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