path: root/doc/cha-gtls-examples.texi

@node GnuTLS application examples
@chapter GnuTLS application examples
@anchor{examples}
@cindex example programs
@cindex examples

@menu
* Client examples::
* Server examples::
* Miscellaneous 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 these examples contain
little or no error checking.  Some of the examples require functions
implemented by another example.

@menu
* Simple client example with anonymous authentication::
* Simple client example with X.509 certificate support::
* Simple Datagram TLS client example::
* Obtaining session information::
* Using a callback to select the certificate to use::
* Verifying a certificate::
* Client using a PKCS 11 token with TLS::
* Client with Resume capability example::
* Simple client example with SRP authentication::
* Simple client example in C++::
* Helper function for TCP connections::
@end menu

@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 is integrity and privacy protected.

@verbatiminclude examples/ex-client1.c

@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-rfc2818.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 example
in @ref{Simple client example with X.509 certificate support}.

@verbatiminclude examples/ex-client-udp.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 PKCS 11 token with TLS
@subsection Using a @acronym{PKCS} #11 token with TLS
@anchor{ex:pkcs11-client}

This example will demonstrate how to load keys and certificates
from a @acronym{PKCS} #11 token, and use it with 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 function for TCP connections
@subsection Helper function for TCP connections

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

@verbatiminclude examples/tcp.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::
* Echo DTLS 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-serv1.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 support anonymous authentication, and could be
used to serve the example client for anonymous authentication.

@verbatiminclude examples/ex-serv-anon.c

@node Echo DTLS server with X.509 authentication
@subsection Echo DTLS 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 Miscellaneous examples
@section Miscellaneous examples

@menu
* Checking for an alert::
* X.509 certificate parsing 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