GnuTLS application 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.

Client examples
===============

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

Simple client example with X.509 certificate support
----------------------------------------------------

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

     [file ex-client-x509.c not included]

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.

     [file ex-verify-ssh.c not included]

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.

     [file ex-client-anon.c not included]

Simple datagram TLS client example
----------------------------------

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

     [file ex-client-dtls.c not included]

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 gnutls_handshake.

     [file ex-session-info.c not included]

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.

     [file ex-cert-select.c not included]

Verifying a certificate
-----------------------

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

     [file ex-verify.c not included]

Using a smart card with TLS
---------------------------

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

     [file ex-cert-select-pkcs11.c not included]

Client with resume capability example
-------------------------------------

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

     [file ex-client-resume.c not included]

Simple client example with SRP authentication
---------------------------------------------

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

     [file ex-client-srp.c not included]

Simple client example using the C++ API
---------------------------------------

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

     [file ex-cxx.cpp not included]

Helper functions for TCP connections
------------------------------------

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

     [file tcp.c not included]

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.

     [file udp.c not included]

Server examples
===============

This section contains examples of TLS and SSL servers, using GnuTLS.

Echo server with X.509 authentication
-------------------------------------

This example is a very simple echo server which supports X.509 authentication.

     [file ex-serv-x509.c not included]

Echo server with OpenPGP authentication
---------------------------------------

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

     [file ex-serv-pgp.c not included]

Echo server with SRP authentication
-----------------------------------

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

     [file ex-serv-srp.c not included]

Echo server with anonymous authentication
-----------------------------------------

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

     [file ex-serv-anon.c not included]

DTLS echo server with X.509 authentication
------------------------------------------

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

     [file ex-serv-dtls.c not included]

OCSP example
============

Generate OCSP request
---------------------

A small tool to generate OCSP requests.

     [file ex-ocsp-client.c not included]

Miscellaneous examples
======================

Checking for an alert
---------------------

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

     [file ex-alert.c not included]

X.509 certificate parsing example
---------------------------------

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

     [file ex-x509-info.c not included]

Listing the ciphersuites in a priority string
---------------------------------------------

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

     [file print-ciphersuites.c not included]

PKCS #12 structure generation example
-------------------------------------

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

     [file ex-pkcs12.c not included]