@node Introduction to GnuTLS

@chapter Introduction to GnuTLS

In brief @acronym{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 @acronym{GnuTLS} is a portable ANSI C based library which

implements the protocols ranging from SSL 3.0 to TLS 1.3 (see @ref{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 @acronym{GnuTLS} library

include:

@itemize

@item Support for TLS 1.3, TLS 1.2, TLS 1.1, TLS 1.0 and optionally SSL 3.0 protocols.

@item Support for Datagram TLS 1.0 and 1.2.

@item Support for handling and verification of @acronym{X.509} certificates.

@item Support for password authentication using @acronym{TLS-SRP}.

@item Support for keyed authentication using @acronym{TLS-PSK}.

@item Support for TPM, @acronym{PKCS} #11 tokens and smart-cards.

@end itemize

The @acronym{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

@acronym{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.

@menu

* Downloading and installing::

* Installing for a software distribution::

* Document overview::

@end menu

@node Downloading and installing

@section Downloading and installing

@cindex installation

@cindex download

GnuTLS is available for download at:

@url{https://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 @code{nettle} and @code{gmplib}, and you will need to install it

before installing GnuTLS.  The @code{nettle} library is available from

@url{https://www.lysator.liu.se/~nisse/nettle/}, while @code{gmplib} is available

from @url{https://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 @file{INSTALL} file that is part of the

distribution archive.  Typically you invoke @code{./configure} and

then @code{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

@url{https://www.gnu.org/software/libtasn1/}.

The compression library, @code{libz}, the PKCS #11 helper library @code{p11-kit},

the TPM library @code{trousers}, as well as the IDN library @code{libidn}@footnote{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 @code{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.

@verbatim

--disable-srp-authentication

--disable-psk-authentication

--disable-anon-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

@end verbatim

For the complete list, refer to the output from @code{configure --help}.

@node Installing for a software distribution

@section Installing for a software distribution

@cindex installation

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.

@verbatim

--with-unbound-root-key-file

@end verbatim

To set the trust store the following options are available.

@verbatim

--with-default-trust-store-file

--with-default-trust-store-dir

--with-default-trust-store-pkcs11

@end verbatim

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@footnote{@url{https://p11-glue.github.io/p11-glue/trust-module.html}}.

@node Document overview

@section Overview

In this document we present an overview of the supported security protocols in @ref{Introduction to TLS}, and 

continue by providing more information on the certificate authentication in @ref{Certificate authentication},

and shared-key as well anonymous authentication in @ref{Shared-key and anonymous authentication}. We

elaborate on certificate authentication by demonstrating advanced usage of the API in @ref{More on certificate authentication}.

The core of the TLS library is presented in @ref{How to use GnuTLS in applications} and example

applications are listed in @ref{GnuTLS application examples}.

In @ref{Other included programs} the usage of few included programs that

may assist debugging is presented. The last chapter is @ref{Internal architecture of GnuTLS} that

provides a short introduction to GnuTLS' internal architecture.