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 (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.
  21
  22 @item Support for both @acronym{X.509} and @acronym{OpenPGP} certificates.
  23
  24 @item Support for handling and verification of certificates.
  25
  26 @item Support for @acronym{SRP} for TLS authentication.
  27
  28 @item Support for @acronym{PSK} for TLS authentication.
  29
  30 @item Support for TLS safe renegotiation.
  31
  32 @item Support for @acronym{PKCS} #11 tokens.
  33
  34 @end itemize
  35
  36 @acronym{GnuTLS} consists of three independent parts, namely the ``TLS
  37 protocol part'', the ``Certificate part'', and the ``Cryptographic
  38 back-end'' part.  The ``TLS protocol part'' is the actual protocol
  39 implementation, and is entirely implemented within the
  40 @acronym{GnuTLS} library.  The ``Certificate part'' consists of the
  41 certificate parsing, and verification functions which is partially
  42 implemented in the @acronym{GnuTLS} library.  The
  43 libtasn1@footnote{@url{http://www.gnu.org/software/libtasn1/}},
  44 a library which offers @acronym{ASN.1} parsing capabilities, is used
  45 for the @acronym{X.509} certificate parsing functions.
  46 The ``Cryptographic back-end'' is provided by nettle@footnote{@url{http://www.lysator.liu.se/~nisse/nettle/}}
  47 library.
  48 In order to ease integration in embedded systems, parts of the
  49 @acronym{GnuTLS} library can be disabled at compile time. That way a
  50 smaller library, with the required features, can be generated.
  51
  52 @menu
  53 * General idea::
  54 * Error handling::
  55 * Thread safety::
  56 * Callback functions::
  57 @end menu
  58
  59 @node General idea
  60 @section General idea
  61
  62 A brief description of how @acronym{GnuTLS} works internally is shown
  63 at @ref{fig:gnutls-design}. This section may be easier to understand after
  64 having seen the examples at @ref{examples}.
  65 As shown in the figure, there is a read-only global state that is
  66 initialized once by the global initialization function.  This global
  67 structure, among others, contains the memory allocation functions
  68 used, and some structures needed for the @acronym{ASN.1} parser.  This
  69 structure is never modified by any @acronym{GnuTLS} function, except
  70 for the deinitialization function which frees all memory allocated in
  71 the global structure and is called after the program has permanently
  72 finished using @acronym{GnuTLS}.
  73
  74 @float Figure,fig:gnutls-design
  75 @image{gnutls-internals,12cm}
  76 @caption{High level design of GnuTLS.}
  77 @end float
  78
  79 The credentials structure is used by some authentication methods, such
  80 as certificate authentication.  A
  81 credentials structure may contain certificates, private keys,
  82 temporary parameters for Diffie-Hellman or RSA key exchange, and other
  83 stuff that may be shared between several TLS sessions.
  84
  85 This structure should be initialized using the appropriate
  86 initialization functions. For example an application which uses
  87 certificate authentication would probably initialize the credentials,
  88 using the appropriate functions, and put its trusted certificates in
  89 this structure. The next step is to associate the credentials
  90 structure with each @acronym{TLS} session.
  91
  92 A @acronym{GnuTLS} session contains all the required information for a
  93 session to handle one secure connection. This session calls directly
  94 to the transport layer functions, in order to communicate with the
  95 peer.  Every session has a unique session ID shared with the peer.
  96
  97 Since TLS sessions can be resumed, servers would probably need a
  98 database back-end to hold the session's parameters.  Every
  99 @acronym{GnuTLS} session after a successful handshake calls the
 100 appropriate back-end function (see @ref{resume}, for information on
 101 initialization) to store the newly negotiated session. The session
 102 database is examined by the server just after having received the
 103 client hello@footnote{The first message in a @acronym{TLS} handshake},
 104 and if the session ID sent by the client, matches a stored session,
 105 the stored session will be retrieved, and the new session will be a
 106 resumed one, and will share the same session ID with the previous one.
 107
 108 @node Error handling
 109 @section Error handling
 110 @subsection Conventions
 111
 112 In @acronym{GnuTLS} most functions return an integer type as a result.
 113 In almost all cases a zero or a positive number means success, and a
 114 negative number indicates failure, or a situation that some action has
 115 to be taken. Thus negative error codes may be fatal or not.
 116
 117 Fatal errors terminate the connection immediately and further sends
 118 and receives will be disallowed.  Such an example is
 119 @code{GNUTLS_@-E_@-DECRYPTION_@-FAILED}. Non-fatal errors may warn about
 120 something, i.e., a warning alert was received, or indicate the some
 121 action has to be taken. This is the case with the error code
 122 @code{GNUTLS_@-E_@-REHANDSHAKE} returned by @funcref{gnutls_record_recv}.
 123 This error code indicates that the server requests a re-handshake. The
 124 client may ignore this request, or may reply with an alert.  You can
 125 test if an error code is a fatal one by using the
 126 @funcref{gnutls_error_is_fatal}.
 127
 128 If any non fatal errors, that require an action, are to be returned by
 129 a function, these error codes will be documented in the function's
 130 reference.  See @ref{Error codes}, for a description of the available
 131 error codes.
 132
 133 @subsection Debugging and auditing
 134
 135 In many cases things may not go as expected and further information,
 136 to assist debugging, from @acronym{GnuTLS} is desired.
 137 Those are the cases where the @funcref{gnutls_global_set_log_level} and
 138 @funcref{gnutls_global_set_log_function} are to be used. Those will print
 139 verbose information on the @acronym{GnuTLS} functions internal flow.
 140
 141 @showfuncB{gnutls_global_set_log_level,gnutls_global_set_log_function}
 142
 143 When debugging is not required, important issues, such as detected
 144 attacks on the protocol still need to be logged. This is provided
 145 by the logging function set by
 146 @funcref{gnutls_global_set_audit_log_function}. The set function
 147 accepts the detected error message and the corresponding
 148 TLS session. The session information might be used to derive IP addresses
 149 or other information about the peer involved.
 150
 151 @showfuncdesc{gnutls_global_set_audit_log_function}
 152
 153 @node Thread safety
 154 @section Thread safety
 155
 156 Although the @acronym{GnuTLS} library is thread safe by design, some
 157 parts of the cryptographic back-end, such as the random generator, are not.
 158 Applications can either call @funcref{gnutls_global_init} which will use the default
 159 operating system provided locks (i.e. @code{pthreads} on GNU/Linux and
 160 @code{CriticalSection} on Windows), or specify manually the locking system using
 161 the function @funcref{gnutls_global_set_mutex} before calling @funcref{gnutls_global_init}.
 162 Setting manually mutexes is recommended
 163 only to applications that have full control of the underlying libraries. If this
 164 is not the case, the use of the operating system defaults is recommended. Examples
 165 are shown below.
 166
 167
 168 @example
 169 #include <gnutls.h>
 170
 171 /* Native threads
 172  */
 173
 174 int main()
 175 @{
 176    gnutls_global_init();
 177 @}
 178 @end example
 179
 180 @example
 181 #include <gnutls.h>
 182
 183 /* Other thread packages
 184  */
 185
 186 int main()
 187 @{
 188    gnutls_global_mutex_set (mutex_init, mutex_deinit,
 189                             mutex_lock, mutex_unlock);
 190    gnutls_global_init();
 191 @}
 192 @end example
 193
 194 @node Callback functions
 195 @section Callback functions
 196 @cindex callback functions
 197
 198 There are several cases where @acronym{GnuTLS} may need out of
 199 band input from your program. This is now implemented using some
 200 callback functions, which your program is expected to register.
 201
 202 An example of this type of functions are the push and pull callbacks
 203 which are used to specify the functions that will retrieve and send
 204 data to the transport layer.
 205
 206 @showfuncB{gnutls_transport_set_push_function,gnutls_transport_set_pull_function}
 207
 208 Other callback functions may require more complicated input and data
 209 to be allocated. Such an example is
 210 @funcref{gnutls_srp_set_server_credentials_function}.
 211 All callbacks should allocate and free memory using the functions shown below.
 212
 213 @showfuncB{gnutls_malloc,gnutls_free}
 214