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