changes in asynchronous documentation
[gnutls:gnutls.git] / doc / cha-gtls-app.texi
1 @node How to use GnuTLS in applications
2 @chapter How to use @acronym{GnuTLS} in applications
3
4 @menu
5 * Introduction to the library::
6 * Preparation::
7 * Session initialization::
8 * Associating the credentials::
9 * Setting up the transport layer::
10 * TLS handshake::
11 * Data transfer and termination::
12 * Handling alerts::
13 * Priority Strings::
14 * Advanced and other topics::
15 * Using the cryptographic library::
16 * Selecting cryptographic key sizes::
17 @end menu
18
19 @node Introduction to the library
20 @section Introduction
21
22 @menu
23 * General idea::
24 * Error handling::
25 * Debugging and auditing::
26 * Thread safety::
27 * Callback functions::
28 @end menu
29
30 @node General idea
31 @subsection General idea
32
33 A brief description of how @acronym{GnuTLS} works internally is shown
34 at @ref{fig:gnutls-design}. This section may become more clear after
35 having read the rest of this section.
36 As shown in the figure, there is a read-only global state that is
37 initialized once by the global initialization function.  This global
38 structure, among others, contains the memory allocation functions
39 used, and structures needed for the @acronym{ASN.1} parser.  This
40 structure is never modified by any @acronym{GnuTLS} function, except
41 for the deinitialization function which frees all allocated memory
42 and is called after the program has permanently
43 finished using @acronym{GnuTLS}.
44
45 @float Figure,fig:gnutls-design
46 @image{gnutls-internals,12cm}
47 @caption{High level design of GnuTLS.}
48 @end float
49
50 The credentials structures are used by the authentication methods, such
51 as certificate authentication. They store certificates, privates keys,
52 and other information that is needed to prove the identity to the peer,
53 and/or verify the indentity of the peer. The information stored in
54 the credentials structures is initialized once and then can be 
55 shared by many @acronym{TLS} sessions.
56
57 A @acronym{GnuTLS} session contains all the required information
58 to handle one secure connection. The session communicates with the
59 peers using the provided functions of the transport layer.
60 Every session has a unique session ID shared with the peer.
61
62 Since TLS sessions can be resumed, servers need a
63 database back-end to hold the session's parameters.  Every
64 @acronym{GnuTLS} session after a successful handshake calls the
65 appropriate back-end function (see @ref{resume})
66 to store the newly negotiated session. The session
67 database is examined by the server just after having received the
68 client hello@footnote{The first message in a @acronym{TLS} handshake},
69 and if the session ID sent by the client, matches a stored session,
70 the stored session will be retrieved, and the new session will be a
71 resumed one, and will share the same session ID with the previous one.
72
73 @node Error handling
74 @subsection Error handling
75
76 In @acronym{GnuTLS} most functions return an integer type as a result.
77 In almost all cases a zero or a positive number means success, and a
78 negative number indicates failure, or a situation that some action has
79 to be taken. Thus negative error codes may be fatal or not.
80
81 Fatal errors terminate the connection immediately and further sends
82 and receives will be disallowed.  Such an example is
83 @code{GNUTLS_@-E_@-DECRYPTION_@-FAILED}. Non-fatal errors may warn about
84 something, i.e., a warning alert was received, or indicate the some
85 action has to be taken. This is the case with the error code
86 @code{GNUTLS_@-E_@-REHANDSHAKE} returned by @funcref{gnutls_record_recv}.
87 This error code indicates that the server requests a re-handshake. The
88 client may ignore this request, or may reply with an alert.  You can
89 test if an error code is a fatal one by using the
90 @funcref{gnutls_error_is_fatal}.
91
92 If any non fatal errors, that require an action, are to be returned by
93 a function, these error codes will be documented in the function's
94 reference.  See @ref{Error codes}, for a description of the available 
95 error codes.
96
97 @node Debugging and auditing
98 @subsection Debugging and auditing
99
100 In many cases things may not go as expected and further information,
101 to assist debugging, from @acronym{GnuTLS} is desired. 
102 Those are the cases where the @funcref{gnutls_global_set_log_level} and
103 @funcref{gnutls_global_set_log_function} are to be used. Those will print
104 verbose information on the @acronym{GnuTLS} functions internal flow.
105
106 @showfuncB{gnutls_global_set_log_level,gnutls_global_set_log_function}
107
108 When debugging is not required, important issues, such as detected
109 attacks on the protocol still need to be logged. This is provided
110 by the logging function set by
111 @funcref{gnutls_global_set_audit_log_function}. The provided function
112 will receive an message and the corresponding
113 TLS session. The session information might be used to derive IP addresses
114 or other information about the peer involved.
115
116 @showfuncdesc{gnutls_global_set_audit_log_function}
117
118 @node Thread safety
119 @subsection Thread safety
120 @cindex thread safety
121
122 The @acronym{GnuTLS} library is thread safe by design, meaning that
123 objects of the library such as TLS sessions, can be safely divided across
124 threads as long as a single thread accesses a single object. This is
125 sufficient to support a server which handles several sessions per thread.
126 If, however, an object needs to be shared across threads then access must be 
127 protected with a mutex. Read-only access to objects, for example the
128 credentials holding structures, is also thread-safe. 
129
130 The random generator of the cryptographic back-end, is not thread safe and requires
131 mutex locks which are setup by @acronym{GnuTLS}.
132 Applications can either call @funcref{gnutls_global_init} which will initialize the default
133 operating system provided locks (i.e. @code{pthreads} on GNU/Linux and
134 @code{CriticalSection} on Windows), or manually specify the locking system using
135 the function @funcref{gnutls_global_set_mutex} before calling @funcref{gnutls_global_init}. 
136 Setting mutexes manually is recommended
137 only for applications that have full control of the underlying libraries. If this
138 is not the case, the use of the operating system defaults is recommended. An example of 
139 non-native thread usage is shown below.
140
141 @example
142 #include <gnutls.h>
143
144 int main()
145 @{
146    /* When the system mutexes are not to be used 
147     * gnutls_global_set_mutex() must be called explicitly
148     */
149    gnutls_global_set_mutex (mutex_init, mutex_deinit, 
150                             mutex_lock, mutex_unlock);
151    gnutls_global_init();
152 @}
153 @end example
154
155 @showfuncdesc{gnutls_global_set_mutex}
156
157 @node Callback functions
158 @subsection Callback functions
159 @cindex callback functions
160
161 There are several cases where @acronym{GnuTLS} may need out of
162 band input from your program. This is now implemented using some
163 callback functions, which your program is expected to register.
164
165 An example of this type of functions are the push and pull callbacks
166 which are used to specify the functions that will retrieve and send
167 data to the transport layer.
168
169 @showfuncB{gnutls_transport_set_push_function,gnutls_transport_set_pull_function}
170
171 Other callback functions may require more complicated input and data
172 to be allocated. Such an example is 
173 @funcref{gnutls_srp_set_server_credentials_function}.
174 All callbacks should allocate and free memory using 
175 @funcintref{gnutls_malloc} and @funcintref{gnutls_free}.
176
177
178 @node Preparation
179 @section Preparation
180
181 To use @acronym{GnuTLS}, you have to perform some changes to your
182 sources and your build system. The necessary changes are explained in
183 the following subsections.
184
185 @menu
186 * Headers::
187 * Initialization::
188 * Version check::
189 * Building the source::
190 @end menu
191
192 @node Headers
193 @subsection Headers
194
195 All the data types and functions of the @acronym{GnuTLS} library are
196 defined in the header file @file{gnutls/gnutls.h}.  This must be
197 included in all programs that make use of the @acronym{GnuTLS}
198 library.
199
200 @node Initialization
201 @subsection Initialization
202
203 GnuTLS must be initialized before it can be used.  The library is
204 initialized by calling @funcref{gnutls_global_init}.  The resources
205 allocated by the initialization process can be released if the
206 application no longer has a need to call GnuTLS functions, this is
207 done by calling @funcref{gnutls_global_deinit}.
208
209 In order to take advantage of the internationalization features in
210 GnuTLS, such as translated error messages, the application must set
211 the current locale using @code{setlocale} before initializing GnuTLS.
212
213 @node Version check
214 @subsection Version check
215
216 It is often desirable to check that the version of `gnutls' used is
217 indeed one which fits all requirements.  Even with binary
218 compatibility new features may have been introduced but due to problem
219 with the dynamic linker an old version is actually used.  So you may
220 want to check that the version is okay right after program start-up.
221 See the function @funcref{gnutls_check_version}.
222
223 @node Building the source
224 @subsection Building the source
225
226 If you want to compile a source file including the
227 @file{gnutls/gnutls.h} header file, you must make sure that the
228 compiler can find it in the directory hierarchy.  This is accomplished
229 by adding the path to the directory in which the header file is
230 located to the compilers include file search path (via the @option{-I}
231 option).
232
233 However, the path to the include file is determined at the time the
234 source is configured.  To solve this problem, the library uses the
235 external package @command{pkg-config} that knows the path to the
236 include file and other configuration options.  The options that need
237 to be added to the compiler invocation at compile time are output by
238 the @option{--cflags} option to @command{pkg-config gnutls}.  The
239 following example shows how it can be used at the command line:
240
241 @example
242 gcc -c foo.c `pkg-config gnutls --cflags`
243 @end example
244
245 Adding the output of @samp{pkg-config gnutls --cflags} to the
246 compilers command line will ensure that the compiler can find the
247 @file{gnutls/gnutls.h} header file.
248
249 A similar problem occurs when linking the program with the library.
250 Again, the compiler has to find the library files.  For this to work,
251 the path to the library files has to be added to the library search
252 path (via the @option{-L} option).  For this, the option
253 @option{--libs} to @command{pkg-config gnutls} can be used.  For
254 convenience, this option also outputs all other options that are
255 required to link the program with the library (for instance, the
256 @samp{-ltasn1} option).  The example shows how to link @file{foo.o}
257 with the library to a program @command{foo}.
258
259 @example
260 gcc -o foo foo.o `pkg-config gnutls --libs`
261 @end example
262
263 Of course you can also combine both examples to a single command by
264 specifying both options to @command{pkg-config}:
265
266 @example
267 gcc -o foo foo.c `pkg-config gnutls --cflags --libs`
268 @end example
269
270 When a program uses the GNU autoconf system, then the following
271 line or similar can be used to detect the presence of GnuTLS.
272
273 @example
274 PKG_CHECK_MODULES([LIBGNUTLS], [gnutls >= 3.0.0])
275
276 AC_SUBST([LIBGNUTLS_CFLAGS])
277 AC_SUBST([LIBGNUTLS_LIBS])
278 @end example
279
280 @node Session initialization
281 @section Session initialization
282
283 In the previous sections we have discussed the global initialization
284 required for GnuTLS as well as the initialization required for each
285 authentication method's credentials (see @ref{Authentication}).
286 In this section we elaborate on the TLS or DTLS session initiation.
287 Each session is initialized using @funcref{gnutls_init} which among
288 others is used to specify the type of the connection (server or client), 
289 and the underlying protocol type, i.e., datagram (UDP) or reliable (TCP).
290
291 @showfuncdesc{gnutls_init}
292
293 After the session initialization details on the allowed ciphersuites
294 and protocol versions should be set using the priority functions
295 such as @funcref{gnutls_priority_set_direct}. We elaborate on them
296 in @ref{Priority Strings}.
297 The credentials used for the key exchange method, such as certificates 
298 or usernames and passwords should also be associated with the session
299 current session using @funcref{gnutls_credentials_set}. 
300
301 @showfuncdesc{gnutls_credentials_set}
302
303 @node Associating the credentials
304 @section Associating the credentials
305
306 @menu
307 * Certificate credentials::
308 * SRP credentials::
309 * PSK credentials::
310 * Anonymous credentials::
311 @end menu
312
313 Each authentication method is associated with a key exchange method, and a credentials type. 
314 The contents of the credentials is method-dependent, e.g. certificates
315 for certificate authentication and should be initialized and associated
316 with a session (see @funcref{gnutls_credentials_set}).  A mapping of the key exchange methods
317 with the credential types is shown in @ref{tab:key-exchange-cred}.
318
319 @float Table,tab:key-exchange-cred
320 @multitable @columnfractions .25 .25 .2 .2
321
322 @headitem Authentication method @tab Key exchange @tab Client credentials @tab Server credentials
323
324 @item Certificate
325 @tab @code{KX_RSA},
326 @code{KX_DHE_RSA},
327 @code{KX_DHE_DSS},
328 @code{KX_ECDHE_RSA},
329 @code{KX_ECDHE_ECDSA},
330 @code{KX_RSA_EXPORT}
331 @tab @code{CRD_CERTIFICATE}
332 @tab @code{CRD_CERTIFICATE}
333
334 @item Password and certificate
335 @tab @code{KX_SRP_RSA}, @code{KX_SRP_DSS}
336 @tab @code{CRD_SRP}
337 @tab @code{CRD_CERTIFICATE}, @code{CRD_SRP}
338
339 @item Password
340 @tab @code{KX_SRP}
341 @tab @code{CRD_SRP}
342 @tab @code{CRD_SRP}
343
344 @item Anonymous
345 @tab @code{KX_ANON_DH},
346 @code{KX_ANON_ECDH}
347 @tab @code{CRD_ANON}
348 @tab @code{CRD_ANON}
349
350 @item Pre-shared key
351 @tab @code{KX_PSK},
352 @code{KX_DHE_PSK}, @code{KX_ECDHE_PSK}
353 @tab @code{CRD_PSK}
354 @tab @code{CRD_PSK}
355
356 @end multitable
357 @caption{Key exchange algorithms and the corresponding credential types.}
358 @end float
359
360 @node Certificate credentials
361 @subsection Certificates
362 @subsubheading Server certificate authentication
363
364 When using certificates the server is required to have at least one
365 certificate and private key pair. Clients may not hold such
366 a pair, but a server could require it. In this section we discuss
367 general issues applying to both client and server certificates. The next
368 section will elaborate on issues arising from client authentication only.
369
370 @showfuncB{gnutls_certificate_allocate_credentials,gnutls_certificate_free_credentials}
371
372 After the credentials structures are initialized, the certificate 
373 and key pair must be loaded. This occurs before any @acronym{TLS} 
374 session is initialized, and the same structures are reused for multiple sessions.
375 Depending on the certificate type different loading functions
376 are available, as shown below.
377 For @acronym{X.509} certificates, the functions will
378 accept and use a certificate chain that leads to a trusted
379 authority. The certificate chain must be ordered in such way that every
380 certificate certifies the one before it. The trusted authority's
381 certificate need not to be included since the peer should possess it
382 already.
383
384 @showfuncC{gnutls_certificate_set_x509_key_mem,gnutls_certificate_set_x509_key,gnutls_certificate_set_x509_key_file}
385
386 @showfuncD{gnutls_certificate_set_openpgp_key_mem,gnutls_certificate_set_openpgp_key,gnutls_certificate_set_openpgp_key_file,gnutls_certificate_set_key}
387
388 If multiple certificates are used with the functions above each
389 client's request will be served with the certificate that matches the
390 requested name (see @ref{Server name indication}).
391
392 As an alternative to loading from files or buffers, a callback may be used for the 
393 server or the client to specify the certificate and the key at the handshake time.
394 In that case a certificate should be selected according the peer's signature
395 algorithm preferences. To get those preferences use
396 @funcref{gnutls_sign_algorithm_get_requested}. Both functions are shown below.
397
398 @showfuncB{gnutls_certificate_set_retrieve_function,gnutls_sign_algorithm_get_requested}
399
400 The functions above do not handle the requested server name automatically.
401 A server would need to check the name requested by the client
402 using @funcref{gnutls_server_name_get}, and serve the appropriate
403 certificate.
404
405 In a handshake, the negotiated cipher suite depends on the
406 certificate's parameters, so some key exchange methods might not be
407 available with all certificates. @acronym{GnuTLS} will disable
408 ciphersuites that are not compatible with the key, or the enabled
409 authentication methods.  For example keys marked as sign-only, will
410 not be able to access the plain RSA ciphersuites, that require
411 decryption. It is not recommended to use RSA keys for both
412 signing and encryption. If possible use a different key for the
413 @code{DHE-RSA} which uses signing and @code{RSA} that requires decryption.
414 All the key exchange methods shown in @ref{tab:key-exchange} are
415 available in certificate authentication.
416
417
418 @subsubheading Client certificate authentication
419
420 If a certificate is to be requested from the client during the handshake, the server
421 will send a certificate request message. This behavior is controlled @funcref{gnutls_certificate_server_set_request}.
422 The request contains a list of the acceptable by the server certificate signers. This list
423 is constructed using the trusted certificate authorities of the server.
424 In cases where the server supports a large number of certificate authorities
425 it makes sense not to advertise all of the names to save bandwidth. That can
426 be controlled using the function @funcref{gnutls_certificate_send_x509_rdn_sequence}. 
427 This however will have the side-effect of not restricting the client to certificates
428 signed by server's acceptable signers.
429
430 @showfuncdesc{gnutls_certificate_server_set_request}
431
432 @showfuncdesc{gnutls_certificate_send_x509_rdn_sequence}
433
434
435 @subsubheading Client or server certificate verification
436
437 Certificate verification is possible by loading the trusted
438 authorities into the credentials structure by using
439 the following functions, applicable to X.509 and OpenPGP certificates.
440
441 @showfuncB{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_openpgp_keyring_file}
442
443 The peer's certificate is not automatically verified and one 
444 should call @funcref{gnutls_certificate_verify_peers2}
445 after a successful handshake to verify the certificate's signature.
446 Alternative the verification can occur during the handshake
447 by using @funcref{gnutls_certificate_set_verify_function}.
448
449 In order to report a detailed verification output, an alternative
450 way has to be used. For that, one should call @funcref{gnutls_certificate_get_peers} 
451 to obtain the raw certificate of the peer and verify it using the
452 functions discussed in @ref{X.509 certificates}.
453
454 @showfuncdesc{gnutls_certificate_verify_peers2}
455
456 @showfuncdesc{gnutls_certificate_set_verify_function}
457
458
459
460 @node SRP credentials
461 @subsection SRP
462
463 The initialization functions in SRP credentials differ between
464 client and server.
465 Clients supporting @acronym{SRP} should set the username and password
466 prior to connection, to the credentials structure.
467 Alternatively @funcref{gnutls_srp_set_client_credentials_function}
468 may be used instead, to specify a callback function that should return the
469 SRP username and password.
470 The callback is called once during the @acronym{TLS} handshake.
471
472 @showfuncE{gnutls_srp_allocate_server_credentials,gnutls_srp_allocate_client_credentials,gnutls_srp_free_server_credentials,gnutls_srp_free_client_credentials,gnutls_srp_set_client_credentials}
473
474 @showfuncdesc{gnutls_srp_set_client_credentials_function}
475
476 In server side the default behavior of @acronym{GnuTLS} is to read
477 the usernames and @acronym{SRP} verifiers from password files. These
478 password file format is compatible the with the @emph{Stanford srp libraries}
479 format.  If a different password file format is to be used, then 
480 @funcref{gnutls_srp_set_server_credentials_function} should be called,
481 to set an appropriate callback. 
482
483 @showfuncdesc{gnutls_srp_set_server_credentials_file}
484
485 @showfuncdesc{gnutls_srp_set_server_credentials_function}
486
487
488 @node PSK credentials
489 @subsection PSK
490 The initialization functions in PSK credentials differ between
491 client and server.
492
493 @showfuncD{gnutls_psk_allocate_server_credentials,gnutls_psk_allocate_client_credentials,gnutls_psk_free_server_credentials,gnutls_psk_free_client_credentials}
494
495 Clients supporting @acronym{PSK} should supply the username and key
496 before a TLS session is established.  Alternatively 
497 @funcref{gnutls_psk_set_client_credentials_function} can be used to
498 specify a callback function. This has the
499 advantage that the callback will be called only if @acronym{PSK} has
500 been negotiated.
501
502 @showfuncA{gnutls_psk_set_client_credentials}
503
504 @showfuncdesc{gnutls_psk_set_client_credentials_function}
505
506 In server side the default behavior of @acronym{GnuTLS} is to read
507 the usernames and @acronym{PSK} keys from a password file. The
508 password file should contain usernames and keys in hexadecimal
509 format. The name of the password file can be stored to the credentials
510 structure by calling @funcref{gnutls_psk_set_server_credentials_file}.  If
511 a different password file format is to be used, then
512 a callback should be set instead by @funcref{gnutls_psk_set_server_credentials_function}.
513
514 The server can help the client chose a suitable username and password,
515 by sending a hint. Note that there is no common profile for the PSK hint and applications
516 are discouraged to use it.
517 A server, may specify the hint by calling
518 @funcref{gnutls_psk_set_server_credentials_hint}.  The client can retrieve
519 the hint, for example in the callback function, using
520 @funcref{gnutls_psk_client_get_hint}.
521
522 @showfuncdesc{gnutls_psk_set_server_credentials_file}
523
524 @showfuncC{gnutls_psk_set_server_credentials_function,gnutls_psk_set_server_credentials_hint,gnutls_psk_client_get_hint}
525
526 @node Anonymous credentials
527 @subsection Anonymous
528 The key exchange methods for anonymous authentication
529 might require Diffie-Hellman parameters to be generated by the server and
530 associated with an anonymous credentials structure. Check
531 @ref{Parameter generation} for more information.
532 The initialization functions for the credentials are shown below.
533
534 @showfuncD{gnutls_anon_allocate_server_credentials,gnutls_anon_allocate_client_credentials,gnutls_anon_free_server_credentials,gnutls_anon_free_client_credentials}
535
536
537
538 @node Setting up the transport layer
539 @section Setting up the transport layer
540
541 The next step is to setup the underlying transport layer details. The
542 Berkeley sockets are implicitly used by GnuTLS, thus a
543 call to @funcref{gnutls_transport_set_ptr2} would be sufficient to
544 specify the socket descriptor.
545
546 @showfuncdesc{gnutls_transport_set_ptr2}
547
548 @showfuncA{gnutls_transport_set_ptr}
549
550 If however another transport layer than TCP is selected, then
551 the following functions have to be specified.
552
553 @showfuncdesc{gnutls_transport_set_push_function}
554 @showfuncdesc{gnutls_transport_set_vec_push_function}
555 @showfuncdesc{gnutls_transport_set_pull_function}
556
557 The functions above accept a callback function which
558 should return the number of bytes written, or -1 on
559 error and should set @code{errno} appropriately.
560 In some environments, setting @code{errno} is unreliable. For example
561 Windows have several errno variables in different CRTs, or in other
562 systems it may be a non thread-local variable.  If this is a concern to
563 you, call @funcref{gnutls_transport_set_errno} with the intended errno
564 value instead of setting @code{errno} directly.
565
566 @showfuncdesc{gnutls_transport_set_errno}
567
568 @acronym{GnuTLS} currently only interprets the EINTR and EAGAIN errno
569 values and returns the corresponding @acronym{GnuTLS} error codes:
570 @itemize
571 @item @code{GNUTLS_E_INTERRUPTED} 
572 @item @code{GNUTLS_E_AGAIN}
573 @end itemize
574 The EINTR and EAGAIN values are returned by interrupted system calls, 
575 or when non blocking IO is used.  All @acronym{GnuTLS} functions can be 
576 resumed (called again), if any of the above error codes is returned.  
577
578 In the case of DTLS it is also desirable to override the generic 
579 transport functions with functions that emulate the operation
580 of @code{recvfrom} and @code{sendto}. In addition
581 @acronym{DTLS} requires timers during the receive of a handshake
582 message, set using the @funcref{gnutls_transport_set_pull_timeout_function} 
583 function. To check the retransmission timers the function
584 @funcref{gnutls_dtls_get_timeout} is provided, which returns the time
585 remaining until the next retransmission, or better the time until 
586 @funcref{gnutls_handshake} should be called again.
587
588 @showfuncdesc{gnutls_transport_set_pull_timeout_function}
589 @showfuncdesc{gnutls_dtls_get_timeout}
590
591 @menu
592 * Asynchronous operation::
593 * DTLS sessions::
594 @end menu
595
596 @node Asynchronous operation
597 @subsection Asynchronous operation
598 @acronym{GnuTLS} can be used with asynchronous socket or event-driven programming.
599 The approach is similar to using Berkeley sockets under such an environment.
600 The blocking, due to network interaction, calls such as
601 @funcref{gnutls_handshake}, @funcref{gnutls_record_recv},
602 can be set to non-blocking by setting the underlying sockets to non-blocking.
603 If other push and pull functions are setup, then they should behave the same
604 way as @funcintref{recv} and @funcintref{send} when used in a non-blocking
605 way, i.e., set errno to @code{EAGAIN}. Since, during a TLS protocol session 
606 @acronym{GnuTLS} does not block except for network interaction, the non blocking
607 @code{EAGAIN} errno will be propagated and @acronym{GnuTLS} functions 
608 will return the @code{GNUTLS_E_AGAIN} error code. Such calls can be resumed the 
609 same way as a system call would. 
610 The only exception is @funcref{gnutls_record_send},
611 which if interrupted subsequent calls need not to include the data to be
612 sent (can be called with NULL argument).
613
614 The @funcintref{select} system call can also be used in combination with the
615 @acronym{GnuTLS} functions. @funcintref{select} allows monitoring of sockets
616 and notifies on them being ready for reading or writing data. Note however
617 that this system call cannot notify on data present in @acronym{GnuTLS}
618 read buffers, it is only applicable to the kernel sockets API. Thus if
619 you are using it for reading from a @acronym{GnuTLS} session, make sure
620 that any cached data are read completely. That can be achieved by checking there 
621 are no data waiting to be read (using @funcref{gnutls_record_check_pending}), 
622 either before the @funcintref{select} system call, or after a call to
623 @funcref{gnutls_record_recv}. @acronym{GnuTLS} does not keep a write buffer,
624 thus when writing no additional actions are required.
625
626 In the DTLS, however, @acronym{GnuTLS} may block due to retransmission timers
627 required by the protocol. To prevent those timers from blocking a DTLS handshake,
628 the @funcref{gnutls_init} should be called with the
629 @code{GNUTLS_NONBLOCK} flag (see @ref{Session initialization}).
630
631 @node DTLS sessions
632 @subsection DTLS sessions
633
634 Because datagram TLS can operate over connections where the peer
635 of a server cannot be reliably verified, functionality is available to prevent
636 denial of service attacks. @acronym{GnuTLS} requires a server
637 to generate a secret key that is used to sign a cookie@footnote{A key of 128 bits or 16 bytes should be sufficient for this purpose.}. 
638 That cookie is sent to the client using @funcref{gnutls_dtls_cookie_send}, and 
639 the client must reply using the correct cookie. The server side
640 should verify the initial message sent by client using @funcref{gnutls_dtls_cookie_verify}.
641 If successful the session should be initialized and associated with
642 the cookie using @funcref{gnutls_dtls_prestate_set}, before proceeding to
643 the handshake.
644
645 @showfuncD{gnutls_key_generate,gnutls_dtls_cookie_send,gnutls_dtls_cookie_verify,gnutls_dtls_prestate_set}
646
647 Note that the above apply to server side only and they are not mandatory to be
648 used. Not using them, however, allows denial of service attacks.
649 The client side cookie handling is part of @funcref{gnutls_handshake}. 
650
651 Datagrams are typically restricted by a maximum transfer unit (MTU). For that
652 both client and server side should set the correct maximum transfer unit for
653 the layer underneath @acronym{GnuTLS}. This will allow proper fragmentation
654 of DTLS messages and prevent messages from being silently discarded by the
655 transport layer. The ``correct'' maximum transfer unit can be obtained through
656 a path MTU discovery mechanism @xcite{RFC4821}.
657
658 @showfuncC{gnutls_dtls_set_mtu,gnutls_dtls_get_mtu,gnutls_dtls_get_data_mtu}
659
660
661 @node TLS handshake
662 @section TLS handshake
663 Once a session has been initialized and a network
664 connection has been set up, TLS and DTLS protocols
665 perform a handshake. The handshake is the actual key
666 exchange.
667
668 @showfuncdesc{gnutls_handshake}
669
670 The handshake process doesn't ensure the verification
671 of the peer's identity. When certificates are in use,
672 this can be done, either after the handshake is complete, or during 
673 the handshake if @funcref{gnutls_certificate_set_verify_function}
674 has been used. In both cases the @funcref{gnutls_certificate_verify_peers2} function can be
675 used to verify the peer's certificate (see @ref{Certificate authentication}
676 for more information).
677
678 @showfuncA{gnutls_certificate_verify_peers2}
679
680 @node Data transfer and termination
681 @section Data transfer and termination
682 Once the handshake is complete and peer's identity
683 has been verified data can be exchanged. The available
684 functions resemble the POSIX @code{recv} and @code{send}
685 functions. It is suggested to use @funcref{gnutls_error_is_fatal}
686 to check whether the error codes returned by these functions are
687 fatal for the protocol or can be ignored.
688
689 @showfuncdesc{gnutls_record_send}
690
691 @showfuncdesc{gnutls_record_recv}
692
693 @showfuncdesc{gnutls_error_is_fatal}
694
695 In DTLS it is advisable to use the extended receive
696 function shown below, because it allows the extraction
697 of the sequence number. This is required in DTLS because
698 messages may arrive out of order.
699
700 @showfuncdesc{gnutls_record_recv_seq}
701
702 The @funcref{gnutls_record_check_pending} helper function is available to 
703 allow checking whether data are available to be read in a @acronym{GnuTLS} session 
704 buffers. Note that this function complements but does not replace @funcintref{select},
705 i.e., @funcref{gnutls_record_check_pending} reports no data to be read, @funcintref{select}
706 should be called to check for data in the network buffers.
707
708 @showfuncdesc{gnutls_record_check_pending}
709 @showfuncA{gnutls_record_get_direction}
710
711 Once a TLS or DTLS session is no longer needed, it is
712 recommended to use @funcref{gnutls_bye} to terminate the
713 session. That way the peer is notified securely about the
714 intention of termination, which allows distinguishing it
715 from a malicious connection termination.
716 A session can be deinitialized with the @funcref{gnutls_deinit} function.
717
718 @showfuncdesc{gnutls_bye}
719 @showfuncdesc{gnutls_deinit}
720
721 @node Handling alerts
722 @section Handling alerts
723 During a TLS connection alert messages may be exchanged by the
724 two peers. Those messages may be fatal, meaning the connection
725 must be terminated afterwards, or warning when something needs
726 to be reported to the peer, but without interrupting the session.
727 The error codes @code{GNUTLS_E_WARNING_ALERT_RECEIVED}
728 or @code{GNUTLS_E_FATAL_ALERT_RECEIVED} signal those alerts
729 when received, and may be returned by all GnuTLS functions that receive 
730 data from the peer, being @funcref{gnutls_handshake} and @funcref{gnutls_record_recv}.
731 Alerts messages may be sent to the peer using @funcref{gnutls_alert_send}.
732
733 @showfuncdesc{gnutls_alert_get}
734
735 @showfuncdesc{gnutls_alert_send}
736
737 @showfuncB{gnutls_error_to_alert,gnutls_alert_get_name}
738
739
740 @node Priority Strings
741 @section Priority strings
742 @cindex Priority strings
743
744 In order to specify cipher suite preferences on a TLS session
745 there are priority functions that accept a string
746 specifying the enabled for the handshake algorithms.
747 That string may contain a single initial keyword such as
748 in @ref{tab:prio-keywords} and may be followed by
749 additional algorithm or special keywords.
750
751 @showfuncB{gnutls_priority_set_direct,gnutls_priority_set}
752
753 @float Table,tab:prio-keywords
754 @multitable @columnfractions .20 .70
755 @headitem Keyword @tab Description
756 @item PERFORMANCE @tab
757 All the known to be secure ciphersuites are enabled,
758 limited to 128 bit ciphers and sorted by terms of speed
759 performance. The message authenticity security level is of 64 bits or more.
760
761 @item NORMAL @tab
762 Means all the known to be secure ciphersuites. The ciphers are sorted by security
763 margin, although the 256-bit ciphers are included as a fallback only.
764 The message authenticity security level is of 64 bits or more.
765
766 @item SECURE128 @tab
767 Means all known to be secure ciphersuites that offer a 
768 security level 128-bit or more and a message authenticity
769 security level of 80 bits or more.
770
771 @item SECURE192 @tab
772 Means all the known to be secure ciphersuites that offer a 
773 security level 192-bit or more and a message authenticity
774 security level of 128 bits or more.
775
776 @item SECURE256 @tab
777 Currently alias for SECURE192.
778
779 @item SUITEB128 @tab
780 Means all the NSA Suite B cryptography (RFC5430) ciphersuites
781 with an 128 bit security level.
782
783 @item SUITEB192 @tab
784 Means all the NSA Suite B cryptography (RFC5430) ciphersuites
785 with an 192 bit security level.
786
787 @item EXPORT @tab
788 Means all ciphersuites are enabled, including the
789 low-security 40 bit ciphers.
790
791 @item NONE @tab
792 Means nothing is enabled.  This disables even protocols and
793 compression methods. It should be followed by the
794 algorithms to be enabled.
795
796 @end multitable
797 @caption{Supported initial keywords.}
798 @end float
799
800 Unless the initial keyword is "NONE" the defaults (in preference
801 order) are for TLS protocols TLS 1.2, TLS1.1, TLS1.0, SSL3.0; for
802 compression NULL; for certificate types X.509.
803 In key exchange algorithms when in NORMAL or SECURE levels the
804 perfect forward secrecy algorithms take precedence of the other
805 protocols.  In all cases all the supported key exchange algorithms
806 are enabled@footnote{Except for the RSA-EXPORT which is only enabled in
807 EXPORT level.}.
808
809 Note that the SECURE levels distinguish between overall security level and
810 message authenticity security level. That is because the message
811 authenticity security level requires the adversary to break
812 the algorithms at real-time during the protocol run, whilst 
813 the overall security level refers to off-line adversaries 
814 (e.g. adversaries breaking the ciphertext years after it was captured).
815
816 The NONE keyword, if used, must followed by keywords specifying 
817 the algorithms and protocols to be enabled. The other initial keywords may be 
818 followed by such keywords.
819 The order with which every algorithm or protocol
820 is specified is significant. Algorithms specified before others
821 will take precedence. The supported algorithms and protocols
822 are shown in @ref{tab:prio-algorithms}. 
823 To avoid collisions in order to specify a compression algorithm in
824 the priority string you have to prefix it with "COMP-", protocol versions
825 with "VERS-", signature algorithms with "SIGN-" and certificate types with "CTYPE-". 
826 All other algorithms don't need a prefix. Each specified keyword can
827 be prefixed with any of the following characters.
828
829 @table @asis
830 @item '!' or '-' 
831 appended with an algorithm will remove this algorithm.
832 @item "+" 
833 appended with an algorithm will add this algorithm.
834 @end table
835
836 @float Table,tab:prio-algorithms
837 @multitable @columnfractions .20 .70
838 @headitem Type @tab Keywords
839 @item Ciphers @tab
840 AES-128-CBC, AES-256-CBC, AES-128-GCM, CAMELLIA-128-CBC,
841 CAMELLIA-256-CBC, ARCFOUR-128, 3DES-CBC ARCFOUR-40. Catch all
842 name is CIPHER-ALL which will add all the algorithms from NORMAL
843 priority.
844
845 @item Key exchange @tab
846 RSA, DHE-RSA, DHE-DSS, SRP, SRP-RSA, SRP-DSS,
847 PSK, DHE-PSK, ECDHE-RSA, ANON-ECDH, ANON-DH, RSA-EXPORT. The
848 Catch all name is KX-ALL which will add all the algorithms from NORMAL
849 priority.
850
851 @item MAC @tab
852 MD5, SHA1, SHA256, AEAD (used with
853 GCM ciphers only). All algorithms from NORMAL priority can be accessed with MAC-ALL.
854
855 @item Compression algorithms @tab
856 COMP-NULL, COMP-DEFLATE. Catch all is COMP-ALL.
857
858 @item TLS versions @tab
859 VERS-SSL3.0, VERS-TLS1.0, VERS-TLS1.1,
860 VERS-TLS1.2, VERS-DTLS1.0. Catch all is VERS-TLS-ALL.
861
862 @item Signature algorithms @tab
863 SIGN-RSA-SHA1, SIGN-RSA-SHA224, 
864 SIGN-RSA-SHA256, SIGN-RSA-SHA384, SIGN-RSA-SHA512, SIGN-DSA-SHA1, 
865 SIGN-DSA-SHA224, SIGN-DSA-SHA256, SIGN-RSA-MD5. Catch all
866 is SIGN-ALL. This is only valid for TLS 1.2 and later.
867
868 @item Elliptic curves @tab
869 CURVE-SECP192R1, CURVE-SECP224R1, CURVE-SECP256R1, CURVE-SECP384R1, CURVE-SECP521R1. Catch all is CURVE-ALL.
870
871 @end multitable
872 @caption{The supported algorithm keywords in priority strings.}
873 @end float
874
875 Note that the DHE key exchange methods are generally
876 slower@footnote{It depends on the group used.  Primes with
877 lesser bits are always faster, but also easier to break.  See @ref{Selecting cryptographic key sizes}
878 for the acceptable security levels.} than their elliptic curves counterpart
879 (ECDHE). Moreover the plain Diffie-Hellman key exchange
880 requires parameters to be generated and associated with a credentials
881 structure by the server (see @ref{Parameter generation}). 
882
883 The available special keywords are shown in @ref{tab:prio-special}. 
884
885 @float Table,tab:prio-special
886 @multitable @columnfractions .45 .45
887 @headitem Keyword @tab Description
888
889 @item %COMPAT @tab
890 will enable compatibility mode. It might mean that violations
891 of the protocols are allowed as long as maximum compatibility with
892 problematic clients and servers is achieved. More specifically this
893 string would disable TLS record random padding and tolerate packets
894 over the maximum allowed TLS record.
895
896 @item %NO_EXTENSIONS @tab
897 will prevent the sending of any TLS extensions in client side. Note
898 that TLS 1.2 requires extensions to be used, as well as safe
899 renegotiation thus this option must be used with care.
900
901 @item %SERVER_PRECEDENCE @tab
902 The ciphersuite will be selected according to server priorities
903 and not the client's.
904
905 @item %DISABLE_SAFE_RENEGOTIATION @tab
906 will disable safe renegotiation
907 completely.  Do not use unless you know what you are doing.
908 Testing purposes only.
909
910 @item %UNSAFE_RENEGOTIATION @tab
911 will allow handshakes and re-handshakes
912 without the safe renegotiation extension.  Note that for clients
913 this mode is insecure (you may be under attack), and for servers it
914 will allow insecure clients to connect (which could be fooled by an
915 attacker).  Do not use unless you know what you are doing and want
916 maximum compatibility.
917
918 @item %PARTIAL_RENEGOTIATION @tab
919 will allow initial handshakes to proceed,
920 but not re-handshakes.  This leaves the client vulnerable to attack,
921 and servers will be compatible with non-upgraded clients for
922 initial handshakes.  This is currently the default for clients and
923 servers, for compatibility reasons.
924
925 @item %SAFE_RENEGOTIATION @tab
926 will enforce safe renegotiation.  Clients and
927 servers will refuse to talk to an insecure peer.  Currently this
928 causes interoperability problems, but is required for full protection.
929
930 @item %SSL3_RECORD_VERSION @tab
931 will use SSL3.0 record version in client hello.
932 This is the default.
933
934 @item %LATEST_RECORD_VERSION @tab
935 will use the latest TLS version record version in client hello.
936
937 @item %VERIFY_ALLOW_SIGN_RSA_MD5 @tab
938 will allow RSA-MD5 signatures in certificate chains.
939
940 @item %VERIFY_ALLOW_X509_V1_CA_CRT @tab
941 will allow V1 CAs in chains.
942
943 @end multitable
944 @caption{Special priority string keywords.}
945 @end float
946
947 Finally the ciphersuites enabled by any priority string can be
948 listed using the @code{gnutls-cli} application (see @ref{gnutls-cli Invocation}), 
949 or by using the priority functions as in @ref{Listing the ciphersuites in a priority string}.
950
951 Example priority strings are:
952 @example
953 The default priority without the HMAC-MD5:
954     "NORMAL:-MD5"
955
956 Specifying RSA with AES-128-CBC:
957     "NONE:+VERS-TLS-ALL:+MAC-ALL:+RSA:+AES-128-CBC:+SIGN-ALL:+COMP-NULL"
958
959 Specifying the defaults except ARCFOUR-128:
960     "NORMAL:-ARCFOUR-128"
961
962 Enabling the 128-bit secure ciphers, while disabling SSL 3.0 and 
963 enabling compression:
964     "SECURE128:-VERS-SSL3.0:+COMP-DEFLATE"
965 @end example
966
967 @node Advanced and other topics
968 @section Advanced and other topics
969
970 @menu
971 * Session resumption::
972 * Parameter generation::
973 * Keying Material Exporters::
974 * Channel Bindings::
975 * Interoperability::
976 * Compatibility with the OpenSSL library::
977 @end menu
978
979 @node Session resumption
980 @subsection Session resumption
981 @cindex resuming sessions
982 @cindex session resumption
983
984 @subsubheading Client side
985
986 To reduce time and roundtrips spent in a handshake the client can   
987 request session resumption from a server that previously shared
988 a session with. For that the client has to retrieve and store
989 the session parameters. Before establishing a new session to the same 
990 server the parameters must be re-associated with the GnuTLS session
991 using @funcref{gnutls_session_set_data}.
992
993 @showfuncC{gnutls_session_get_data,gnutls_session_get_id,gnutls_session_set_data}
994
995 Keep in mind that sessions will be expired after some time, depending
996 on the server, and a server may choose not to resume a session
997 even when requested to.  The expiration is to prevent temporal session keys
998 from becoming long-term keys. Also note that as a client you must enable, 
999 using the priority functions, at least the algorithms used in the last session.
1000
1001 It is highly recommended for clients to enable the session ticket extension using
1002 @funcref{gnutls_session_ticket_enable_client} in order to allow resumption with 
1003 servers that do not store any state.
1004
1005 @showfuncA{gnutls_session_ticket_enable_client}
1006
1007 @showfuncdesc{gnutls_session_is_resumed}
1008
1009 @subsubheading Server side
1010
1011 In order to support resumption a server can store
1012 the session security parameters in a local database or by using session
1013 tickets (see @ref{Session tickets}) to delegate storage to the client. Because
1014 session tickets might not be supported by all clients, servers
1015 could combine the two methods.
1016
1017 A storing server needs to specify callback functions to store, retrieve and delete session data. These can be
1018 registered with the functions below. The stored sessions in the database can be checked using @funcref{gnutls_db_check_entry}
1019 for expiration.
1020
1021 @showfuncD{gnutls_db_set_retrieve_function,gnutls_db_set_store_function,gnutls_db_set_ptr,gnutls_db_set_remove_function}
1022 @showfuncA{gnutls_db_check_entry}
1023
1024 A server utilizing tickets should generate ticket encryption
1025 and authentication keys using @funcref{gnutls_session_ticket_key_generate}.
1026 Those keys should be associated with the GnuTLS session using
1027 @funcref{gnutls_session_ticket_enable_server}.
1028
1029 @showfuncdesc{gnutls_session_ticket_enable_server}
1030 @showfuncdesc{gnutls_session_ticket_key_generate}
1031 @showfuncdesc{gnutls_session_resumption_requested}
1032
1033 A server enabling both session tickets and a storage for session data
1034 would use session tickets when clients support it and the storage otherwise.
1035
1036 @node Parameter generation
1037 @subsection Parameter generation
1038 @cindex parameter generation
1039 @cindex generating parameters
1040
1041 Several TLS ciphersuites require additional parameters that
1042 need to be generated or provided by the application. The
1043 Diffie-Hellman based ciphersuites (ANON-DH or DHE), require
1044 the group parameters to be provided. Those can either be
1045 be generated on the fly using @funcref{gnutls_dh_params_generate2}
1046 or imported from pregenerated data using @funcref{gnutls_dh_params_import_pkcs3}.
1047 The parameters can be used in a @acronym{TLS} session by calling
1048 @funcref{gnutls_certificate_set_dh_params} or
1049 @funcref{gnutls_anon_set_server_dh_params} for anonymous sessions.
1050
1051 @showfuncD{gnutls_dh_params_generate2,gnutls_dh_params_import_pkcs3,gnutls_certificate_set_dh_params,gnutls_anon_set_server_dh_params}
1052
1053 Due to the time-consuming calculations required for the generation
1054 of Diffie-Hellman parameters we suggest against performing generation
1055 of them within an application. The @code{certtool} tool can be used to 
1056 generate or export known safe values that can be stored in code
1057 or in a configuration file to provide the ability to replace. We also
1058 recommend the usage of @funcref{gnutls_sec_param_to_pk_bits} 
1059 (see @ref{Selecting cryptographic key sizes}) to determine
1060 the bit size of the generated parameters.
1061
1062 Note that the information stored in the generated PKCS #3 structure
1063 changed with GnuTLS 3.0.9. Since that version the @code{privateValueLength}
1064 member of the structure is set, allowing the server utilizing the
1065 parameters to use keys of the size of the security parameter. This
1066 provides better performance in key exchange.
1067
1068 The ciphersuites that involve the RSA-EXPORT key exchange require
1069 additional parameters. Those ciphersuites are rarely used today
1070 because they are by design insecure, thus if you have no requirement
1071 for them, the rest of this section can be skipped. The RSA-EXPORT key exchange
1072 requires 512-bit RSA keys to be generated. It is recommended those
1073 parameters to be refreshed (regenerated) in short intervals. The
1074 following functions can be used for these parameters.
1075
1076 @showfuncD{gnutls_rsa_params_generate2,gnutls_certificate_set_rsa_export_params,gnutls_rsa_params_import_pkcs1,gnutls_rsa_params_export_pkcs1}
1077
1078 To allow renewal of the parameters within an application without
1079 accessing the credentials, which are a shared structure,
1080 an alternative interface is available using a callback function.  
1081
1082 @showfuncdesc{gnutls_certificate_set_params_function}
1083
1084
1085 @node Keying Material Exporters
1086 @subsection Keying material exporters
1087 @cindex keying material exporters
1088 @cindex exporting keying material
1089
1090 The TLS PRF can be used by other protocols to derive keys based on
1091 the TLS master secret.  The API to use is @funcref{gnutls_prf}.  The 
1092 function needs to be provided with the label in the parameter 
1093 @code{label}, and the extra data to mix in the
1094 @code{extra} parameter.  Depending on whether you want to mix in the
1095 client or server random data first, you can set the
1096 @code{server_random_first} parameter.
1097
1098 For example, after establishing a TLS session using
1099 @funcref{gnutls_handshake}, you can invoke the TLS PRF with this call:
1100
1101 @example
1102 #define MYLABEL "EXPORTER-FOO"
1103 #define MYCONTEXT "some context data"
1104 char out[32];
1105 rc = gnutls_prf (session, strlen (MYLABEL), MYLABEL, 0,
1106                  strlen (MYCONTEXT), MYCONTEXT, 32, out);
1107 @end example
1108
1109 If you don't want to mix in the client/server random, there is a 
1110 low-level TLS PRF interface called @funcref{gnutls_prf_raw}.
1111
1112 @node Channel Bindings
1113 @subsection Channel bindings
1114 @cindex channel bindings
1115
1116 In user authentication protocols (e.g., EAP or SASL mechanisms) it is
1117 useful to have a unique string that identifies the secure channel that
1118 is used, to bind together the user authentication with the secure
1119 channel.  This can protect against man-in-the-middle attacks in some
1120 situations.  That unique string is called a ``channel binding''.  For
1121 background and discussion see @xcite{RFC5056}.
1122
1123 In @acronym{GnuTLS} you can extract a channel binding using the
1124 @funcref{gnutls_session_channel_binding} function.  Currently only the
1125 type @code{GNUTLS_CB_TLS_UNIQUE} is supported, which corresponds to
1126 the @code{tls-unique} channel binding for TLS defined in
1127 @xcite{RFC5929}.
1128
1129 The following example describes how to print the channel binding data.
1130 Note that it must be run after a successful TLS handshake.
1131
1132 @example
1133 @{
1134   gnutls_datum_t cb;
1135   int rc;
1136
1137   rc = gnutls_session_channel_binding (session,
1138                                        GNUTLS_CB_TLS_UNIQUE,
1139                                        &cb);
1140   if (rc)
1141     fprintf (stderr, "Channel binding error: %s\n",
1142              gnutls_strerror (rc));
1143   else
1144     @{
1145       size_t i;
1146       printf ("- Channel binding 'tls-unique': ");
1147       for (i = 0; i < cb.size; i++)
1148         printf ("%02x", cb.data[i]);
1149       printf ("\n");
1150     @}
1151 @}
1152 @end example
1153
1154 @node Interoperability
1155 @subsection Interoperability
1156
1157 The @acronym{TLS} protocols support many ciphersuites, extensions and version
1158 numbers. As a result, few implementations are 
1159 not able to properly interoperate once faced with extensions or version protocols
1160 they do not support and understand. The @acronym{TLS} protocol allows for a
1161 graceful downgrade to the commonly supported options, but practice shows 
1162 it is not always implemented correctly. 
1163
1164 Because there is no way to achieve maximum interoperability with broken peers
1165 without sacrificing security, @acronym{GnuTLS} ignores such peers by default. 
1166 This might not be acceptable in cases where maximum compatibility
1167 is required. Thus we allow enabling compatibility with broken peers using
1168 priority strings (see @ref{Priority Strings}). A conservative priority
1169 string that would disable certain @acronym{TLS} protocol
1170 options that are known to cause compatibility problems, is shown below. 
1171 @verbatim
1172 NORMAL:%COMPAT
1173 @end verbatim
1174
1175 For broken peers that do not tolerate TLS version numbers over TLS 1.0
1176 another priority string is:
1177 @verbatim
1178 NORMAL:-VERS-TLS-ALL:+VERS-TLS1.0:+VERS-SSL3.0:%COMPAT
1179 @end verbatim
1180 This priority string will in addition to above, only enable SSL 3.0 and 
1181 TLS 1.0 as protocols. Note however that
1182 there are known attacks against those protocol versions, especially over
1183 the CBC-mode ciphersuites. To mitigate them another priority string
1184 that only allows the stream cipher ARCFOUR is below.
1185 @verbatim
1186 NORMAL:-VERS-TLS-ALL:+VERS-TLS1.0:+VERS-SSL3.0:-CIPHER-ALL:+ARCFOUR-128:%COMPAT
1187 @end verbatim
1188
1189 @node Compatibility with the OpenSSL library
1190 @subsection Compatibility with the OpenSSL library
1191 @cindex OpenSSL
1192
1193 To ease @acronym{GnuTLS}' integration with existing applications, a
1194 compatibility layer with the OpenSSL library is included
1195 in the @code{gnutls-openssl} library. This compatibility layer is not
1196 complete and it is not intended to completely re-implement the OpenSSL
1197 API with @acronym{GnuTLS}.  It only provides limited source-level
1198 compatibility. 
1199
1200 The prototypes for the compatibility functions are in the
1201 @file{gnutls/openssl.h} header file. The limitations 
1202 imposed by the compatibility layer include:
1203
1204 @itemize
1205
1206 @item Error handling is not thread safe.
1207
1208 @end itemize
1209
1210 @node Using the cryptographic library
1211 @section Using the cryptographic library
1212
1213 @acronym{GnuTLS} is not a low-level cryptographic library, i.e., 
1214 it does not provide access to basic cryptographic primitives. However
1215 it abstracts the internal cryptographic back-end (see @ref{Cryptographic Backend}),
1216 providing symmetric crypto, hash and HMAC algorithms, as well access
1217 to the random number generation.
1218
1219 @menu
1220 * Symmetric cryptography::
1221 * Hash and HMAC functions::
1222 * Random number generation::
1223 @end menu
1224
1225 @node Symmetric cryptography
1226 @subsection Symmetric cryptography
1227 @cindex symmetric cryptography
1228
1229 The available functions to access symmetric crypto algorithms operations
1230 are shown below. The supported algorithms are the algorithms required by the TLS protocol.
1231 They are listed in @ref{tab:ciphers}.
1232
1233 @showfuncE{gnutls_cipher_init,gnutls_cipher_encrypt2,gnutls_cipher_decrypt2,gnutls_cipher_set_iv,gnutls_cipher_deinit}
1234
1235 In order to support authenticated encryption with associated data (AEAD) algorithms the following
1236 functions are provided to set the associated data and retrieve the authentication tag.
1237
1238 @showfuncB{gnutls_cipher_add_auth,gnutls_cipher_tag}
1239
1240 @node Hash and HMAC functions
1241 @subsection Hash and HMAC functions
1242 @cindex hash functions
1243 @cindex HMAC functions
1244
1245 The available operations to access hash functions and hash-MAC (HMAC) algorithms
1246 are shown below. HMAC algorithms provided keyed hash functionality. They supported HMAC algorithms are listed in @ref{tab:macs}.
1247
1248 @showfuncF{gnutls_hmac_init,gnutls_hmac,gnutls_hmac_output,gnutls_hmac_deinit,gnutls_hmac_get_len,gnutls_hmac_fast}
1249
1250 The available functions to access hash functions are shown below. The supported hash functions
1251 are the same as the HMAC algorithms.
1252
1253 @showfuncF{gnutls_hash_init,gnutls_hash,gnutls_hash_output,gnutls_hash_deinit,gnutls_hash_get_len,gnutls_hash_fast}
1254
1255 @node Random number generation
1256 @subsection Random number generation
1257 @cindex random numbers
1258
1259 Access to the random number generator is provided using the @funcref{gnutls_rnd}
1260 function. It allows obtaining random data of various levels.
1261
1262 @showenumdesc{gnutls_rnd_level_t,The random number levels.}
1263 @showfuncdesc{gnutls_rnd}
1264
1265 @node Selecting cryptographic key sizes
1266 @section Selecting cryptographic key sizes
1267 @cindex key sizes
1268
1269 Because many algorithms are involved in TLS, it is not easy to set
1270 a consistent security level.  For this reason in @ref{tab:key-sizes} we
1271 present some correspondence between key sizes of symmetric algorithms
1272 and public key algorithms based on @xcite{ECRYPT}. 
1273 Those can be used to generate certificates with
1274 appropriate key sizes as well as select parameters for Diffie-Hellman and SRP
1275 authentication.
1276
1277 @float Table,tab:key-sizes
1278 @multitable @columnfractions .10 .12 .10 .20 .32
1279
1280 @headitem Security bits @tab RSA, DH and SRP parameter size @tab ECC key size @tab Security parameter @tab Description
1281
1282 @item 80
1283 @tab 1248
1284 @tab 160
1285 @tab @code{LOW}
1286 @tab Very short term protection against agencies
1287
1288 @item 96
1289 @tab 1776
1290 @tab 192
1291 @tab @code{LEGACY}
1292 @tab Legacy standard level
1293
1294 @item 112
1295 @tab 2432
1296 @tab 224
1297 @tab @code{NORMAL}
1298 @tab Medium-term protection
1299
1300 @item 128
1301 @tab 3248
1302 @tab 256
1303 @tab @code{HIGH}
1304 @tab Long term protection
1305
1306 @item 256
1307 @tab 15424
1308 @tab 512
1309 @tab @code{ULTRA}
1310 @tab Foreseeable future
1311
1312 @end multitable
1313 @caption{Key sizes and security parameters.}
1314 @end float
1315
1316 The first column  provides a security parameter in a number of bits. This
1317 gives an indication of the number of combinations to be tried by an adversary
1318 to brute force a key. For example to test all possible keys in a 112 bit security parameter
1319 @math{2^{112}} combinations have to be tried. For today's technology this is infeasible.
1320 The next two columns correlate the security
1321 parameter with actual bit sizes of parameters for DH, RSA, SRP and ECC algorithms.
1322 A mapping to @code{gnutls_sec_param_t} value is given for each security parameter, on
1323 the next column, and finally a brief description of the level.
1324
1325 @c @showenumdesc{gnutls_sec_param_t,The @code{gnutls_sec_@-param_t} enumeration.}
1326
1327 Note, however, that the values suggested here are nothing more than an
1328 educated guess that is valid today. There are no guarantees that an
1329 algorithm will remain unbreakable or that these values will remain
1330 constant in time. There could be scientific breakthroughs that cannot
1331 be predicted or total failure of the current public key systems by
1332 quantum computers. On the other hand though the cryptosystems used in
1333 TLS are selected in a conservative way and such catastrophic
1334 breakthroughs or failures are believed to be unlikely.
1335 The NIST publication SP 800-57 @xcite{NISTSP80057} contains a similar
1336 table.
1337
1338 When using @acronym{GnuTLS} and a decision on bit sizes for a public
1339 key algorithm is required, use of the following functions is  
1340 recommended:
1341
1342 @showfuncdesc{gnutls_sec_param_to_pk_bits}
1343
1344 @showfuncdesc{gnutls_pk_bits_to_sec_param}
1345
1346 Those functions will convert a human understandable security parameter
1347 of @code{gnutls_sec_param_t} type, to a number of bits suitable for a public 
1348 key algorithm.
1349
1350