summaryrefslogtreecommitdiff
path: root/doc/cha-gtls-examples.texi
blob: 23a488e2fd45c6e571cf44bbaad48c3bd38b779b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
@node GnuTLS application examples
@chapter GnuTLS application examples
@anchor{examples}
@cindex example programs
@cindex examples

In this chapter several examples of real-world use cases are listed.
The examples are simplified to promote readability and contain little or 
no error checking.  

@menu
* Client examples::
* Server examples::
* OCSP example::
* Miscellaneous examples::
* XSSL examples::
@end menu

@node Client examples
@section Client examples

This section contains examples of @acronym{TLS} and @acronym{SSL}
clients, using @acronym{GnuTLS}. Note that some of the examples require functions
implemented by another example.

@menu
* Simple client example with X.509 certificate support::
* Simple client example with SSH-style certificate verification::
* Simple client example with anonymous authentication::
* Simple Datagram TLS client example::
* Obtaining session information::
* Using a callback to select the certificate to use::
* Verifying a certificate::
* Client using a smart card with TLS::
* Client with Resume capability example::
* Simple client example with SRP authentication::
* Simple client example in C++::
* Helper functions for TCP connections::
* Helper functions for UDP connections::
@end menu

@node Simple client example with X.509 certificate support
@subsection Simple client example with @acronym{X.509} certificate support
@anchor{ex:verify}

Let's assume now that we want to create a TCP client which
communicates with servers that use @acronym{X.509} or
@acronym{OpenPGP} certificate authentication. The following client is
a very simple @acronym{TLS} client, which uses the high level verification
functions for certificates, but does not support session
resumption. 

@verbatiminclude examples/ex-client-x509.c

@node Simple client example with SSH-style certificate verification
@subsection Simple client example with SSH-style certificate verification

This is an alternative verification function that will use the
X.509 certificate authorities for verification, but also assume an
trust on first use (SSH-like) authentication system. That is the user is 
prompted on unknown public keys and known public keys are considered 
trusted.

@verbatiminclude examples/ex-verify-ssh.c

@node Simple client example with anonymous authentication
@subsection Simple client example with anonymous authentication

The simplest client using TLS is the one that doesn't do any
authentication.  This means no external certificates or passwords are
needed to set up the connection.  As could be expected, the connection
is vulnerable to man-in-the-middle (active or redirection) attacks.
However, the data are integrity protected and encrypted from
passive eavesdroppers.

Note that due to the vulnerable nature of this method very few public
servers support it.

@verbatiminclude examples/ex-client-anon.c


@node Simple Datagram TLS client example
@subsection Simple datagram @acronym{TLS} client example

This is a client that uses @acronym{UDP} to connect to a
server. This is the @acronym{DTLS} equivalent to the TLS example
with X.509 certificates.

@verbatiminclude examples/ex-client-dtls.c

@node Obtaining session information
@subsection Obtaining session information

Most of the times it is desirable to know the security properties of
the current established session.  This includes the underlying ciphers
and the protocols involved.  That is the purpose of the following
function.  Note that this function will print meaningful values only
if called after a successful @funcref{gnutls_handshake}.

@verbatiminclude examples/ex-session-info.c

@node Using a callback to select the certificate to use
@subsection Using a callback to select the certificate to use

There are cases where a client holds several certificate and key
pairs, and may not want to load all of them in the credentials
structure.  The following example demonstrates the use of the
certificate selection callback.

@verbatiminclude examples/ex-cert-select.c

@node Verifying a certificate
@subsection Verifying a certificate
@anchor{ex:verify2}

An example is listed below which uses the high level verification
functions to verify a given certificate list.

@verbatiminclude examples/ex-verify.c

@node Client using a smart card with TLS
@subsection Using a smart card with TLS
@anchor{ex:pkcs11-client}
@cindex Smart card example

This example will demonstrate how to load keys and certificates
from a smart-card or any other @acronym{PKCS} #11 token, and 
use it in a TLS connection.

@verbatiminclude examples/ex-cert-select-pkcs11.c


@node Client with Resume capability example
@subsection Client with resume capability example
@anchor{ex:resume-client}

This is a modification of the simple client example. Here we
demonstrate the use of session resumption. The client tries to connect
once using @acronym{TLS}, close the connection and then try to
establish a new connection using the previously negotiated data.

@verbatiminclude examples/ex-client-resume.c


@node Simple client example with SRP authentication
@subsection Simple client example with @acronym{SRP} authentication

The following client is a very simple @acronym{SRP} @acronym{TLS}
client which connects to a server and authenticates using a
@emph{username} and a @emph{password}. The server may authenticate
itself using a certificate, and in that case it has to be verified.

