doc/cha-gtls-examples.texi

   1 @node GnuTLS application examples
   2 @chapter GnuTLS application examples
   3 @anchor{examples}
   4 @cindex example programs
   5 @cindex examples
   6
   7 In this chapter several examples of real-world use cases are listed.
   8 The examples are simplified to promote readability and contain little or
   9 no error checking.
  10
  11 @menu
  12 * Client examples::
  13 * Server examples::
  14 * OCSP example::
  15 * Miscellaneous examples::
  16 @end menu
  17
  18 @node Client examples
  19 @section Client examples
  20
  21 This section contains examples of @acronym{TLS} and @acronym{SSL}
  22 clients, using @acronym{GnuTLS}. Note that some of the examples require functions
  23 implemented by another example.
  24
  25 @menu
  26 * Simple client example with anonymous authentication::
  27 * Simple client example with X.509 certificate support::
  28 * Simple client example with SSH-style certificate verification::
  29 * Simple Datagram TLS client example::
  30 * Obtaining session information::
  31 * Using a callback to select the certificate to use::
  32 * Verifying a certificate::
  33 * Client using a smart card with TLS::
  34 * Client with Resume capability example::
  35 * Simple client example with SRP authentication::
  36 * Simple client example in C++::
  37 * Helper functions for TCP connections::
  38 * Helper functions for UDP connections::
  39 @end menu
  40
  41 @node Simple client example with anonymous authentication
  42 @subsection Simple client example with anonymous authentication
  43
  44 The simplest client using TLS is the one that doesn't do any
  45 authentication.  This means no external certificates or passwords are
  46 needed to set up the connection.  As could be expected, the connection
  47 is vulnerable to man-in-the-middle (active or redirection) attacks.
  48 However, the data are integrity protected and encrypted from
  49 passive eavesdroppers.
  50
  51 Note that the server must support anonymous authentication as well.
  52
  53 @verbatiminclude examples/ex-client-anon.c
  54
  55 @node Simple client example with X.509 certificate support
  56 @subsection Simple client example with @acronym{X.509} certificate support
  57 @anchor{ex:verify}
  58
  59 Let's assume now that we want to create a TCP client which
  60 communicates with servers that use @acronym{X.509} or
  61 @acronym{OpenPGP} certificate authentication. The following client is
  62 a very simple @acronym{TLS} client, which uses the high level verification
  63 functions for certificates, but does not support session
  64 resumption.
  65
  66 @verbatiminclude examples/ex-client-x509.c
  67
  68 @node Simple client example with SSH-style certificate verification
  69 @subsection Simple client example with SSH-style certificate verification
  70
  71 This is an alternative verification function that will use the
  72 X.509 certificate authorities for verification, but also assume an
  73 trust on first use (SSH-like) authentication system. That is the user is
  74 prompted on unknown public keys and known public keys are considered
  75 trusted.
  76
  77 @verbatiminclude examples/ex-verify-ssh.c
  78
  79 @node Simple Datagram TLS client example
  80 @subsection Simple datagram @acronym{TLS} client example
  81
  82 This is a client that uses @acronym{UDP} to connect to a
  83 server. This is the @acronym{DTLS} equivalent to the TLS example
  84 with X.509 certificates.
  85
  86 @verbatiminclude examples/ex-client-dtls.c
  87
  88 @node Obtaining session information
  89 @subsection Obtaining session information
  90
  91 Most of the times it is desirable to know the security properties of
  92 the current established session.  This includes the underlying ciphers
  93 and the protocols involved.  That is the purpose of the following
  94 function.  Note that this function will print meaningful values only
  95 if called after a successful @funcref{gnutls_handshake}.
  96
  97 @verbatiminclude examples/ex-session-info.c
  98
  99 @node Using a callback to select the certificate to use
 100 @subsection Using a callback to select the certificate to use
 101
 102 There are cases where a client holds several certificate and key
 103 pairs, and may not want to load all of them in the credentials
 104 structure.  The following example demonstrates the use of the
 105 certificate selection callback.
 106
 107 @verbatiminclude examples/ex-cert-select.c
 108
 109 @node Verifying a certificate
 110 @subsection Verifying a certificate
 111 @anchor{ex:verify2}
 112
 113 An example is listed below which uses the high level verification
 114 functions to verify a given certificate list.
 115
 116 @verbatiminclude examples/ex-verify.c
 117
 118 @node Client using a smart card with TLS
 119 @subsection Using a smart card with TLS
 120 @anchor{ex:pkcs11-client}
 121 @cindex Smart card example
 122
 123 This example will demonstrate how to load keys and certificates
 124 from a smart-card or any other @acronym{PKCS} #11 token, and
 125 use it in a TLS connection.
 126
 127 @verbatiminclude examples/ex-cert-select-pkcs11.c
 128
 129
 130 @node Client with Resume capability example
 131 @subsection Client with resume capability example
 132 @anchor{ex:resume-client}
 133
 134 This is a modification of the simple client example. Here we
 135 demonstrate the use of session resumption. The client tries to connect
 136 once using @acronym{TLS}, close the connection and then try to
 137 establish a new connection using the previously negotiated data.
 138
 139 @verbatiminclude examples/ex-client-resume.c
 140
 141
 142 @node Simple client example with SRP authentication
 143 @subsection Simple client example with @acronym{SRP} authentication
 144
 145 The following client is a very simple @acronym{SRP} @acronym{TLS}
 146 client which connects to a server and authenticates using a
 147 @emph{username} and a @emph{password}. The server may authenticate
 148 itself using a certificate, and in that case it has to be verified.
 149
 150 @verbatiminclude examples/ex-client-srp.c
 151
 152 @node Simple client example in C++
 153 @subsection Simple client example using the C++ API
 154
 155 The following client is a simple example of a client client utilizing
 156 the GnuTLS C++ API.
 157
 158 @verbatiminclude examples/ex-cxx.cpp
 159
 160 @node Helper functions for TCP connections
 161 @subsection Helper functions for TCP connections
 162
 163 Those helper function abstract away TCP connection handling from the
 164 other examples.  It is required to build some examples.
 165
 166 @verbatiminclude examples/tcp.c
 167
 168 @node Helper functions for UDP connections
 169 @subsection Helper functions for UDP connections
 170
 171 The UDP helper functions abstract away UDP connection handling from the
 172 other examples.  It is required to build the examples using UDP.
 173
 174 @verbatiminclude examples/udp.c
 175
 176 @node Server examples
 177 @section Server examples
 178
 179 This section contains examples of @acronym{TLS} and @acronym{SSL}
 180 servers, using @acronym{GnuTLS}.
 181
 182 @menu
 183 * Echo server with X.509 authentication::
 184 * Echo server with OpenPGP authentication::
 185 * Echo server with SRP authentication::
 186 * Echo server with anonymous authentication::
 187 * DTLS echo server with X.509 authentication::
 188 @end menu
 189
 190 @node Echo server with X.509 authentication
 191 @subsection Echo server with @acronym{X.509} authentication
 192
 193 This example is a very simple echo server which supports
 194 @acronym{X.509} authentication.
 195
 196 @verbatiminclude examples/ex-serv-x509.c
 197
 198 @node Echo server with OpenPGP authentication
 199 @subsection Echo server with @acronym{OpenPGP} authentication
 200 @cindex OpenPGP server
 201
 202 The following example is an echo server which supports
 203 @acronym{OpenPGP} key authentication. You can easily combine
 204 this functionality ---that is have a server that supports both
 205 @acronym{X.509} and @acronym{OpenPGP} certificates--- but we separated
 206 them to keep these examples as simple as possible.
 207
 208 @verbatiminclude examples/ex-serv-pgp.c
 209
 210 @node Echo server with SRP authentication
 211 @subsection Echo server with @acronym{SRP} authentication
 212
 213 This is a server which supports @acronym{SRP} authentication. It is
 214 also possible to combine this functionality with a certificate
 215 server. Here it is separate for simplicity.
 216
 217 @verbatiminclude examples/ex-serv-srp.c
 218
 219 @node Echo server with anonymous authentication
 220 @subsection Echo server with anonymous authentication
 221
 222 This example server supports anonymous authentication, and could be
 223 used to serve the example client for anonymous authentication.
 224
 225 @verbatiminclude examples/ex-serv-anon.c
 226
 227 @node DTLS echo server with X.509 authentication
 228 @subsection DTLS echo server with @acronym{X.509} authentication
 229
 230 This example is a very simple echo server using Datagram TLS and
 231 @acronym{X.509} authentication.
 232
 233 @verbatiminclude examples/ex-serv-dtls.c
 234
 235
 236 @node OCSP example
 237 @section OCSP example
 238
 239 @anchor{Generate OCSP request}
 240 @subheading Generate @acronym{OCSP} request
 241
 242 A small tool to generate OCSP requests.
 243
 244 @verbatiminclude examples/ex-ocsp-client.c
 245
 246 @node Miscellaneous examples
 247 @section Miscellaneous examples
 248
 249 @menu
 250 * Checking for an alert::
 251 * X.509 certificate parsing example::
 252 * Listing the ciphersuites in a priority string::
 253 @end menu
 254
 255 @node Checking for an alert
 256 @subsection Checking for an alert
 257
 258 This is a function that checks if an alert has been received in the
 259 current session.
 260
 261 @verbatiminclude examples/ex-alert.c
 262
 263 @node X.509 certificate parsing example
 264 @subsection @acronym{X.509} certificate parsing example
 265 @anchor{ex:x509-info}
 266
 267 To demonstrate the @acronym{X.509} parsing capabilities an example program is
 268 listed below.  That program reads the peer's certificate, and prints
 269 information about it.
 270
 271 @verbatiminclude examples/ex-x509-info.c
 272
 273 @node Listing the ciphersuites in a priority string
 274 @subsection Listing the ciphersuites in a priority string
 275
 276 This is a small program to list the enabled ciphersuites by a
 277 priority string.
 278
 279 @verbatiminclude examples/print-ciphersuites.c