How to use GnuTLS in applications
*********************************

Preparation
===========

To use GnuTLS, you have to perform some changes to your sources and your build system. The necessary changes are explained in the following subsections.

Headers
-------

All the data types and functions of the GnuTLS library are defined in the header file gnutls/gnutls.h.  This must be included in all programs that make use of the GnuTLS library.

The extra functionality of the GnuTLS-extra library is available by including the header file gnutls/extra.h in your programs.

Initialization
--------------

GnuTLS must be initialized before it can be used.  The library is initialized by calling gnutls_global_init.  The resources allocated by the initialization process can be released if the application no longer has a need to call GnuTLS functions, this is done by calling gnutls_global_deinit.

The extra functionality of the GnuTLS-extra library is available after calling gnutls_global_init_extra.

In order to take advantage of the internationalization features in GnuTLS, such as translated error messages, the application must set the current locale using setlocale before initializing GnuTLS.

Version check
-------------

It is often desirable to check that the version of `gnutls' used is indeed one which fits all requirements.  Even with binary compatibility new features may have been introduced but due to problem with the dynamic linker an old version is actually used.  So you may want to check that the version is okay right after program start-up. See the function gnutls_check_version.

Building the source
-------------------

If you want to compile a source file including the gnutls/gnutls.h header file, you must make sure that the compiler can find it in the directory hierarchy.  This is accomplished by adding the path to the directory in which the header file is located to the compilers include file search path (via the -I option).

However, the path to the include file is determined at the time the source is configured.  To solve this problem, the library uses the external package pkg-config that knows the path to the include file and other configuration options.  The options that need to be added to the compiler invocation at compile time are output by the --cflags option to pkg-config gnutls.  The following example shows how it can be used at the command line:

     gcc -c foo.c `pkg-config gnutls --cflags`

Adding the output of pkg-config gnutls --cflags to the compilers command line will ensure that the compiler can find the gnutls/gnutls.h header file.

A similar problem occurs when linking the program with the library. Again, the compiler has to find the library files.  For this to work, the path to the library files has to be added to the library search path (via the -L option).  For this, the option --libs to pkg-config gnutls can be used.  For convenience, this option also outputs all other options that are required to link the program with the library (for instance, the -ltasn1 option).  The example shows how to link foo.o with the library to a program foo.

     gcc -o foo foo.o `pkg-config gnutls --libs`

Of course you can also combine both examples to a single command by specifying both options to pkg-config:

     gcc -o foo foo.c `pkg-config gnutls --cflags --libs`

TLS and DTLS sessions
=====================

Session initialization
----------------------

In the previous sections we have discussed the global initialization required for GnuTLS as well as the initialization required for each authentication method's credentials (see Authentication methods). In this section we elaborate on the TLS or DTLS session initiation. Each session is initialized using gnutls_init which among others is used to specify the type of the connection (server or client), and the underlying protocol type, i.e., datagram (UDP) or reliable (TCP).

gnutls_init

After the session initialization details on the allowed ciphersuites and protocol versions should be set using the priority functions such as gnutls_priority_set_direct. We elaborate on them in Priority Strings. The credentials used for the key exchange method, such as certificates or usernames and passwords should also be associated with the session current session using gnutls_credentials_set (see Authentication methods).

Setting up the transport layer
------------------------------

The next step is to setup the underlying transport layer details. The Berkeley sockets are implicitly used by GnuTLS, thus a call to gnutls_transport_set_ptr2 would be sufficient to specify the socket descriptor.

gnutls_transport_set_ptr2

gnutls_transport_set_ptr

If however another transport layer than TCP is selected, then the following functions have to be specified.

gnutls_transport_set_push_function gnutls_transport_set_vec_push_function gnutls_transport_set_pull_function

The functions above accept a callback function which should return the number of bytes written, or -1 on error and should set errno appropriately. In some environments, setting errno is unreliable. For example Windows have several errno variables in different CRTs, or in other systems it may be a non thread-local variable.  If this is a concern to you, call gnutls_transport_set_errno with the intended errno value instead of setting errno directly.

gnutls_transport_set_errno

GnuTLS currently only interprets the EINTR and EAGAIN errno values and returns the corresponding GnuTLS error codes:

  * GNUTLS_E_INTERRUPTED

  * GNUTLS_E_AGAIN

The EINTR and EAGAIN values are returned by interrupted system calls, or when non blocking IO is used.  All GnuTLS functions can be resumed (called again), if any of the above error codes is returned.

In the case of DTLS it is also desirable to override the generic transport functions with functions that emulate the operation of recvfrom and sendto. In addition DTLS requires timers during the receive of a handshake message. This requires the following function to be used.

gnutls_transport_set_pull_timeout_function

Handshake
---------

Once a session has been initialized and a network connection has been set up, TLS and DTLS protocols perform a handshake. The handshake is the actual key exchange.

gnutls_handshake

The handshake process doesn't ensure the verification of the peer's identity. When certificates are in use, this can be done, either after the handshake is complete, or during the handshake if gnutls_certificate_set_verify_function has been used. In both cases the following function can be used to verify the peer's certificate (see Certificate authentication for more information).

gnutls_certificate_verify_peers2

Data transfer and termination
-----------------------------

Once the handshake is complete and peer's identity has been verified data can be exchanged. The available functions resemble the POSIX recv and send functions.

gnutls_record_send

gnutls_record_recv

In DTLS it is adviceable to use the extended receive function shown below, because it allows the extraction of the sequence number. This is required in DTLS because messages may arrive out of order.

gnutls_record_recv_seq

A helper function is available to check whether data to be read are pending in a GnuTLS session. This is the equivalent of select in POSIX systems.

gnutls_record_check_pending

Once a TLS or DTLS session is no longer needed, it is recommended to use gnutls_bye to terminate the session. That way the peer is notified securely about the intention of termination, which allows distinguishing it from a malicious connection termination.

gnutls_bye

A session can be deinitialized using the following function.

gnutls_deinit

Asynchronous operation
----------------------

GnuTLS can be used with asynchronous socket or event-driven programming. During a TLS protocol session GnuTLS does not block for anything except calculations. The only blocking operations are due to the transport layer (sockets) functions. Those, however, in an asynchronous scenario are typically set to non-blocking mode, which forces them to return EAGAIN error code instead of blocking. In that case GnuTLS functions will return the GNUTLS_E_AGAIN error code and can be resumed the same way as a system call would. The only exception is gnutls_record_send, which if interrupted subsequent calls need not to include the data to be sent (can be called with NULL argument).

The select system call can also be used in combination with the GnuTLS functions. select allows monitoring of sockets and notifies on them being ready for reading or writing data. Note however that this system call cannot notify on data present in GnuTLS read buffers, it is only applicable to the kernel sockets API. Thus if you are using it for reading from a GnuTLS session, make sure the session is read completely. That can be achieved by checking there are no data waiting to be read (using gnutls_record_check_pending), either before the select system call, or after a call to gnutls_record_recv. GnuTLS does not keep a write buffer, thus when writing select need only to be consulted.

In the DTLS, however, GnuTLS might block due to timers required by the protocol. To prevent those timers from blocking a DTLS handshake, the gnutls_init should be called with the GNUTLS_NONBLOCK flag (see TLS and DTLS sessions).

DTLS sessions
-------------

Because datagram TLS can operate over connections where the peer of a server cannot be reliably verified, functionality is available to prevent denial of service attacks. GnuTLS requires a server to generate a secret key that is used to sign a cookie (A key of 128 bits or 16 bytes should be sufficient for this purpose.). That cookie is sent to the client using gnutls_dtls_cookie_send, and the client must reply using the correct cookie. The server side should verify the initial message sent by client using gnutls_dtls_cookie_verify, if successful associate a session with the cookie using gnutls_dtls_prestate_set and proceed to a proper handshake.

gnutls_key_generate

gnutls_dtls_cookie_send

gnutls_dtls_cookie_verify

gnutls_dtls_prestate_set

Note that the above apply to server side only and they are not mandatory to be used. Not using them, however, allows denial of service attacks. The client side cookie handling is part of gnutls_handshake.

Datagrams are typically restricted by a maximum transfer unit (MTU). For that both client and server side should set the correct maximum transfer unit for the layer underneath GnuTLS. This would allow proper fragmentation of DTLS messages and prevent messages from being silently discarded by the transport layer. The ``correct'' maximum transfer unit can be obtained through a path MTU discovery mechanism RFC4821.

gnutls_dtls_set_mtu

gnutls_dtls_get_mtu gnutls_dtls_get_data_mtu

Priority strings
================

In order to specify cipher suite preferences on client or server side, the previously mentioned priority functions accept a string that specifies the enabled for the handshake algorithms. That string may contain some high level keyword such as the keywords in tab:prio-keywords or it might contain special keywords, to be explained later on.

gnutls_priority_set_direct,gnutls_priority_init,gnutls_priority_deinit,gnutls_priority_set

Keyword   Description
PERFORMANCE
All the "secure" ciphersuites are enabled,
limited to 128 bit ciphers and sorted by terms of speed
performance.

NORMAL
Means all "secure" ciphersuites. The 256-bit ciphers are
included as a fallback only.  The ciphers are sorted by security
margin.

SECURE128
Means all "secure" ciphersuites of security level 128-bit
or more.

SECURE192
Means all "secure" ciphersuites of security level 192-bit
or more.

SUITEB128
Means all the NSA Suite B cryptography (RFC5430) ciphersuites
with an 128 bit security level.

SUITEB192
Means all the NSA Suite B cryptography (RFC5430) ciphersuites
with an 192 bit security level.

EXPORT
Means all ciphersuites are enabled, including the
low-security 40 bit ciphers.

NONE
Means nothing is enabled.  This disables even protocols and
compression methods. It should be followed by the
algorithms to be enabled.

Table: Supported priority string keywords.

Unless the first keyword is "NONE" the defaults (in preference order) are for TLS protocols TLS 1.2, TLS1.1, TLS1.0, SSL3.0; for compression NULL; for certificate types X.509, OpenPGP. For key exchange algorithms when in NORMAL or SECURE levels the perfect forward secrecy algorithms take precedence of the other protocols.  In all cases all the supported key exchange algorithms are enabled (except for the RSA-EXPORT which is only enabled in EXPORT level).

The NONE keyword must followed by the algorithms to be enabled, and is used to provide the exact list of requested algorithms (To avoid collisions in order to specify a compression algorithm in this string you have to prefix it with "COMP-", protocol versions with "VERS-", signature algorithms with "SIGN-" and certificate types with "CTYPE-". All other algorithms don't need a prefix.). The order with which every algorithm is specified is significant. Similar algorithms specified before others will take precedence. The individual algorithms are shown in tab:prio-algorithms and special keywords are in tab:prio-special. The prefixes for individual algorithms are:

'!' or '-'
     appended with an algorithm will remove this algorithm.

"+"
     appended with an algorithm will add this algorithm.

Type   Keywords
Ciphers
AES-128-CBC, AES-256-CBC, AES-128-GCM, CAMELLIA-128-CBC,
CAMELLIA-256-CBC, ARCFOUR-128, 3DES-CBC ARCFOUR-40. Catch all
name is CIPHER-ALL which will add all the algorithms from NORMAL
priority.

Key exchange
RSA, DHE-RSA, DHE-DSS, SRP, SRP-RSA, SRP-DSS,
PSK, DHE-PSK, ECDHE-RSA, ANON-ECDH, ANON-DH, RSA-EXPORT. The
Catch all name is KX-ALL which will add all the algorithms from NORMAL
priority.

MAC
MD5, SHA1, SHA256, AEAD (used with
GCM ciphers only). All algorithms from NORMAL priority can be accessed with MAC-ALL.

Compression algorithms
COMP-NULL, COMP-DEFLATE. Catch all is COMP-ALL.

TLS versions
VERS-SSL3.0, VERS-TLS1.0, VERS-TLS1.1,
VERS-TLS1.2. Catch all is VERS-TLS-ALL.

Signature algorithms
SIGN-RSA-SHA1, SIGN-RSA-SHA224,
SIGN-RSA-SHA256, SIGN-RSA-SHA384, SIGN-RSA-SHA512, SIGN-DSA-SHA1,
SIGN-DSA-SHA224, SIGN-DSA-SHA256, SIGN-RSA-MD5. Catch all
is SIGN-ALL. This is only valid for TLS 1.2 and later.

Elliptic curves
CURVE-SECP224R1, CURVE-SECP256R1, CURVE-SECP384R1, CURVE-SECP521R1. Catch all is CURVE-ALL.

Table: The supported priority strings.

Keyword   Description

%COMPAT
will enable compatibility mode. It might mean that violations
of the protocols are allowed as long as maximum compatibility with
problematic clients and servers is achieved.

%NO_EXTENSIONS
will prevent the sending of any TLS extensions in client side. Note
that TLS 1.2 requires extensions to be used, thus this option must
be used with care.

%DISABLE_SAFE_RENEGOTIATION
will disable safe renegotiation
completely.  Do not use unless you know what you are doing.
Testing purposes only.

%UNSAFE_RENEGOTIATION
will allow handshakes and re-handshakes
without the safe renegotiation extension.  Note that for clients
this mode is insecure (you may be under attack), and for servers it
will allow insecure clients to connect (which could be fooled by an
attacker).  Do not use unless you know what you are doing and want
maximum compatibility.

%PARTIAL_RENEGOTIATION
will allow initial handshakes to proceed,
but not re-handshakes.  This leaves the client vulnerable to attack,
and servers will be compatible with non-upgraded clients for
initial handshakes.  This is currently the default for clients and
servers, for compatibility reasons.

%SAFE_RENEGOTIATION
will enforce safe renegotiation.  Clients and
servers will refuse to talk to an insecure peer.  Currently this
causes interoperability problems, but is required for full protection.

%SSL3_RECORD_VERSION
will use SSL3.0 record version in client hello.
This is the default.

%LATEST_RECORD_VERSION
will use the latest TLS version record version in client hello.

%VERIFY_ALLOW_SIGN_RSA_MD5
will allow RSA-MD5 signatures in certificate chains.

%VERIFY_ALLOW_X509_V1_CA_CRT
will allow V1 CAs in chains.

Table: Special priority string keywords.

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

This section contains examples of TLS and SSL clients, using GnuTLS.  Note that these examples contain little or no error checking.  Some of the examples require functions implemented by another example.

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.

     [file ex-client1.c not included]

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, it does not support session resuming, not even certificate verification. The TCP functions defined in this example are used in most of the other examples below, without redefining them.

     [file ex-client2.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 example in Simple client example with X.509 certificate support.

     [file ex-client-udp.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]

Verifying peer's certificate
----------------------------

A TLS session is not secure just after the handshake procedure has finished.  It must be considered secure, only after the peer's certificate and identity have been verified. That is, you have to verify the signature in peer's certificate, the hostname in the certificate, and expiration dates.  Just after this step you should treat the connection as being a secure one.

     [file ex-rfc2818.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 PKCS #11 token with TLS
-------------------------------

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

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

     [file tcp.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, using the RSA ciphersuites.

     [file ex-serv1.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 support anonymous authentication, and could be used to serve the example client for anonymous authentication.

     [file ex-serv-anon.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]

Advanced and other topics
=========================

Parameter generation
--------------------

Several TLS ciphersuites require additional parameters that need to be generated or provided by the application. The Diffie-Hellman based ciphersuites (ANON-DH or DHE), require the group parameters to be provided. Those can either be be generated on the fly using gnutls_dh_params_generate2 or imported from pregenerated data using gnutls_dh_params_import_pkcs3. The parameters can be used in a TLS session by calling gnutls_certificate_set_dh_params or gnutls_anon_set_server_dh_params for anonymous sessions.

gnutls_dh_params_init,gnutls_dh_params_deinit

gnutls_dh_params_generate2,gnutls_dh_params_import_pkcs3,gnutls_certificate_set_dh_params,gnutls_anon_set_server_dh_params

Due to the time-consuming calculations required for the generation of Diffie-Hellman parameters we suggest against performing generation of them within an application. The certtool tool can be used to generate or export known safe values that can be stored in code or in a configuration file to provide the ability to replace. We also recommend the usage of gnutls_sec_param_to_pk_bits (see Selecting cryptographic key sizes) to determine the bit size of the generated parameters.

The ciphersuites that involve the RSA-EXPORT key exchange require additional parameters. Those ciphersuites are rarely used today because they are by design insecure, thus if you have no requirement for them, the rest of this section can be skipped. The RSA-EXPORT key exchange requires 512-bit RSA keys to be generated. It is recommended those parameters to be refreshed (regenerated) in short intervals. The following functions can be used for these parameters.

gnutls_rsa_params_init,gnutls_rsa_params_deinit

gnutls_rsa_params_generate2,gnutls_certificate_set_rsa_export_params,gnutls_rsa_params_import_pkcs1,gnutls_rsa_params_export_pkcs1

To allow renewal of the parameters within an application without accessing the credentials, which are a shared structure, an alternative interface is available using a callback function.

gnutls_certificate_set_params_function

Keying material exporters
-------------------------

The TLS PRF can be used by other protocols to derive data.  The API to use is gnutls_prf.  The function needs to be provided with the label in the parameter label, and the extra data to mix in the extra parameter.  Depending on whether you want to mix in the client or server random data first, you can set the server_random_first parameter.

For example, after establishing a TLS session using gnutls_handshake, you can invoke the TLS PRF with this call:

     #define MYLABEL "EXPORTER-FOO"
     #define MYCONTEXT "some context data"
     char out[32];
     rc = gnutls_prf (session, strlen (MYLABEL), MYLABEL, 0,
                      strlen (MYCONTEXT), MYCONTEXT, 32, out);

If you don't want to mix in the client/server random, there is a more low-level TLS PRF interface called gnutls_prf_raw.

Channel bindings
----------------

In user authentication protocols (e.g., EAP or SASL mechanisms) it is useful to have a unique string that identifies the secure channel that is used, to bind together the user authentication with the secure channel.  This can protect against man-in-the-middle attacks in some situations.  That unique string is called a ``channel binding''.  For background and discussion see RFC5056.

In GnuTLS you can extract a channel binding using the gnutls_session_channel_binding function.  Currently only the type GNUTLS_CB_TLS_UNIQUE is supported, which corresponds to the tls-unique channel binding for TLS defined in RFC5929.

The following example describes how to print the channel binding data. Note that it must be run after a successful TLS handshake.

     {
       gnutls_datum_t cb;
       int rc;

       rc = gnutls_session_channel_binding (session,
                                            GNUTLS_CB_TLS_UNIQUE,
                                            &cb);
       if (rc)
         fprintf (stderr, "Channel binding error: %s\n",
                  gnutls_strerror (rc));
       else
         {
           size_t i;
           printf ("- Channel binding 'tls-unique': ");
           for (i = 0; i < cb.size; i++)
             printf ("%02x", cb.data[i]);
           printf ("\n");
         }
     }

Compatibility with the OpenSSL library
--------------------------------------

To ease GnuTLS' integration with existing applications, a compatibility layer with the OpenSSL library is included in the gnutls-openssl library. This compatibility layer is not complete and it is not intended to completely re-implement the OpenSSL API with GnuTLS.  It only provides limited source-level compatibility.

The prototypes for the compatibility functions are in the gnutls/openssl.h header file. The limitations imposed by the compatibility layer include:

  * Error handling is not thread safe.

Using the cryptographic library
===============================

GnuTLS is not a low-level cryptographic library, i.e., it does not provide access to basic cryptographic primitives. However it abstracts the internal cryptographic back-end (see Cryptographic Backend), providing symmetric crypto, hash and HMAC algorithms, as well access to the random number generation.

Symmetric cryptography
----------------------

The available functions to access symmetric crypto algorithms operations are shown below. The supported algorithms are the algorithms required by the TLS protocol. They are listed in tab:ciphers.

gnutls_cipher_init,gnutls_cipher_encrypt2,gnutls_cipher_decrypt2,gnutls_cipher_set_iv,gnutls_cipher_deinit

In order to support authenticated encryption with associated data (AEAD) algorithms the following functions are provided to set the associated data and retrieve the authentication tag.

gnutls_cipher_add_auth,gnutls_cipher_tag

Hash and HMAC functions
-----------------------

The available operations to access hash functions and hash-MAC (HMAC) algorithms are shown below. HMAC algorithms provided keyed hash functionality. They supported HMAC algorithms are listed in tab:macs.

gnutls_hmac_init,gnutls_hmac,gnutls_hmac_output,gnutls_hmac_deinit,gnutls_hmac_get_len,gnutls_hmac_fast

The available functions to access hash functions are shown below. The supported hash functions are the same as the HMAC algorithms.

gnutls_hash_init,gnutls_hash,gnutls_hash_output,gnutls_hash_deinit,gnutls_hash_get_len,gnutls_hash_fast

Random number generation
------------------------

Access to the random number generator is provided using the gnutls_rnd function.

gnutls_rnd