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 * Document overview::
  46 @end menu
  47
  48 @node Downloading and installing
  49 @section Downloading and installing
  50 @cindex installation
  51 @cindex download
  52
  53 GnuTLS is available for download at:
  54 @url{http://www.gnutls.org/download.html}
  55
  56 GnuTLS uses a development cycle where even minor version numbers
  57 indicate a stable release and a odd minor version number indicate a
  58 development release.  For example, GnuTLS 1.6.3 denote a stable
  59 release since 6 is even, and GnuTLS 1.7.11 denote a development
  60 release since 7 is odd.
  61
  62 GnuTLS depends on @code{nettle} and @code{gmplib}, and you will need to install it
  63 before installing GnuTLS.  The @code{nettle} library is available from
  64 @url{http://www.lysator.liu.se/~nisse/nettle/}, while @code{gmplib} is available
  65 from @url{http://www.gmplib.org/}.
  66 Don't forget to verify the cryptographic signature after downloading
  67 source code packages.
  68
  69 The package is then extracted, configured and built like many other
  70 packages that use Autoconf.  For detailed information on configuring
  71 and building it, refer to the @file{INSTALL} file that is part of the
  72 distribution archive.  Typically you invoke @code{./configure} and
  73 then @code{make check install}.  There are a number of compile-time
  74 parameters, as discussed below.
  75
  76 Several parts of GnuTLS require ASN.1 functionality, which is provided by
  77 a library called libtasn1.  A copy of libtasn1 is included in GnuTLS.  If you
  78 want to install it separately (e.g., to make it possibly to use
  79 libtasn1 in other programs), you can get it from
  80 @url{http://www.gnu.org/software/libtasn1/}.
  81
  82 The compression library, @code{libz}, the PKCS #11 helper library @code{p11-kit}, as well
  83 as the TPM library @code{trousers}, are
  84 optional dependencies. You may get libz from @url{http://www.zlib.net/},
  85 p11-kit from @url{http://p11-glue.freedesktop.org/} and trousers from
  86 @url{http://trousers.sourceforge.net/}.
  87
  88 A few @code{configure} options may be relevant, summarized below.
  89 They disable or enable particular features,
  90 to create a smaller library with only the required features.
  91 Note however, that although a smaller library is generated, the
  92 included programs are not guaranteed to compile if some of these
  93 options are given.
  94
  95 @verbatim
  96 --disable-srp-authentication
  97 --disable-psk-authentication
  98 --disable-anon-authentication
  99 --disable-openpgp-authentication
 100 --disable-dhe
 101 --disable-ecdhe
 102 --disable-openssl-compatibility
 103 --disable-dtls-srtp-support
 104 --disable-alpn-support
 105 --disable-heartbeat-support
 106 --disable-libdane
 107 --without-p11-kit
 108 --without-tpm
 109 --without-zlib
 110
 111 @end verbatim
 112
 113 For the complete list, refer to the output from @code{configure --help}.
 114
 115 @node Document overview
 116 @section Overview
 117 In this document we present an overview of the supported security protocols in @ref{Introduction to TLS}, and
 118 continue by providing more information on the certificate authentication in @ref{Certificate authentication},
 119 and shared-key as well anonymous authentication in @ref{Shared-key and anonymous authentication}. We
 120 elaborate on certificate authentication by demonstrating advanced usage of the API in @ref{More on certificate authentication}.
 121 The core of the TLS library is presented in @ref{How to use GnuTLS in applications} and example
 122 applications are listed in @ref{GnuTLS application examples}.
 123 In @ref{Other included programs} the usage of few included programs that
 124 may assist debugging is presented. The last chapter is @ref{Internal architecture of GnuTLS} that
 125 provides a short introduction to GnuTLS' internal architecture.