doc/cha-library.texi

   1 @node The Library
   2 @chapter The Library
   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 (@xref{Introduction to
  11 TLS}, for a more 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 both @acronym{X.509} and @acronym{OpenPGP} certificates.
  21
  22 @item Support for handling and verification of certificates.
  23
  24 @item Support for @acronym{SRP} for TLS authentication.
  25
  26 @item Support for @acronym{PSK} for TLS authentication.
  27
  28 @item Support for TLS Extension mechanism.
  29
  30 @item Support for TLS Compression Methods.
  31
  32 @end itemize
  33
  34 Additionally @acronym{GnuTLS} provides a limited emulation API for the
  35 widely used OpenSSL@footnote{@url{http://www.openssl.org/}} library,
  36 to ease integration with existing applications.
  37
  38 @acronym{GnuTLS} consists of three independent parts, namely the ``TLS
  39 protocol part'', the ``Certificate part'', and the ``Cryptographic
  40 backend'' part.  The `TLS protocol part' is the actual protocol
  41 implementation, and is entirely implemented within the
  42 @acronym{GnuTLS} library.  The `Certificate part' consists of the
  43 certificate parsing, and verification functions which is partially
  44 implemented in the @acronym{GnuTLS} library.  The
  45 @acronym{Libtasn1}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/libtasn1/}},
  46 a library which offers @acronym{ASN.1} parsing capabilities, is used
  47 for the @acronym{X.509} certificate parsing functions.  A smaller
  48 version of
  49 @acronym{OpenCDK}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/opencdk/}}
  50 is used for the @acronym{OpenPGP} key support in @acronym{GnuTLS}.
  51 The ``Cryptographic backend'' is provided by the
  52 @acronym{Libgcrypt}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/libgcrypt/}}
  53 library@footnote{On current versions of GnuTLS it is possible to
  54 override the default crypto backend. Check @pxref{Cryptographic
  55 Backend} for details}.
  56
  57 In order to ease integration in embedded systems, parts of the
  58 @acronym{GnuTLS} library can be disabled at compile time. That way a
  59 small library, with the required features, can be generated.
  60
  61 @menu
  62 * General Idea::
  63 * Error handling::
  64 * Memory handling::
  65 * Callback functions::
  66 @end menu
  67
  68 @node General Idea
  69 @section General Idea
  70
  71 A brief description of how @acronym{GnuTLS} works internally is shown
  72 at the figure below. This section may be easier to understand after
  73 having seen the examples (@pxref{examples}).
  74
  75 @image{gnutls-internals,12cm,8cm}
  76
  77 As shown in the figure, there is a read-only global state that is
  78 initialized once by the global initialization function.  This global
  79 structure, among others, contains the memory allocation functions
  80 used, and some structures needed for the @acronym{ASN.1} parser.  This
  81 structure is never modified by any @acronym{GnuTLS} function, except
  82 for the deinitialization function which frees all memory allocated in
  83 the global structure and is called after the program has permanently
  84 finished using @acronym{GnuTLS}.
  85
  86 The credentials structure is used by some authentication methods, such
  87 as certificate authentication (@pxref{Certificate Authentication}).  A
  88 credentials structure may contain certificates, private keys,
  89 temporary parameters for Diffie-Hellman or RSA key exchange, and other
  90 stuff that may be shared between several TLS sessions.
  91
  92 This structure should be initialized using the appropriate
  93 initialization functions. For example an application which uses
  94 certificate authentication would probably initialize the credentials,
  95 using the appropriate functions, and put its trusted certificates in
  96 this structure. The next step is to associate the credentials
  97 structure with each @acronym{TLS} session.
  98
  99 A @acronym{GnuTLS} session contains all the required stuff for a
 100 session to handle one secure connection. This session calls directly
 101 to the transport layer functions, in order to communicate with the
 102 peer.  Every session has a unique session ID shared with the peer.
 103
 104 Since TLS sessions can be resumed, servers would probably need a
 105 database backend to hold the session's parameters.  Every
 106 @acronym{GnuTLS} session after a successful handshake calls the
 107 appropriate backend function (@xref{resume}, for information on
 108 initialization) to store the newly negotiated session. The session
 109 database is examined by the server just after having received the
 110 client hello@footnote{The first message in a @acronym{TLS} handshake},
 111 and if the session ID sent by the client, matches a stored session,
 112 the stored session will be retrieved, and the new session will be a
 113 resumed one, and will share the same session ID with the previous one.
 114
 115 @node Error handling
 116 @section Error Handling
 117
 118 In @acronym{GnuTLS} most functions return an integer type as a result.
 119 In almost all cases a zero or a positive number means success, and a
 120 negative number indicates failure, or a situation that some action has
 121 to be taken. Thus negative error codes may be fatal or not.
 122
 123 Fatal errors terminate the connection immediately and further sends
 124 and receives will be disallowed. An example of a fatal error code is
 125 @code{GNUTLS_E_DECRYPTION_FAILED}. Non-fatal errors may warn about
 126 something, i.e., a warning alert was received, or indicate the some
 127 action has to be taken. This is the case with the error code
 128 @code{GNUTLS_E_REHANDSHAKE} returned by @ref{gnutls_record_recv}.
 129 This error code indicates that the server requests a re-handshake. The
 130 client may ignore this request, or may reply with an alert.  You can
 131 test if an error code is a fatal one by using the
 132 @ref{gnutls_error_is_fatal}.
 133
 134 If any non fatal errors, that require an action, are to be returned by
 135 a function, these error codes will be documented in the function's
 136 reference.  @xref{Error Codes}, for all the error codes.
 137
 138 @node Memory handling
 139 @section Memory Handling
 140
 141 @acronym{GnuTLS} internally handles heap allocated objects
 142 differently, depending on the sensitivity of the data they
 143 contain. However for performance reasons, the default memory functions
 144 do not overwrite sensitive data from memory, nor protect such objects
 145 from being written to the swap.  In order to change the default
 146 behavior the @ref{gnutls_global_set_mem_functions} function is
 147 available which can be used to set other memory handlers than the
 148 defaults.
 149
 150 The @acronym{Libgcrypt} library on which @acronym{GnuTLS} depends, has
 151 such secure memory allocation functions available. These should be
 152 used in cases where even the system's swap memory is not considered
 153 secure. See the documentation of @acronym{Libgcrypt} for more
 154 information.
 155
 156 @node Callback functions
 157 @section Callback Functions
 158 @cindex Callback functions
 159
 160 There are several cases where @acronym{GnuTLS} may need some out of
 161 band input from your program. This is now implemented using some
 162 callback functions, which your program is expected to register.
 163
 164 An example of this type of functions are the push and pull callbacks
 165 which are used to specify the functions that will retrieve and send
 166 data to the transport layer.
 167
 168 @itemize
 169
 170 @item @ref{gnutls_transport_set_push_function}
 171
 172 @item @ref{gnutls_transport_set_pull_function}
 173
 174 @end itemize
 175
 176 Other callback functions such as the one set by
 177 @ref{gnutls_srp_set_server_credentials_function}, may require more
 178 complicated input, including data to be allocated.  These callbacks
 179 should allocate and free memory using the functions shown below.
 180
 181 @itemize
 182
 183 @item @ref{gnutls_malloc}
 184
 185 @item @ref{gnutls_free}
 186
 187 @end itemize