@verbatiminclude examples/ex-client-srp.c

@node Simple client example in C++
@subsection Simple client example using the C++ API

The following client is a simple example of a client client utilizing
the GnuTLS C++ API.

@verbatiminclude examples/ex-cxx.cpp

@node Helper functions for TCP connections
@subsection Helper functions for TCP connections

Those helper function abstract away TCP connection handling from the
other examples.  It is required to build some examples.

@verbatiminclude examples/tcp.c

@node Helper functions for UDP connections
@subsection Helper functions for UDP connections

The UDP helper functions abstract away UDP connection handling from the
other examples.  It is required to build the examples using UDP.

@verbatiminclude examples/udp.c

@node Server examples
@section Server examples

This section contains examples of @acronym{TLS} and @acronym{SSL}
servers, using @acronym{GnuTLS}.

@menu
* Echo server with X.509 authentication::
* Echo server with OpenPGP authentication::
* Echo server with SRP authentication::
* Echo server with anonymous authentication::
* DTLS echo server with X.509 authentication::
@end menu

@node Echo server with X.509 authentication
@subsection Echo server with @acronym{X.509} authentication

This example is a very simple echo server which supports
@acronym{X.509} authentication.

@verbatiminclude examples/ex-serv-x509.c

@node Echo server with OpenPGP authentication
@subsection Echo server with @acronym{OpenPGP} authentication
@cindex OpenPGP server

The following example is an echo server which supports
@acronym{OpenPGP} key authentication. You can easily combine
this functionality ---that is have a server that supports both
@acronym{X.509} and @acronym{OpenPGP} certificates--- but we separated
them to keep these examples as simple as possible.

@verbatiminclude examples/ex-serv-pgp.c

@node Echo server with SRP authentication
@subsection Echo server with @acronym{SRP} authentication

This is a server which supports @acronym{SRP} authentication. It is
also possible to combine this functionality with a certificate
server. Here it is separate for simplicity.

@verbatiminclude examples/ex-serv-srp.c

@node Echo server with anonymous authentication
@subsection Echo server with anonymous authentication

This example server supports anonymous authentication, and could be
used to serve the example client for anonymous authentication.

@verbatiminclude examples/ex-serv-anon.c

@node DTLS echo server with X.509 authentication
@subsection DTLS echo server with @acronym{X.509} authentication

This example is a very simple echo server using Datagram TLS and 
@acronym{X.509} authentication.

@verbatiminclude examples/ex-serv-dtls.c


@node OCSP example
@section OCSP example

@anchor{Generate OCSP request}
@subheading Generate @acronym{OCSP} request

A small tool to generate OCSP requests.

@verbatiminclude examples/ex-ocsp-client.c

@node Miscellaneous examples
@section Miscellaneous examples

@menu
* Checking for an alert::
* X.509 certificate parsing example::
* Listing the ciphersuites in a priority string::
* PKCS #12 structure generation example::
@end menu

@node Checking for an alert
@subsection Checking for an alert

This is a function that checks if an alert has been received in the
current session.

@verbatiminclude examples/ex-alert.c

@node X.509 certificate parsing example
@subsection @acronym{X.509} certificate parsing example
@anchor{ex:x509-info}

To demonstrate the @acronym{X.509} parsing capabilities an example program is
listed below.  That program reads the peer's certificate, and prints
information about it.

@verbatiminclude examples/ex-x509-info.c

@node Listing the ciphersuites in a priority string
@subsection Listing the ciphersuites in a priority string

This is a small program to list the enabled ciphersuites by a 
priority string.

@verbatiminclude examples/print-ciphersuites.c

@node PKCS #12 structure generation example
@subsection PKCS #12 structure generation example

This small program demonstrates the usage of the PKCS #12 API, by generating
such a structure.

@verbatiminclude examples/ex-pkcs12.c

@node XSSL examples
@section XSSL examples

XSSL is an experimental API available in the @code{gnutls-xssl} library
and in @code{gnutls/xssl.h} header. It is intended to be a very simple
to use API avoid the GnuTLS API. The API however has the following limitations
@itemize
@item It is applicable to blocking sockets only.
@item The server verification is based on its DNS name.
@end itemize

@menu
* Example client with X.509 certificate authentication::
* Example client with X.509 certificate authentication and TOFU::
@end menu

@node Example client with X.509 certificate authentication
@subsection Example client with X.509 certificate authentication

@verbatiminclude examples/ex-client-xssl1.c

@node Example client with X.509 certificate authentication and TOFU
@subsection Example client with X.509 certificate authentication and TOFU

@verbatiminclude examples/ex-client-xssl2.c