102
102
For the complete list, refer to the output from @code{configure --help}.
105
@section General idea
107
A brief description of how @acronym{GnuTLS} works internally is shown
108
at @ref{fig:gnutls-design}. This section may be easier to understand after
109
having seen the examples at @ref{examples}.
110
As shown in the figure, there is a read-only global state that is
111
initialized once by the global initialization function. This global
112
structure, among others, contains the memory allocation functions
113
used, and structures needed for the @acronym{ASN.1} parser. This
114
structure is never modified by any @acronym{GnuTLS} function, except
115
for the deinitialization function which frees all allocated memory
116
and is called after the program has permanently
117
finished using @acronym{GnuTLS}.
119
@float Figure,fig:gnutls-design
120
@image{gnutls-internals,12cm}
121
@caption{High level design of GnuTLS.}
124
The credentials structures are used by the authentication methods, such
125
as certificate authentication. They store certificates, privates keys,
126
and other information that is needed to prove the identity to the peer,
127
and/or verify the indentity of the peer. The information stored in
128
the credentials structures is initialized once and then can be
129
shared by many @acronym{TLS} sessions.
131
A @acronym{GnuTLS} session contains all the required information
132
to handle one secure connection. The session communicates with the
133
peers using the provided functions of the transport layer.
134
Every session has a unique session ID shared with the peer.
136
Since TLS sessions can be resumed, servers need a
137
database back-end to hold the session's parameters. Every
138
@acronym{GnuTLS} session after a successful handshake calls the
139
appropriate back-end function (see @ref{resume})
140
to store the newly negotiated session. The session
141
database is examined by the server just after having received the
142
client hello@footnote{The first message in a @acronym{TLS} handshake},
143
and if the session ID sent by the client, matches a stored session,
144
the stored session will be retrieved, and the new session will be a
145
resumed one, and will share the same session ID with the previous one.
148
@section Error handling
149
@subsection Conventions
151
In @acronym{GnuTLS} most functions return an integer type as a result.
152
In almost all cases a zero or a positive number means success, and a
153
negative number indicates failure, or a situation that some action has
154
to be taken. Thus negative error codes may be fatal or not.
156
Fatal errors terminate the connection immediately and further sends
157
and receives will be disallowed. Such an example is
158
@code{GNUTLS_@-E_@-DECRYPTION_@-FAILED}. Non-fatal errors may warn about
159
something, i.e., a warning alert was received, or indicate the some
160
action has to be taken. This is the case with the error code
161
@code{GNUTLS_@-E_@-REHANDSHAKE} returned by @funcref{gnutls_record_recv}.
162
This error code indicates that the server requests a re-handshake. The
163
client may ignore this request, or may reply with an alert. You can
164
test if an error code is a fatal one by using the
165
@funcref{gnutls_error_is_fatal}.
167
If any non fatal errors, that require an action, are to be returned by
168
a function, these error codes will be documented in the function's
169
reference. See @ref{Error codes}, for a description of the available
172
@subsection Debugging and auditing
174
In many cases things may not go as expected and further information,
175
to assist debugging, from @acronym{GnuTLS} is desired.
176
Those are the cases where the @funcref{gnutls_global_set_log_level} and
177
@funcref{gnutls_global_set_log_function} are to be used. Those will print
178
verbose information on the @acronym{GnuTLS} functions internal flow.
180
@showfuncB{gnutls_global_set_log_level,gnutls_global_set_log_function}
182
When debugging is not required, important issues, such as detected
183
attacks on the protocol still need to be logged. This is provided
184
by the logging function set by
185
@funcref{gnutls_global_set_audit_log_function}. The provided function
186
will receive an message and the corresponding
187
TLS session. The session information might be used to derive IP addresses
188
or other information about the peer involved.
190
@showfuncdesc{gnutls_global_set_audit_log_function}
193
@section Thread safety
195
The @acronym{GnuTLS} library is thread safe by design, meaning that
196
objects of the library such as TLS sessions, can be safely divided across
197
threads as long as a single thread accesses a single object. This is
198
sufficient to support a server which handles several sessions per thread.
199
If, however, an object needs to be shared across threads then access must be
200
protected with a mutex. Read-only access to objects, for example the
201
credentials holding structures (see @ref{Authentication methods}), is also thread-safe.
203
The random generator of the cryptographic back-end, is not thread safe and requires
204
mutex locks which are setup by @acronym{GnuTLS}.
205
Applications can either call @funcref{gnutls_global_init} which will initialize the default
206
operating system provided locks (i.e. @code{pthreads} on GNU/Linux and
207
@code{CriticalSection} on Windows), or specify manually the locking system using
208
the function @funcref{gnutls_global_set_mutex} before calling @funcref{gnutls_global_init}.
209
Setting manually mutexes is recommended
210
only to applications that have full control of the underlying libraries. If this
211
is not the case, the use of the operating system defaults is recommended. An example of
212
non-native thread usage is shown below.
217
/* Other thread packages
222
gnutls_global_set_mutex (mutex_init, mutex_deinit,
223
mutex_lock, mutex_unlock);
224
gnutls_global_init();
228
@showfuncdesc{gnutls_global_set_mutex}
230
@node Callback functions
231
@section Callback functions
232
@cindex callback functions
234
There are several cases where @acronym{GnuTLS} may need out of
235
band input from your program. This is now implemented using some
236
callback functions, which your program is expected to register.
238
An example of this type of functions are the push and pull callbacks
239
which are used to specify the functions that will retrieve and send
240
data to the transport layer.
242
@showfuncB{gnutls_transport_set_push_function,gnutls_transport_set_pull_function}
244
Other callback functions may require more complicated input and data
245
to be allocated. Such an example is
246
@funcref{gnutls_srp_set_server_credentials_function}.
247
All callbacks should allocate and free memory using the functions shown below.
249
@showfuncB{gnutls_malloc,gnutls_free}
104
@node Document overview
106
In this document we present an overview of the supported security protocols in @ref{Introduction to TLS}, and
107
continue by providing more information on the certificate authentication in @ref{Certificate authentication},
108
and shared-key as well anonymous authentication in @ref{Shared-key and anonymous authentication}. We
109
elaborate on certificate authentication by demonstrating advanced usage of the API in @ref{More on certificate authentication}.
110
The core of the TLS library is presented in @ref{How to use GnuTLS in applications} and example
111
applications are listed in @ref{GnuTLS application examples}.
112
In @ref{Other included programs} the usage of few included programs that
113
may assist debugging is presented. The last chapter is @ref{Internal architecture of GnuTLS} that
114
provides a short introduction to GnuTLS' internal architecture.
added
removed
doc/cha-library.texi
