|
Packit |
549fdc |
@node GnuTLS application examples
|
|
Packit |
549fdc |
@chapter GnuTLS application examples
|
|
Packit |
549fdc |
@anchor{examples}
|
|
Packit |
549fdc |
@cindex example programs
|
|
Packit |
549fdc |
@cindex examples
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
In this chapter several examples of real-world use cases are listed.
|
|
Packit |
549fdc |
The examples are simplified to promote readability and contain little or
|
|
Packit |
549fdc |
no error checking.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@menu
|
|
Packit |
549fdc |
* Client examples::
|
|
Packit |
549fdc |
* Server examples::
|
|
Packit |
549fdc |
* OCSP example::
|
|
Packit |
549fdc |
* Miscellaneous examples::
|
|
Packit |
549fdc |
@end menu
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Client examples
|
|
Packit |
549fdc |
@section Client examples
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
This section contains examples of @acronym{TLS} and @acronym{SSL}
|
|
Packit |
549fdc |
clients, using @acronym{GnuTLS}. Note that some of the examples require functions
|
|
Packit |
549fdc |
implemented by another example.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@menu
|
|
Packit |
549fdc |
* Simple client example with X.509 certificate support::
|
|
Packit |
549fdc |
* Simple client example with SSH-style certificate verification::
|
|
Packit |
549fdc |
* Simple client example with anonymous authentication::
|
|
Packit |
549fdc |
* Simple Datagram TLS client example::
|
|
Packit |
549fdc |
* Obtaining session information::
|
|
Packit |
549fdc |
* Using a callback to select the certificate to use::
|
|
Packit |
549fdc |
* Verifying a certificate::
|
|
Packit |
549fdc |
* Client using a smart card with TLS::
|
|
Packit |
549fdc |
* Client with Resume capability example::
|
|
Packit |
549fdc |
* Simple client example with SRP authentication::
|
|
Packit |
549fdc |
* Legacy client example with X.509 certificate support::
|
|
Packit |
549fdc |
* Simple client example in C++::
|
|
Packit |
549fdc |
* Helper functions for TCP connections::
|
|
Packit |
549fdc |
* Helper functions for UDP connections::
|
|
Packit |
549fdc |
@end menu
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Simple client example with X.509 certificate support
|
|
Packit |
549fdc |
@subsection Simple client example with @acronym{X.509} certificate support
|
|
Packit |
549fdc |
@anchor{ex-verify}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
Let's assume now that we want to create a TCP client which
|
|
Packit |
549fdc |
communicates with servers that use @acronym{X.509} certificate authentication.
|
|
Packit |
549fdc |
The following client is a very simple @acronym{TLS} client, which uses
|
|
Packit |
549fdc |
the high level verification functions for certificates, but does not support session
|
|
Packit |
549fdc |
resumption.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
Note that this client utilizes functionality present in the latest GnuTLS
|
|
Packit |
549fdc |
version. For a reasonably portable version see @ref{Legacy client example with X.509 certificate support}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/ex-client-x509.c
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Simple client example with SSH-style certificate verification
|
|
Packit |
549fdc |
@subsection Simple client example with SSH-style certificate verification
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
This is an alternative verification function that will use the
|
|
Packit |
549fdc |
X.509 certificate authorities for verification, but also assume an
|
|
Packit |
549fdc |
trust on first use (SSH-like) authentication system. That is the user is
|
|
Packit |
549fdc |
prompted on unknown public keys and known public keys are considered
|
|
Packit |
549fdc |
trusted.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/ex-verify-ssh.c
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Simple client example with anonymous authentication
|
|
Packit |
549fdc |
@subsection Simple client example with anonymous authentication
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The simplest client using TLS is the one that doesn't do any
|
|
Packit |
549fdc |
authentication. This means no external certificates or passwords are
|
|
Packit |
549fdc |
needed to set up the connection. As could be expected, the connection
|
|
Packit |
549fdc |
is vulnerable to man-in-the-middle (active or redirection) attacks.
|
|
Packit |
549fdc |
However, the data are integrity protected and encrypted from
|
|
Packit |
549fdc |
passive eavesdroppers.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
Note that due to the vulnerable nature of this method very few public
|
|
Packit |
549fdc |
servers support it.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/ex-client-anon.c
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Simple Datagram TLS client example
|
|
Packit |
549fdc |
@subsection Simple datagram @acronym{TLS} client example
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
This is a client that uses @acronym{UDP} to connect to a
|
|
Packit |
549fdc |
server. This is the @acronym{DTLS} equivalent to the TLS example
|
|
Packit |
549fdc |
with X.509 certificates.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/ex-client-dtls.c
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Obtaining session information
|
|
Packit |
549fdc |
@subsection Obtaining session information
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
Most of the times it is desirable to know the security properties of
|
|
Packit |
549fdc |
the current established session. This includes the underlying ciphers
|
|
Packit |
549fdc |
and the protocols involved. That is the purpose of the following
|
|
Packit |
549fdc |
function. Note that this function will print meaningful values only
|
|
Packit |
549fdc |
if called after a successful @funcref{gnutls_handshake}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/ex-session-info.c
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Using a callback to select the certificate to use
|
|
Packit |
549fdc |
@subsection Using a callback to select the certificate to use
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
There are cases where a client holds several certificate and key
|
|
Packit |
549fdc |
pairs, and may not want to load all of them in the credentials
|
|
Packit |
549fdc |
structure. The following example demonstrates the use of the
|
|
Packit |
549fdc |
certificate selection callback.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/ex-cert-select.c
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Verifying a certificate
|
|
Packit |
549fdc |
@subsection Verifying a certificate
|
|
Packit |
549fdc |
@anchor{ex-verify2}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
An example is listed below which uses the high level verification
|
|
Packit |
549fdc |
functions to verify a given certificate list.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/ex-verify.c
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Client using a smart card with TLS
|
|
Packit |
549fdc |
@subsection Using a smart card with TLS
|
|
Packit |
549fdc |
@anchor{ex-pkcs11-client}
|
|
Packit |
549fdc |
@cindex Smart card example
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
This example will demonstrate how to load keys and certificates
|
|
Packit |
549fdc |
from a smart-card or any other @acronym{PKCS} #11 token, and
|
|
Packit |
549fdc |
use it in a TLS connection.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/ex-cert-select-pkcs11.c
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Client with Resume capability example
|
|
Packit |
549fdc |
@subsection Client with resume capability example
|
|
Packit |
549fdc |
@anchor{ex-resume-client}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
This is a modification of the simple client example. Here we
|
|
Packit |
549fdc |
demonstrate the use of session resumption. The client tries to connect
|
|
Packit |
549fdc |
once using @acronym{TLS}, close the connection and then try to
|
|
Packit |
549fdc |
establish a new connection using the previously negotiated data.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/ex-client-resume.c
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Simple client example with SRP authentication
|
|
Packit |
549fdc |
@subsection Simple client example with @acronym{SRP} authentication
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The following client is a very simple @acronym{SRP} @acronym{TLS}
|
|
Packit |
549fdc |
client which connects to a server and authenticates using a
|
|
Packit |
549fdc |
@emph{username} and a @emph{password}. The server may authenticate
|
|
Packit |
549fdc |
itself using a certificate, and in that case it has to be verified.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/ex-client-srp.c
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Legacy client example with X.509 certificate support
|
|
Packit |
549fdc |
@subsection Legacy client example with @acronym{X.509} certificate support
|
|
Packit |
549fdc |
@anchor{ex-verify-legacy}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
For applications that need to maintain compatibility with the GnuTLS 3.1.x
|
|
Packit |
549fdc |
library, this client example is identical to @ref{Simple client example with X.509 certificate support}
|
|
Packit |
549fdc |
but utilizes APIs that were available in GnuTLS 3.1.4.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/ex-client-x509-3.1.c
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Simple client example in C++
|
|
Packit |
549fdc |
@subsection Simple client example using the C++ API
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The following client is a simple example of a client client utilizing
|
|
Packit |
549fdc |
the GnuTLS C++ API.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/ex-cxx.cpp
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Helper functions for TCP connections
|
|
Packit |
549fdc |
@subsection Helper functions for TCP connections
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
Those helper function abstract away TCP connection handling from the
|
|
Packit |
549fdc |
other examples. It is required to build some examples.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/tcp.c
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Helper functions for UDP connections
|
|
Packit |
549fdc |
@subsection Helper functions for UDP connections
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
The UDP helper functions abstract away UDP connection handling from the
|
|
Packit |
549fdc |
other examples. It is required to build the examples using UDP.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/udp.c
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Server examples
|
|
Packit |
549fdc |
@section Server examples
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
This section contains examples of @acronym{TLS} and @acronym{SSL}
|
|
Packit |
549fdc |
servers, using @acronym{GnuTLS}.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@menu
|
|
Packit |
549fdc |
* Echo server with X.509 authentication::
|
|
Packit |
549fdc |
* Echo server with SRP authentication::
|
|
Packit |
549fdc |
* Echo server with anonymous authentication::
|
|
Packit |
549fdc |
* DTLS echo server with X.509 authentication::
|
|
Packit |
549fdc |
@end menu
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Echo server with X.509 authentication
|
|
Packit |
549fdc |
@subsection Echo server with @acronym{X.509} authentication
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
This example is a very simple echo server which supports
|
|
Packit |
549fdc |
@acronym{X.509} authentication.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/ex-serv-x509.c
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Echo server with SRP authentication
|
|
Packit |
549fdc |
@subsection Echo server with @acronym{SRP} authentication
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
This is a server which supports @acronym{SRP} authentication. It is
|
|
Packit |
549fdc |
also possible to combine this functionality with a certificate
|
|
Packit |
549fdc |
server. Here it is separate for simplicity.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/ex-serv-srp.c
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Echo server with anonymous authentication
|
|
Packit |
549fdc |
@subsection Echo server with anonymous authentication
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
This example server supports anonymous authentication, and could be
|
|
Packit |
549fdc |
used to serve the example client for anonymous authentication.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/ex-serv-anon.c
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node DTLS echo server with X.509 authentication
|
|
Packit |
549fdc |
@subsection DTLS echo server with @acronym{X.509} authentication
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
This example is a very simple echo server using Datagram TLS and
|
|
Packit |
549fdc |
@acronym{X.509} authentication.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/ex-serv-dtls.c
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node OCSP example
|
|
Packit |
549fdc |
@section OCSP example
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@anchor{Generate OCSP request}
|
|
Packit |
549fdc |
@subheading Generate @acronym{OCSP} request
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
A small tool to generate OCSP requests.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/ex-ocsp-client.c
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Miscellaneous examples
|
|
Packit |
549fdc |
@section Miscellaneous examples
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@menu
|
|
Packit |
549fdc |
* Checking for an alert::
|
|
Packit |
549fdc |
* X.509 certificate parsing example::
|
|
Packit |
549fdc |
* Listing the ciphersuites in a priority string::
|
|
Packit |
549fdc |
* PKCS12 structure generation example::
|
|
Packit |
549fdc |
@end menu
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Checking for an alert
|
|
Packit |
549fdc |
@subsection Checking for an alert
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
This is a function that checks if an alert has been received in the
|
|
Packit |
549fdc |
current session.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/ex-alert.c
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node X.509 certificate parsing example
|
|
Packit |
549fdc |
@subsection @acronym{X.509} certificate parsing example
|
|
Packit |
549fdc |
@anchor{ex-x509-info}
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
To demonstrate the @acronym{X.509} parsing capabilities an example program is
|
|
Packit |
549fdc |
listed below. That program reads the peer's certificate, and prints
|
|
Packit |
549fdc |
information about it.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/ex-x509-info.c
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node Listing the ciphersuites in a priority string
|
|
Packit |
549fdc |
@subsection Listing the ciphersuites in a priority string
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
This is a small program to list the enabled ciphersuites by a
|
|
Packit |
549fdc |
priority string.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/print-ciphersuites.c
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@node PKCS12 structure generation example
|
|
Packit |
549fdc |
@subsection PKCS #12 structure generation example
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
This small program demonstrates the usage of the PKCS #12 API, by generating
|
|
Packit |
549fdc |
such a structure.
|
|
Packit |
549fdc |
|
|
Packit |
549fdc |
@verbatiminclude examples/ex-pkcs12.c
|
|
Packit |
549fdc |
|