path: root/doc/cha-library.texi

@node The Library
@chapter The Library

In brief @acronym{GnuTLS} can be described as a library which offers an API
to access secure communication protocols. These protocols provide
privacy over insecure lines, and were designed to prevent
eavesdropping, tampering, or message forgery.

Technically @acronym{GnuTLS} is a portable ANSI C based library which
implements the protocols ranging from SSL 3.0 to TLS 1.2 (see @ref{Introduction to TLS}, 
for a detailed description of the protocols), accompanied
with the required framework for authentication and public key
infrastructure.  Important features of the @acronym{GnuTLS} library
include:

@itemize

@item Support for TLS 1.2, TLS 1.1, TLS 1.0 and SSL 3.0 protocols.

@item Support for Datagram TLS 1.0.

@item Support for both @acronym{X.509} and @acronym{OpenPGP} certificates.

@item Support for handling and verification of certificates.

@item Support for @acronym{SRP} for TLS authentication.

@item Support for @acronym{PSK} for TLS authentication.

@item Support for TLS safe renegotiation.

@item Support for @acronym{PKCS} #11 tokens.

@end itemize

@acronym{GnuTLS} consists of three independent parts, namely the ``TLS
protocol part'', the ``Certificate part'', and the ``Cryptographic
back-end'' part.  The ``TLS protocol part'' is the actual protocol
implementation, and is entirely implemented within the
@acronym{GnuTLS} library.  The ``Certificate part'' consists of the
certificate parsing, and verification functions which is partially
implemented in the @acronym{GnuTLS} library.  The
libtasn1@footnote{@url{http://www.gnu.org/software/libtasn1/}},
a library which offers @acronym{ASN.1} parsing capabilities, is used
for the @acronym{X.509} certificate parsing functions.  
The ``Cryptographic back-end'' is provided by nettle@footnote{@url{http://www.lysator.liu.se/~nisse/nettle/}}
library.
In order to ease integration in embedded systems, parts of the
@acronym{GnuTLS} library can be disabled at compile time. That way a
smaller library, with the required features, can be generated.

@menu
* General idea::
* Error handling::
* Thread safety::
* Callback functions::
@end menu

@node General idea
@section General idea

A brief description of how @acronym{GnuTLS} works internally is shown
at @ref{fig:gnutls-design}. This section may be easier to understand after
having seen the examples at @ref{examples}.
As shown in the figure, there is a read-only global state that is
initialized once by the global initialization function.  This global
structure, among others, contains the memory allocation functions
used, and some structures needed for the @acronym{ASN.1} parser.  This
structure is never modified by any @acronym{GnuTLS} function, except
for the deinitialization function which frees all memory allocated in
the global structure and is called after the program has permanently
finished using @acronym{GnuTLS}.

@float Figure,fig:gnutls-design
@image{gnutls-internals,12cm}
@caption{High level design of GnuTLS.}
@end float

The credentials structure is used by some authentication methods, such
as certificate authentication.  A
credentials structure may contain certificates, private keys,
temporary parameters for Diffie-Hellman or RSA key exchange, and other
stuff that may be shared between several TLS sessions.

This structure should be initialized using the appropriate
initialization functions. For example an application which uses
certificate authentication would probably initialize the credentials,
using the appropriate functions, and put its trusted certificates in
this structure. The next step is to associate the credentials
structure with each @acronym{TLS} session.

A @acronym{GnuTLS} session contains all the required information for a
session to handle one secure connection. This session calls directly
to the transport layer functions, in order to communicate with the
peer.  Every session has a unique session ID shared with the peer.

Since TLS sessions can be resumed, servers would probably need a
database back-end to hold the session's parameters.  Every
@acronym{GnuTLS} session after a successful handshake calls the
appropriate back-end function (see @ref{resume}, for information on
initialization) to store the newly negotiated session. The session
database is examined by the server just after having received the
client hello@footnote{The first message in a @acronym{TLS} handshake},
and if the session ID sent by the client, matches a stored session,
the stored session will be retrieved, and the new session will be a
resumed one, and will share the same session ID with the previous one.

@node Error handling
@section Error handling
@subsection Conventions

In @acronym{GnuTLS} most functions return an integer type as a result.
In almost all cases a zero or a positive number means success, and a
negative number indicates failure, or a situation that some action has
to be taken. Thus negative error codes may be fatal or not.

Fatal errors terminate the connection immediately and further sends
and receives will be disallowed.  Such an example is
@code{GNUTLS_@-E_@-DECRYPTION_@-FAILED}. Non-fatal errors may warn about
something, i.e., a warning alert was received, or indicate the some
action has to be taken. This is the case with the error code
@code{GNUTLS_@-E_@-REHANDSHAKE} returned by @funcref{gnutls_record_recv}.
This error code indicates that the server requests a re-handshake. The
client may ignore this request, or may reply with an alert.  You can
test if an error code is a fatal one by using the
@funcref{gnutls_error_is_fatal}.

If any non fatal errors, that require an action, are to be returned by
a function, these error codes will be documented in the function's
reference.  See @ref{Error codes}, for a description of the available 
error codes.

@subsection Debugging and auditing

In many cases things may not go as expected and further information,
to assist debugging, from @acronym{GnuTLS} is desired. 
Those are the cases where the @funcref{gnutls_global_set_log_level} and
@funcref{gnutls_global_set_log_function} are to be used. Those will print
verbose information on the @acronym{GnuTLS} functions internal flow.

@showfuncB{gnutls_global_set_log_level,gnutls_global_set_log_function}

When debugging is not required, important issues, such as detected
attacks on the protocol still need to be logged. This is provided
by the logging function set by
@funcref{gnutls_global_set_audit_log_function}. The set function
accepts the detected error message and the corresponding
TLS session. The session information might be used to derive IP addresses
or other information about the peer involved.

@showfuncdesc{gnutls_global_set_audit_log_function}

@node Thread safety
@section Thread safety

Although the @acronym{GnuTLS} library is thread safe by design, some
parts of the cryptographic back-end, such as the random generator, are not.
Applications can either call @funcref{gnutls_global_init} which will use the default
operating system provided locks (i.e. @code{pthreads} on GNU/Linux and
@code{CriticalSection} on Windows), or specify manually the locking system using 
the function @funcref{gnutls_global_set_mutex} before calling @funcref{gnutls_global_init}. 
Setting manually mutexes is recommended
only to applications that have full control of the underlying libraries. If this
is not the case, the use of the operating system defaults is recommended. Examples
are shown below.


@example
#include <gnutls.h>

/* Native threads
 */

int main()
@{
   gnutls_global_init();
@}
@end example

@example
#include <gnutls.h>

/* Other thread packages
 */

int main()
@{
   gnutls_global_mutex_set (mutex_init, mutex_deinit, 
                            mutex_lock, mutex_unlock);
   gnutls_global_init();
@}
@end example

@node Callback functions
@section Callback functions
@cindex callback functions

There are several cases where @acronym{GnuTLS} may need out of
band input from your program. This is now implemented using some
callback functions, which your program is expected to register.

An example of this type of functions are the push and pull callbacks
which are used to specify the functions that will retrieve and send
data to the transport layer.

@showfuncB{gnutls_transport_set_push_function,gnutls_transport_set_pull_function}

Other callback functions may require more complicated input and data
to be allocated. Such an example is 
@funcref{gnutls_srp_set_server_credentials_function}.
All callbacks should allocate and free memory using the functions shown below.

@showfuncB{gnutls_malloc,gnutls_free}