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