|
Packit Service |
4684c1 |
@node Introduction to GnuTLS
|
|
Packit Service |
4684c1 |
@chapter Introduction to GnuTLS
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
In brief @acronym{GnuTLS} can be described as a library which offers an API
|
|
Packit Service |
4684c1 |
to access secure communication protocols. These protocols provide
|
|
Packit Service |
4684c1 |
privacy over insecure lines, and were designed to prevent
|
|
Packit Service |
4684c1 |
eavesdropping, tampering, or message forgery.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
Technically @acronym{GnuTLS} is a portable ANSI C based library which
|
|
Packit Service |
4684c1 |
implements the protocols ranging from SSL 3.0 to TLS 1.3 (see @ref{Introduction to TLS},
|
|
Packit Service |
4684c1 |
for a detailed description of the protocols), accompanied
|
|
Packit Service |
4684c1 |
with the required framework for authentication and public key
|
|
Packit Service |
4684c1 |
infrastructure. Important features of the @acronym{GnuTLS} library
|
|
Packit Service |
4684c1 |
include:
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@itemize
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item Support for TLS 1.3, TLS 1.2, TLS 1.1, TLS 1.0 and optionally SSL 3.0 protocols.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item Support for Datagram TLS 1.0 and 1.2.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item Support for handling and verification of @acronym{X.509} certificates.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item Support for password authentication using @acronym{TLS-SRP}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item Support for keyed authentication using @acronym{TLS-PSK}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item Support for TPM, @acronym{PKCS} #11 tokens and smart-cards.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@end itemize
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The @acronym{GnuTLS} library consists of three independent parts, namely the ``TLS
|
|
Packit Service |
4684c1 |
protocol part'', the ``Certificate part'', and the ``Cryptographic
|
|
Packit Service |
4684c1 |
back-end'' part. The ``TLS protocol part'' is the actual protocol
|
|
Packit Service |
4684c1 |
implementation, and is entirely implemented within the
|
|
Packit Service |
4684c1 |
@acronym{GnuTLS} library. The ``Certificate part'' consists of the
|
|
Packit Service |
4684c1 |
certificate parsing, and verification functions and it uses
|
|
Packit Service |
4684c1 |
functionality from the
|
|
Packit Service |
4684c1 |
libtasn1 library.
|
|
Packit Service |
4684c1 |
The ``Cryptographic back-end'' is provided by the nettle
|
|
Packit Service |
4684c1 |
and gmplib libraries.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@menu
|
|
Packit Service |
4684c1 |
* Downloading and installing::
|
|
Packit Service |
4684c1 |
* Installing for a software distribution::
|
|
Packit Service |
4684c1 |
* Document overview::
|
|
Packit Service |
4684c1 |
@end menu
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@node Downloading and installing
|
|
Packit Service |
4684c1 |
@section Downloading and installing
|
|
Packit Service |
4684c1 |
@cindex installation
|
|
Packit Service |
4684c1 |
@cindex download
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
GnuTLS is available for download at:
|
|
Packit Service |
4684c1 |
@url{https://www.gnutls.org/download.html}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
GnuTLS uses a development cycle where even minor version numbers
|
|
Packit Service |
4684c1 |
indicate a stable release and a odd minor version number indicate a
|
|
Packit Service |
4684c1 |
development release. For example, GnuTLS 1.6.3 denote a stable
|
|
Packit Service |
4684c1 |
release since 6 is even, and GnuTLS 1.7.11 denote a development
|
|
Packit Service |
4684c1 |
release since 7 is odd.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
GnuTLS depends on @code{nettle} and @code{gmplib}, and you will need to install it
|
|
Packit Service |
4684c1 |
before installing GnuTLS. The @code{nettle} library is available from
|
|
Packit Service |
4684c1 |
@url{https://www.lysator.liu.se/~nisse/nettle/}, while @code{gmplib} is available
|
|
Packit Service |
4684c1 |
from @url{https://www.gmplib.org/}.
|
|
Packit Service |
4684c1 |
Don't forget to verify the cryptographic signature after downloading
|
|
Packit Service |
4684c1 |
source code packages.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The package is then extracted, configured and built like many other
|
|
Packit Service |
4684c1 |
packages that use Autoconf. For detailed information on configuring
|
|
Packit Service |
4684c1 |
and building it, refer to the @file{INSTALL} file that is part of the
|
|
Packit Service |
4684c1 |
distribution archive. Typically you invoke @code{./configure} and
|
|
Packit Service |
4684c1 |
then @code{make check install}. There are a number of compile-time
|
|
Packit Service |
4684c1 |
parameters, as discussed below.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
Several parts of GnuTLS require ASN.1 functionality, which is provided by
|
|
Packit Service |
4684c1 |
a library called libtasn1. A copy of libtasn1 is included in GnuTLS. If you
|
|
Packit Service |
4684c1 |
want to install it separately (e.g., to make it possibly to use
|
|
Packit Service |
4684c1 |
libtasn1 in other programs), you can get it from
|
|
Packit Service |
4684c1 |
@url{https://www.gnu.org/software/libtasn1/}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The compression library, @code{libz}, the PKCS #11 helper library @code{p11-kit},
|
|
Packit Service |
4684c1 |
the TPM library @code{trousers}, as well as the IDN library @code{libidn}@footnote{Needed
|
|
Packit Service |
4684c1 |
to use RFC6125 name comparison in internationalized domains.} are
|
|
Packit Service |
4684c1 |
optional dependencies. Check the README file in the distribution on how
|
|
Packit Service |
4684c1 |
to obtain these libraries.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
A few @code{configure} options may be relevant, summarized below.
|
|
Packit Service |
4684c1 |
They disable or enable particular features,
|
|
Packit Service |
4684c1 |
to create a smaller library with only the required features.
|
|
Packit Service |
4684c1 |
Note however, that although a smaller library is generated, the
|
|
Packit Service |
4684c1 |
included programs are not guaranteed to compile if some of these
|
|
Packit Service |
4684c1 |
options are given.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@verbatim
|
|
Packit Service |
4684c1 |
--disable-srp-authentication
|
|
Packit Service |
4684c1 |
--disable-psk-authentication
|
|
Packit Service |
4684c1 |
--disable-anon-authentication
|
|
Packit Service |
4684c1 |
--disable-dhe
|
|
Packit Service |
4684c1 |
--disable-ecdhe
|
|
Packit Service |
4684c1 |
--disable-openssl-compatibility
|
|
Packit Service |
4684c1 |
--disable-dtls-srtp-support
|
|
Packit Service |
4684c1 |
--disable-alpn-support
|
|
Packit Service |
4684c1 |
--disable-heartbeat-support
|
|
Packit Service |
4684c1 |
--disable-libdane
|
|
Packit Service |
4684c1 |
--without-p11-kit
|
|
Packit Service |
4684c1 |
--without-tpm
|
|
Packit Service |
4684c1 |
--without-zlib
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@end verbatim
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
For the complete list, refer to the output from @code{configure --help}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@node Installing for a software distribution
|
|
Packit Service |
4684c1 |
@section Installing for a software distribution
|
|
Packit Service |
4684c1 |
@cindex installation
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
When installing for a software distribution, it is often desirable to preconfigure
|
|
Packit Service |
4684c1 |
GnuTLS with the system-wide paths and files. There two important configuration
|
|
Packit Service |
4684c1 |
options, one sets the trust store in system, which are the CA certificates
|
|
Packit Service |
4684c1 |
to be used by programs by default (if they don't override it), and the other sets
|
|
Packit Service |
4684c1 |
to DNSSEC root key file used by unbound for DNSSEC verification.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
For the latter the following configuration option is available, and if not specified
|
|
Packit Service |
4684c1 |
GnuTLS will try to auto-detect the location of that file.
|
|
Packit Service |
4684c1 |
@verbatim
|
|
Packit Service |
4684c1 |
--with-unbound-root-key-file
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@end verbatim
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
To set the trust store the following options are available.
|
|
Packit Service |
4684c1 |
@verbatim
|
|
Packit Service |
4684c1 |
--with-default-trust-store-file
|
|
Packit Service |
4684c1 |
--with-default-trust-store-dir
|
|
Packit Service |
4684c1 |
--with-default-trust-store-pkcs11
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@end verbatim
|
|
Packit Service |
4684c1 |
The first option is used to set a PEM file which contains a list of trusted certificates,
|
|
Packit Service |
4684c1 |
while the second will read all certificates in the given path. The recommended option is
|
|
Packit Service |
4684c1 |
the last, which allows to use a PKCS #11 trust policy module. That module not only
|
|
Packit Service |
4684c1 |
provides the trusted certificates, but allows the categorization of them using purpose,
|
|
Packit Service |
4684c1 |
e.g., CAs can be restricted for e-mail usage only, or administrative restrictions of CAs, for
|
|
Packit Service |
4684c1 |
examples by restricting a CA to only issue certificates for a given DNS domain using NameConstraints.
|
|
Packit Service |
4684c1 |
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}}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@node Document overview
|
|
Packit Service |
4684c1 |
@section Overview
|
|
Packit Service |
4684c1 |
In this document we present an overview of the supported security protocols in @ref{Introduction to TLS}, and
|
|
Packit Service |
4684c1 |
continue by providing more information on the certificate authentication in @ref{Certificate authentication},
|
|
Packit Service |
4684c1 |
and shared-key as well anonymous authentication in @ref{Shared-key and anonymous authentication}. We
|
|
Packit Service |
4684c1 |
elaborate on certificate authentication by demonstrating advanced usage of the API in @ref{More on certificate authentication}.
|
|
Packit Service |
4684c1 |
The core of the TLS library is presented in @ref{How to use GnuTLS in applications} and example
|
|
Packit Service |
4684c1 |
applications are listed in @ref{GnuTLS application examples}.
|
|
Packit Service |
4684c1 |
In @ref{Other included programs} the usage of few included programs that
|
|
Packit Service |
4684c1 |
may assist debugging is presented. The last chapter is @ref{Internal architecture of GnuTLS} that
|
|
Packit Service |
4684c1 |
provides a short introduction to GnuTLS' internal architecture.
|