document the usage of a PKCS #11 trust module for verification
[gnutls:gnutls.git] / doc / cha-library.texi
1 @node Introduction to GnuTLS
2 @chapter Introduction to GnuTLS
3
4 In brief @acronym{GnuTLS} can be described as a library which offers an API
5 to access secure communication protocols. These protocols provide
6 privacy over insecure lines, and were designed to prevent
7 eavesdropping, tampering, or message forgery.
8
9 Technically @acronym{GnuTLS} is a portable ANSI C based library which
10 implements the protocols ranging from SSL 3.0 to TLS 1.2 (see @ref{Introduction to TLS}, 
11 for a detailed description of the protocols), accompanied
12 with the required framework for authentication and public key
13 infrastructure.  Important features of the @acronym{GnuTLS} library
14 include:
15
16 @itemize
17
18 @item Support for TLS 1.2, TLS 1.1, TLS 1.0 and SSL 3.0 protocols.
19
20 @item Support for Datagram TLS 1.0 and 1.2.
21
22 @item Support for handling and verification of @acronym{X.509} and @acronym{OpenPGP} certificates.
23
24 @item Support for password authentication using @acronym{TLS-SRP}.
25
26 @item Support for keyed authentication using @acronym{TLS-PSK}.
27
28 @item Support for TPM, @acronym{PKCS} #11 tokens and smart-cards.
29
30 @end itemize
31
32 The @acronym{GnuTLS} library consists of three independent parts, namely the ``TLS
33 protocol part'', the ``Certificate part'', and the ``Cryptographic
34 back-end'' part.  The ``TLS protocol part'' is the actual protocol
35 implementation, and is entirely implemented within the
36 @acronym{GnuTLS} library.  The ``Certificate part'' consists of the
37 certificate parsing, and verification functions and it uses
38 functionality from the
39 libtasn1 library.
40 The ``Cryptographic back-end'' is provided by the nettle
41 and gmplib libraries.
42
43 @menu
44 * Downloading and installing::
45 * Installing for a software distribution::
46 * Document overview::
47 @end menu
48
49 @node Downloading and installing
50 @section Downloading and installing
51 @cindex installation
52 @cindex download
53
54 GnuTLS is available for download at:
55 @url{http://www.gnutls.org/download.html}
56
57 GnuTLS uses a development cycle where even minor version numbers
58 indicate a stable release and a odd minor version number indicate a
59 development release.  For example, GnuTLS 1.6.3 denote a stable
60 release since 6 is even, and GnuTLS 1.7.11 denote a development
61 release since 7 is odd.
62
63 GnuTLS depends on @code{nettle} and @code{gmplib}, and you will need to install it
64 before installing GnuTLS.  The @code{nettle} library is available from
65 @url{http://www.lysator.liu.se/~nisse/nettle/}, while @code{gmplib} is available
66 from @url{http://www.gmplib.org/}.
67 Don't forget to verify the cryptographic signature after downloading
68 source code packages.
69
70 The package is then extracted, configured and built like many other
71 packages that use Autoconf.  For detailed information on configuring
72 and building it, refer to the @file{INSTALL} file that is part of the
73 distribution archive.  Typically you invoke @code{./configure} and
74 then @code{make check install}.  There are a number of compile-time
75 parameters, as discussed below.
76
77 Several parts of GnuTLS require ASN.1 functionality, which is provided by 
78 a library called libtasn1.  A copy of libtasn1 is included in GnuTLS.  If you
79 want to install it separately (e.g., to make it possibly to use
80 libtasn1 in other programs), you can get it from
81 @url{http://www.gnu.org/software/libtasn1/}.
82
83 The compression library, @code{libz}, the PKCS #11 helper library @code{p11-kit}, as well
84 as the TPM library @code{trousers}, are 
85 optional dependencies. You may get libz from @url{http://www.zlib.net/}, 
86 p11-kit from @url{http://p11-glue.freedesktop.org/} and trousers from
87 @url{http://trousers.sourceforge.net/}.
88
89 A few @code{configure} options may be relevant, summarized below.
90 They disable or enable particular features,
91 to create a smaller library with only the required features.
92 Note however, that although a smaller library is generated, the
93 included programs are not guaranteed to compile if some of these
94 options are given.
95
96 @verbatim
97 --disable-srp-authentication
98 --disable-psk-authentication
99 --disable-anon-authentication
100 --disable-openpgp-authentication
101 --disable-dhe
102 --disable-ecdhe
103 --disable-openssl-compatibility
104 --disable-dtls-srtp-support
105 --disable-alpn-support
106 --disable-heartbeat-support
107 --disable-libdane
108 --without-p11-kit
109 --without-tpm
110 --without-zlib
111
112 @end verbatim
113
114 For the complete list, refer to the output from @code{configure --help}.
115
116 @node Installing for a software distribution
117 @section Installing for a software distribution
118 @cindex installation
119
120 When installing for a software distribution, it is often desirable to preconfigure
121 GnuTLS with the system-wide paths and files. There two important configuration
122 options, one sets the trust store in system, which are the CA certificates
123 to be used by programs by default (if they don't override it), and the other sets
124 to DNSSEC root key file used by unbound for DNSSEC verification.
125
126 For the latter the following configuration option is available, and if not specified
127 GnuTLS will try to auto-detect the location of that file.
128 @verbatim
129 --with-unbound-root-key-file
130
131 @end verbatim
132
133 To set the trust store the following options are available.
134 @verbatim
135 --with-default-trust-store-file
136 --with-default-trust-store-dir
137 --with-default-trust-store-pkcs11
138
139 @end verbatim
140 The first option is used to set a PEM file which contains a list of trusted certificates,
141 while the second will read all certificates in the given path. The recommended option is
142 the last, which allows to use a PKCS #11 trust policy module. That module not only
143 provides the trusted certificates, but allows the categorization of them using purpose,
144 e.g., CAs can be restricted for e-mail usage only, or administrative restrictions of CAs, for
145 examples by restricting a CA to only issue certificates for a given DNS domain using NameConstraints.
146 A publicly available PKCS #11 trust module is p11-kit's trust module@footnote{@url{http://p11-glue.freedesktop.org/doc/p11-kit/trust-module.html}}.
147
148 @node Document overview
149 @section Overview
150 In this document we present an overview of the supported security protocols in @ref{Introduction to TLS}, and 
151 continue by providing more information on the certificate authentication in @ref{Certificate authentication},
152 and shared-key as well anonymous authentication in @ref{Shared-key and anonymous authentication}. We
153 elaborate on certificate authentication by demonstrating advanced usage of the API in @ref{More on certificate authentication}.
154 The core of the TLS library is presented in @ref{How to use GnuTLS in applications} and example
155 applications are listed in @ref{GnuTLS application examples}.
156 In @ref{Other included programs} the usage of few included programs that
157 may assist debugging is presented. The last chapter is @ref{Internal architecture of GnuTLS} that
158 provides a short introduction to GnuTLS' internal architecture.