Introduction to GnuTLS
**********************

In brief GnuTLS can be described as a library which offers an API to access secure communication protocols. These protocols provide privacy over insecure lines, and were designed to prevent eavesdropping, tampering, or message forgery.

Technically GnuTLS is a portable ANSI C based library which implements the protocols ranging from SSL 3.0 to TLS 1.2 (see Introduction to TLS, for a detailed description of the protocols), accompanied with the required framework for authentication and public key infrastructure.  Important features of the GnuTLS library include:

  * Support for TLS 1.2, TLS 1.1, TLS 1.0 and SSL 3.0 protocols.

  * Support for Datagram TLS 1.0 and 1.2.

  * Support for handling and verification of X.509 and OpenPGP certificates.

  * Support for password authentication using TLS-SRP.

  * Support for keyed authentication using TLS-PSK.

  * Support for TPM, PKCS #11 tokens and smart-cards.

The GnuTLS library consists of three independent parts, namely the ``TLS protocol part'', the ``Certificate part'', and the ``Cryptographic back-end'' part.  The ``TLS protocol part'' is the actual protocol implementation, and is entirely implemented within the GnuTLS library.  The ``Certificate part'' consists of the certificate parsing, and verification functions and it uses functionality from the libtasn1 library. The ``Cryptographic back-end'' is provided by the nettle and gmplib libraries.

Downloading and installing
==========================

GnuTLS is available for download at: http://www.gnutls.org/download.html

GnuTLS uses a development cycle where even minor version numbers indicate a stable release and a odd minor version number indicate a development release.  For example, GnuTLS 1.6.3 denote a stable release since 6 is even, and GnuTLS 1.7.11 denote a development release since 7 is odd.

GnuTLS depends on nettle and gmplib, and you will need to install it before installing GnuTLS.  The nettle library is available from http://www.lysator.liu.se/~nisse/nettle/, while gmplib is available from http://www.gmplib.org/. Don't forget to verify the cryptographic signature after downloading source code packages.

The package is then extracted, configured and built like many other packages that use Autoconf.  For detailed information on configuring and building it, refer to the INSTALL file that is part of the distribution archive.  Typically you invoke ./configure and then make check install.  There are a number of compile-time parameters, as discussed below.

Several parts of GnuTLS require ASN.1 functionality, which is provided by a library called libtasn1.  A copy of libtasn1 is included in GnuTLS.  If you want to install it separately (e.g., to make it possibly to use libtasn1 in other programs), you can get it from http://www.gnu.org/software/libtasn1/.

The compression library, libz, the PKCS #11 helper library p11-kit, the TPM library trousers, as well as the IDN library libidn (Needed to use RFC6125 name comparison in internationalized domains.) are optional dependencies. Check the README file in the distribution on how to obtain these libraries.

A few configure options may be relevant, summarized below. They disable or enable particular features, to create a smaller library with only the required features. Note however, that although a smaller library is generated, the included programs are not guaranteed to compile if some of these options are given.

--disable-srp-authentication
--disable-psk-authentication
--disable-anon-authentication
--disable-openpgp-authentication
--disable-dhe
--disable-ecdhe
--disable-openssl-compatibility
--disable-dtls-srtp-support
--disable-alpn-support
--disable-heartbeat-support
--disable-libdane
--without-p11-kit
--without-tpm
--without-zlib

For the complete list, refer to the output from configure --help.

Installing for a software distribution
======================================

When installing for a software distribution, it is often desirable to preconfigure GnuTLS with the system-wide paths and files. There two important configuration options, one sets the trust store in system, which are the CA certificates to be used by programs by default (if they don't override it), and the other sets to DNSSEC root key file used by unbound for DNSSEC verification.

For the latter the following configuration option is available, and if not specified GnuTLS will try to auto-detect the location of that file.
--with-unbound-root-key-file

To set the trust store the following options are available.
--with-default-trust-store-file
--with-default-trust-store-dir
--with-default-trust-store-pkcs11

The first option is used to set a PEM file which contains a list of trusted certificates, while the second will read all certificates in the given path. The recommended option is the last, which allows to use a PKCS #11 trust policy module. That module not only provides the trusted certificates, but allows the categorization of them using purpose, e.g., CAs can be restricted for e-mail usage only, or administrative restrictions of CAs, for examples by restricting a CA to only issue certificates for a given DNS domain using NameConstraints. A publicly available PKCS #11 trust module is p11-kit's trust module (http://p11-glue.freedesktop.org/doc/p11-kit/trust-module.html).

Overview
========

In this document we present an overview of the supported security protocols in Introduction to TLS, and continue by providing more information on the certificate authentication in Certificate authentication, and shared-key as well anonymous authentication in Shared-key and anonymous authentication. We elaborate on certificate authentication by demonstrating advanced usage of the API in More on certificate authentication. The core of the TLS library is presented in How to use GnuTLS in applications and example applications are listed in GnuTLS application examples. In Other included programs the usage of few included programs that may assist debugging is presented. The last chapter is Internal architecture of GnuTLS that provides a short introduction to GnuTLS' internal architecture.