documented fixes.
[gnutls.git] / doc / cha-intro-tls.texi
blobd3de6b367c08f06db9d463074a5d58a19cdcf235
1 @node Introduction to TLS
2 @chapter Introduction to @acronym{TLS}
4 @acronym{TLS} stands for ``Transport Layer Security'' and is the
5 successor of SSL, the Secure Sockets Layer protocol @xcite{SSL3}
6 designed by Netscape.  @acronym{TLS} is an Internet protocol, defined
7 by @acronym{IETF}@footnote{IETF, or Internet Engineering Task Force,
8 is a large open international community of network designers,
9 operators, vendors, and researchers concerned with the evolution of
10 the Internet architecture and the smooth operation of the Internet.
11 It is open to any interested individual.}, described in @acronym{RFC}
12 4346 and also in @xcite{RESCORLA}.  The protocol provides
13 confidentiality, and authentication layers over any reliable transport
14 layer.  The description, below, refers to @acronym{TLS} 1.0 but also
15 applies to @acronym{TLS} 1.1 @xcite{RFC4346} and @acronym{SSL} 3.0,
16 since the differences of these protocols are minor.  Older protocols
17 such as @acronym{SSL} 2.0 are not discussed nor implemented in
18 @acronym{GnuTLS} since they are not considered secure today.  GnuTLS
19 also supports @acronym{X.509} and @acronym{OpenPGP} @xcite{RFC4880}.
21 @menu
22 * TLS layers::
23 * The transport layer::
24 * The TLS record protocol::
25 * The TLS Alert Protocol::
26 * The TLS Handshake Protocol::
27 * TLS Extensions::
28 * Selecting cryptographic key sizes::
29 * On SSL 2 and older protocols::
30 @end menu
32 @node TLS layers
33 @section TLS Layers
34 @cindex TLS Layers
36 @acronym{TLS} is a layered protocol, and consists of the Record
37 Protocol, the Handshake Protocol and the Alert Protocol. The Record
38 Protocol is to serve all other protocols and is above the transport
39 layer.  The Record protocol offers symmetric encryption, data
40 authenticity, and optionally compression.
42 The Alert protocol offers some signaling to the other protocols. It
43 can help informing the peer for the cause of failures and other error
44 conditions.  @xref{The Alert Protocol}, for more information.  The
45 alert protocol is above the record protocol.
47 The Handshake protocol is responsible for the security parameters'
48 negotiation, the initial key exchange and authentication.  @xref{The
49 Handshake Protocol}, for more information about the handshake
50 protocol.  The protocol layering in TLS is shown in the figure below.
52 @image{gnutls-layers,12cm,8cm}
54 @node The transport layer
55 @section The Transport Layer
56 @cindex Transport protocol
58 @acronym{TLS} is not limited to one transport layer, it can be used
59 above any transport layer, as long as it is a reliable one.  A set of
60 functions is provided and their purpose is to load to @acronym{GnuTLS} the
61 required callbacks to access the transport layer.
63 @itemize
64 @item @ref{gnutls_transport_set_push_function}
65 @item @ref{gnutls_transport_set_vec_push_function}
66 @item @ref{gnutls_transport_set_pull_function}
67 @item @ref{gnutls_transport_set_ptr}
68 @item @ref{gnutls_transport_set_lowat}
69 @item @ref{gnutls_transport_set_errno}
70 @end itemize
72 These functions accept a callback function as a parameter.  The
73 callback functions should return the number of bytes written, or -1 on
74 error and should set @code{errno} appropriately.
76 In some environments, setting @code{errno} is unreliable, for example
77 Windows have several errno variables in different CRTs, or it may be
78 that errno is not a thread-local variable.  If this is a concern to
79 you, call @code{gnutls_transport_set_errno} with the intended errno
80 value instead of setting @code{errno} directly.
82 @acronym{GnuTLS} currently only interprets the EINTR and EAGAIN errno
83 values and returns the corresponding @acronym{GnuTLS} error codes
84 @code{GNUTLS_E_INTERRUPTED} and @code{GNUTLS_E_AGAIN}.  These values
85 are usually returned by interrupted system calls, or when non blocking
86 IO is used.  All @acronym{GnuTLS} functions can be resumed (called
87 again), if any of these error codes is returned.  The error codes
88 above refer to the system call, not the @acronym{GnuTLS} function,
89 since signals do not interrupt @acronym{GnuTLS}' functions.
91 For non blocking sockets or other custom made pull/push functions
92 the @ref{gnutls_transport_set_lowat} must be called, with a zero
93 low water mark value.
95 By default, if the transport functions are not set, @acronym{GnuTLS}
96 will use the Berkeley Sockets functions. 
98 @node The TLS record protocol
99 @section The TLS Record Protocol
100 @cindex Record protocol
102 The Record protocol is the secure communications provider. Its purpose
103 is to encrypt, authenticate and ---optionally--- compress packets.
104 The following functions are available:
106 @table @asis
108 @item @ref{gnutls_record_send}:
109 To send a record packet (with application data).
111 @item @ref{gnutls_record_recv}:
112 To receive a record packet (with application data).
114 @item @ref{gnutls_record_get_direction}:
115 To get the direction of the last interrupted function call.
116 @end table
118 As you may have already noticed, the functions which access the Record
119 protocol, are quite limited, given the importance of this protocol in
120 @acronym{TLS}.  This is because the Record protocol's parameters are
121 all set by the Handshake protocol.
123 The Record protocol initially starts with NULL parameters, which means
124 no encryption, and no MAC is used. Encryption and authentication begin
125 just after the handshake protocol has finished.
127 @menu
128 * Encryption algorithms used in the record layer::
129 * Compression algorithms used in the record layer::
130 * Weaknesses and countermeasures::
131 * On Record Padding::
132 @end menu
134 @node Encryption algorithms used in the record layer
135 @subsection Encryption Algorithms Used in the Record Layer
136 @cindex Symmetric encryption algorithms
138 Confidentiality in the record layer is achieved by using symmetric
139 block encryption algorithms like @code{3DES}, @code{AES}@footnote{AES,
140 or Advanced Encryption Standard, is actually the RIJNDAEL algorithm.
141 This is the algorithm that replaced DES.}, or stream algorithms like
142 @code{ARCFOUR_128}@footnote{@code{ARCFOUR_128} is a compatible
143 algorithm with RSA's RC4 algorithm, which is considered to be a trade
144 secret.}. Ciphers are encryption algorithms that use a single, secret,
145 key to encrypt and decrypt data. Block algorithms in TLS also provide
146 protection against statistical analysis of the data.  Thus, if you're
147 using the @acronym{TLS} protocol, a random number of blocks will be
148 appended to data, to prevent eavesdroppers from guessing the actual
149 data size.
151 Supported cipher algorithms:
153 @table @code
154 @item 3DES_CBC
155 @code{3DES_CBC} is the DES block cipher algorithm used with triple
156 encryption (EDE). Has 64 bits block size and is used in CBC mode.
158 @item ARCFOUR_128
159 ARCFOUR is a fast stream cipher.
161 @item ARCFOUR_40
162 This is the ARCFOUR cipher that is fed with a 40 bit key,
163 which is considered weak.
165 @item AES_CBC
166 AES or RIJNDAEL is the block cipher algorithm that replaces the old
167 DES algorithm.  Has 128 bits block size and is used in CBC mode.
168 @end table
170 Supported MAC algorithms:
172 @table @code
173 @item MAC_MD5
174 MD5 is a cryptographic hash algorithm designed by Ron Rivest. Outputs
175 128 bits of data.
177 @item MAC_SHA
178 SHA is a cryptographic hash algorithm designed by NSA. Outputs 160
179 bits of data.
181 @end table
183 @node Compression algorithms used in the record layer
184 @subsection Compression Algorithms Used in the Record Layer
185 @cindex Compression algorithms
187 The TLS record layer also supports compression.  The algorithms
188 implemented in @acronym{GnuTLS} can be found in the table below.
189 All the algorithms except for DEFLATE which is
190 referenced in @xcite{RFC3749}, should be considered as
191 @acronym{GnuTLS}' extensions@footnote{You should use
192 @ref{gnutls_handshake_set_private_extensions} to enable private
193 extensions.}, and should be advertised only when the peer is known to
194 have a compliant client, to avoid interoperability problems.
196 The included algorithms perform really good when text, or other
197 compressible data are to be transfered, but offer nothing on already
198 compressed data, such as compressed images, zipped archives etc.
199 These compression algorithms, may be useful in high bandwidth TLS
200 tunnels, and in cases where network usage has to be minimized. As a
201 drawback, compression increases latency.
203 The record layer compression in @acronym{GnuTLS} is implemented based
204 on the proposal @xcite{RFC3749}.
205 The supported compression algorithms are:
207 @table @code
208 @item DEFLATE
209 Zlib compression, using the deflate algorithm.
211 @item LZO
212 LZO is a very fast compression algorithm.  This algorithm is only
213 available if the @acronym{GnuTLS-extra} library has been initialized
214 and the private extensions are enabled, and if GnuTLS was built with
215 LZO support.
217 @end table
219 @node Weaknesses and countermeasures
220 @subsection Weaknesses and Countermeasures
222 Some weaknesses that may affect the security of the Record layer have
223 been found in @acronym{TLS} 1.0 protocol. These weaknesses can be
224 exploited by active attackers, and exploit the facts that
226 @enumerate
228 @item
229 @acronym{TLS} has separate alerts for ``decryption_failed'' and
230 ``bad_record_mac''
232 @item
233 The decryption failure reason can be detected by timing the response
234 time.
236 @item
237 The IV for CBC encrypted packets is the last block of the previous
238 encrypted packet.
240 @end enumerate
242 Those weaknesses were solved in @acronym{TLS} 1.1 @xcite{RFC4346}
243 which is implemented in @acronym{GnuTLS}. For a detailed discussion
244 see the archives of the TLS Working Group mailing list and the paper
245 @xcite{CBCATT}.
247 @node On Record Padding
248 @subsection On Record Padding
249 @cindex Record padding
250 @cindex Bad record MAC
252 The TLS protocol allows for random padding of records, to make it more
253 difficult to perform analysis on the length of exchanged messages (RFC 5246 6.2.3.2).  
254 GnuTLS appears to be one of few implementation that take advantage of this text, 
255 and pad records by a random length.
257 The TLS implementation in the Symbian operating system, frequently
258 used by Nokia and Sony-Ericsson mobile phones, cannot handle
259 non-minimal record padding.  What happens when one of these clients
260 handshake with a GnuTLS server is that the client will fail to compute
261 the correct MAC for the record.  The client sends a TLS alert
262 (@code{bad_record_mac}) and disconnects.  Typically this will result
263 in error messages such as 'A TLS fatal alert has been received', 'Bad
264 record MAC', or both, on the GnuTLS server side.
266 GnuTLS implements a work around for this problem.  However, it has to
267 be enabled specifically.  It can be enabled by using
268 @ref{gnutls_record_disable_padding}, or @ref{gnutls_priority_set} with
269 the @code{%COMPAT} priority string.
271 If you implement an application that have a configuration file, we
272 recommend that you make it possible for users or administrators to
273 specify a GnuTLS protocol priority string, which is used by your
274 application via @ref{gnutls_priority_set}.  To allow the best
275 flexibility, make it possible to have a different priority string for
276 different incoming IP addresses.
278 To enable the workaround in the @code{gnutls-cli} client or the
279 @code{gnutls-serv} server, for testing of other implementations, use
280 the following parameter: @code{--priority "NORMAL:%COMPAT"}.
283 @node The TLS Alert Protocol
284 @section The TLS Alert Protocol
285 @anchor{The Alert Protocol}
286 @cindex Alert protocol
288 The Alert protocol is there to allow signals to be sent between peers.
289 These signals are mostly used to inform the peer about the cause of a
290 protocol failure. Some of these signals are used internally by the
291 protocol and the application protocol does not have to cope with them
292 (see @code{GNUTLS_A_CLOSE_NOTIFY}), and others refer to the
293 application protocol solely (see @code{GNUTLS_A_USER_CANCELLED}).  An
294 alert signal includes a level indication which may be either fatal or
295 warning. Fatal alerts always terminate the current connection, and
296 prevent future renegotiations using the current session ID.
298 The alert messages are protected by the record protocol, thus the
299 information that is included does not leak. You must take extreme care
300 for the alert information not to leak to a possible attacker, via
301 public log files etc.
303 @table @asis
304 @item @ref{gnutls_alert_send}:
305 To send an alert signal.
307 @item @ref{gnutls_error_to_alert}:
308 To map a gnutls error number to an alert signal.
310 @item @ref{gnutls_alert_get}:
311 Returns the last received alert.
313 @item @ref{gnutls_alert_get_name}:
314 Returns the name, in a character array, of the given alert.
316 @end table
318 @node The TLS Handshake Protocol
319 @section The TLS Handshake Protocol
320 @anchor{The Handshake Protocol}
321 @cindex Handshake protocol
323 The Handshake protocol is responsible for the ciphersuite negotiation,
324 the initial key exchange, and the authentication of the two peers.
325 This is fully controlled by the application layer, thus your program
326 has to set up the required parameters. Available functions to control
327 the handshake protocol include:
329 @table @asis
330 @item @ref{gnutls_priority_init}:
331 To initialize a priority set of ciphers.
333 @item @ref{gnutls_priority_deinit}:
334 To deinitialize a priority set of ciphers.
336 @item @ref{gnutls_priority_set}:
337 To associate a priority set with a @acronym{TLS} session.
339 @item @ref{gnutls_priority_set_direct}:
340 To directly associate a session with a given priority string.
342 @item @ref{gnutls_credentials_set}:
343 To set the appropriate credentials structures.
345 @item @ref{gnutls_certificate_server_set_request}:
346 To set whether client certificate is required or not.
348 @item @ref{gnutls_handshake}:
349 To initiate the handshake.
350 @end table
352 @menu
353 * TLS Cipher Suites::           TLS session parameters.
354 * Priority Strings::            Defining how parameters are negotiated.
355 * Client Authentication::       Requesting a certificate from the client.
356 * Resuming Sessions::           Reusing previously established keys.
357 * Resuming Internals::          More information on reusing previously established keys.
358 * Interoperability::            About interoperability with other implementations.
359 @end menu
361 @node TLS Cipher Suites
362 @subsection TLS Cipher Suites
364 The Handshake Protocol of @acronym{TLS} negotiates cipher suites of
365 the form @code{TLS_DHE_RSA_WITH_3DES_CBC_SHA}.  The usual cipher
366 suites contain these parameters:
368 @itemize
370 @item The key exchange algorithm.
371 @code{DHE_RSA} in the example.
373 @item The Symmetric encryption algorithm and mode
374 @code{3DES_CBC} in this example.
376 @item The MAC@footnote{MAC stands for Message Authentication Code. It can be described as a keyed hash algorithm. See RFC2104.} algorithm used for authentication.
377 @code{MAC_SHA} is used in the above example.
379 @end itemize
381 The cipher suite negotiated in the handshake protocol will affect the
382 Record Protocol, by enabling encryption and data authentication.  Note
383 that you should not over rely on @acronym{TLS} to negotiate the
384 strongest available cipher suite. Do not enable ciphers and algorithms
385 that you consider weak.
387 All the supported ciphersuites are shown in @ref{ciphersuites}.
389 @node Priority Strings
390 @subsection Priority Strings
392 In order to specify cipher suite preferences, the
393 previously shown priority functions accept a string
394 that specifies the algorithms to be enabled in a TLS handshake.
395 That string may contain some high level keyword such as:
397 @table @asis
398 @item PERFORMANCE:
399 All the "secure" ciphersuites are enabled,
400 limited to 128 bit ciphers and sorted by terms of speed
401 performance.
403 @item NORMAL:
404 Means all "secure" ciphersuites. The 256-bit ciphers are
405 included as a fallback only.  The ciphers are sorted by security
406 margin.
408 @item SECURE128: 
409 Means all "secure" ciphersuites with ciphers up to 128
410 bits, sorted by security margin.
412 @item SECURE256:
413 Means all "secure" ciphersuites including the 256 bit
414 ciphers, sorted by security margin.
416 @item EXPORT:
417 Means all ciphersuites are enabled, including the
418 low-security 40 bit ciphers.
420 @item NONE:
421 Means nothing is enabled.  This disables even protocols and
422 compression methods. It should be followed by the
423 algorithms to be enabled.
425 @end table
427 or it might contain special keywords, that will be explained
428 later on.
430 Unless the first keyword is "NONE" the defaults (in preference
431 order) are for TLS protocols TLS 1.2, TLS1.1, TLS1.0, SSL3.0; for
432 compression NULL; for certificate types X.509, OpenPGP.
433 For key exchange algorithms when in NORMAL or SECURE levels the
434 perfect forward secrecy algorithms take precedence of the other
435 protocols.  In all cases all the supported key exchange algorithms
436  are enabled (except for the RSA-EXPORT which is only enabled in
437 EXPORT level).
439 The NONE keyword is followed by the algorithms to be enabled,
440 and is used to provide the exact list of requested algorithms@footnote{
441 To avoid collisions in order to specify a compression algorithm in
442 this string you have to prefix it with "COMP-", protocol versions
443 with "VERS-", signature algorithms with "SIGN-" and certificate types with "CTYPE-". All other
444 algorithms don't need a prefix.}. The order with which every algorithm
445 is specified is significant. Similar algorithms specified before others
446 will take precedence.
448 Keywords prepended to individual algorithms:
449 @table @asis
451 @item '!' or '-' 
452 appended with an algorithm will remove this algorithm.
454 @item "+" 
455 appended with an algorithm will add this algorithm.
457 @end table
459 Individual algorithms:
460 @table @asis
461 @item Ciphers: 
462 AES-128-CBC, AES-256-CBC, CAMELLIA-128-CBC,
463 CAMELLIA-256-CBC, ARCFOUR-128, 3DES-CBC ARCFOUR-40. Catch all
464 name is CIPHER-ALL which will add all the algorithms from NORMAL
465 priority.
467 @item Key exchange: 
468 RSA, DHE-RSA, DHE-DSS, SRP, SRP-RSA, SRP-DSS,
469 PSK, DHE-PSK, ANON-DH, RSA-EXPORT. The
470 key exchange methods do not have a catch all.
472 @item MAC: 
473 MD5, SHA1, SHA256. All algorithms from NORMAL priority can be accessed with MAC-ALL.
475 @item Compression algorithms: 
476 COMP-NULL, COMP-DEFLATE. Catch all is COMP-ALL.
478 @item TLS versions: 
479 VERS-SSL3.0, VERS-TLS1.0, VERS-TLS1.1,
480 VERS-TLS1.2. Catch all is VERS-TLS-ALL.
482 @item Signature algorithms: 
483 SIGN-RSA-SHA1, SIGN-RSA-SHA224, 
484 SIGN-RSA-SHA256, SIGN-RSA-SHA384, SIGN-RSA-SHA512, SIGN-DSA-SHA1, 
485 SIGN-DSA-SHA224, SIGN-DSA-SHA256, SIGN-RSA-MD5. Catch all
486 is SIGN-ALL. This is only valid for TLS 1.2 and later.
488 @end table
491 Special keywords:
492 @table @asis
494 @item %COMPAT:
495 will enable compatibility mode. It might mean that violations
496 of the protocols are allowed as long as maximum compatibility with
497 problematic clients and servers is achieved.
499 @item %DISABLE_SAFE_RENEGOTIATION:
500 will disable safe renegotiation
501 completely.  Do not use unless you know what you are doing.
502 Testing purposes only.
504 @item %UNSAFE_RENEGOTIATION:
505 will allow handshakes and rehandshakes
506 without the safe renegotiation extension.  Note that for clients
507 this mode is insecure (you may be under attack), and for servers it
508 will allow insecure clients to connect (which could be fooled by an
509 attacker).  Do not use unless you know what you are doing and want
510 maximum compatibility.
512 @item %PARTIAL_RENEGOTIATION:
513 will allow initial handshakes to proceed,
514 but not rehandshakes.  This leaves the client vulnerable to attack,
515 and servers will be compatible with non-upgraded clients for
516 initial handshakes.  This is currently the default for clients and
517 servers, for compatibility reasons.
519 @item %SAFE_RENEGOTIATION:
520 will enforce safe renegotiation.  Clients and
521 servers will refuse to talk to an insecure peer.  Currently this
522 causes operability problems, but is required for full protection.
524 @item %SSL3_RECORD_VERSION:
525 will use SSL3.0 record version in client hello.
526 This is the default.
528 @item %LATEST_RECORD_VERSION:
529 will use the latest TLS version record version in client hello.
531 @item %VERIFY_ALLOW_SIGN_RSA_MD5:
532 will allow RSA-MD5 signatures in certificate chains.
534 @item %VERIFY_ALLOW_X509_V1_CA_CRT:
535 will allow V1 CAs in chains.
537 @end table
539 @node Client Authentication
540 @subsection Client Authentication
541 @cindex Client Certificate authentication
543 In the case of ciphersuites that use certificate authentication, the
544 authentication of the client is optional in @acronym{TLS}.  A server
545 may request a certificate from the client --- using the
546 @ref{gnutls_certificate_server_set_request} function. If a certificate
547 is to be requested from the client during the handshake, the server
548 will send a certificate request message that contains a list of
549 acceptable certificate signers. In @acronym{GnuTLS} the certificate
550 signers list is constructed using the trusted Certificate Authorities
551 by the server. That is the ones set using
552 @itemize
553 @item @ref{gnutls_certificate_set_x509_trust_file}
554 @item @ref{gnutls_certificate_set_x509_trust_mem}
555 @end itemize
557 Sending of the names of the CAs can be controlled using
558 @ref{gnutls_certificate_send_x509_rdn_sequence}. The client, then, may
559 send a certificate, signed by one of the server's acceptable signers.
561 @node Resuming Sessions
562 @subsection Resuming Sessions
563 @anchor{resume}
564 @cindex Resuming sessions
566 The @ref{gnutls_handshake} function, is expensive since a lot of
567 calculations are performed. In order to support many fast connections
568 to the same server a client may use session resuming. @strong{Session
569 resuming} is a feature of the @acronym{TLS} protocol which allows a
570 client to connect to a server, after a successful handshake, without
571 the expensive calculations.  This is achieved by using the previously
572 established keys. @acronym{GnuTLS} supports this feature, and the
573 example (@pxref{ex:resume-client}) illustrates a typical use of it.
575 Keep in mind that sessions are expired after some time, for security
576 reasons, thus it may be normal for a server not to resume a session
577 even if you requested that.  Also note that you must enable, using the
578 priority functions, at least the algorithms used in the last session.
580 @node Resuming Internals
581 @subsection Resuming Internals
583 The resuming capability, mostly in the server side, is one of the
584 problems of a thread-safe TLS implementations. The problem is that all
585 threads must share information in order to be able to resume
586 sessions. The gnutls approach is, in case of a client, to leave all
587 the burden of resuming to the client. I.e., copy and keep the
588 necessary parameters. See the functions:
590 @itemize
592 @item @ref{gnutls_session_get_data}
594 @item @ref{gnutls_session_get_id}
596 @item @ref{gnutls_session_set_data}
598 @end itemize
600 The server side is different. A server has to specify some callback
601 functions which store, retrieve and delete session data. These can be
602 registered with:
604 @itemize
606 @item @ref{gnutls_db_set_remove_function}
608 @item @ref{gnutls_db_set_store_function}
610 @item @ref{gnutls_db_set_retrieve_function}
612 @item @ref{gnutls_db_set_ptr}
614 @end itemize
616 It might also be useful to be able to check for expired sessions in
617 order to remove them, and save space. The function
618 @ref{gnutls_db_check_entry} is provided for that reason.
620 @node Interoperability
621 @subsection Interoperability
623 The @acronym{TLS} handshake is a complex procedure that negotiates all
624 required parameters for a secure session. @acronym{GnuTLS} supports
625 several @acronym{TLS} extensions, as well as the latest @acronym{TLS} protocol 
626 version 1.2. However few implementations are not able to
627 properly interoperate once faced with extensions or version protocols
628 they do not support and understand. The @acronym{TLS} protocol allows for a
629 graceful downgrade to the commonly supported options, but practice shows 
630 it is not always implemented correctly. 
632 Because there is no way to achieve maximum interoperability with broken peers
633 without sacrificing security, @acronym{GnuTLS} ignores such peers by default. 
634 This might not be acceptable in cases where maximum compatibility
635 is required. Thus we allow enabling compatibility with broken peers using
636 priority strings (see @ref{Priority Strings}). An example priority string that
637 is known to provide wide compatibility even with broken peers
638 is shown below:
639 @example
640 NORMAL:-VERS-TLS-ALL:+VERS-TLS1.0:+VERS-SSL3.0:%COMPAT
641 @end example
642 This priority string will only enable SSL 3.0 and TLS 1.0 as protocols and
643 will disable, via the @code{%COMPAT} keyword, several @acronym{TLS} protocol
644 options that are known to cause compatibility problems.
645 We suggest however only to use this mode if compatibility issues occur.
647 @node TLS Extensions
648 @section TLS Extensions
649 @cindex TLS Extensions
651 A number of extensions to the @acronym{TLS} protocol have been
652 proposed mainly in @xcite{TLSEXT}. The extensions supported
653 in @acronym{GnuTLS} are:
655 @itemize
656 @item Maximum fragment length negotiation
657 @item Server name indication
658 @item Session tickets
659 @item Safe Renegotiation
660 @end itemize
662 and they will be discussed in the subsections that follow.
664 @subsection Maximum Fragment Length Negotiation
665 @cindex TLS Extensions
666 @cindex Maximum fragment length
668 This extension allows a @acronym{TLS} implementation to negotiate a
669 smaller value for record packet maximum length. This extension may be
670 useful to clients with constrained capabilities. See the
671 @ref{gnutls_record_set_max_size} and the
672 @ref{gnutls_record_get_max_size} functions.
674 @subsection Server Name Indication
675 @anchor{serverind}
676 @cindex TLS Extensions
677 @cindex Server name indication
679 A common problem in @acronym{HTTPS} servers is the fact that the
680 @acronym{TLS} protocol is not aware of the hostname that a client
681 connects to, when the handshake procedure begins. For that reason the
682 @acronym{TLS} server has no way to know which certificate to send.
684 This extension solves that problem within the @acronym{TLS} protocol,
685 and allows a client to send the HTTP hostname before the handshake
686 begins within the first handshake packet.  The functions
687 @ref{gnutls_server_name_set} and @ref{gnutls_server_name_get} can be
688 used to enable this extension, or to retrieve the name sent by a
689 client.
691 @subsection Session Tickets
692 @cindex TLS Extensions
693 @cindex Session Tickets
694 @cindex Ticket
696 To resume a TLS session the server normally store some state.  This
697 complicates deployment, and typical situations the client can cache
698 information and send it to the server instead.  The Session Ticket
699 extension implements this idea, and it is documented in
700 RFC 5077 @xcite{TLSTKT}.
702 Clients can enable support for TLS tickets with
703 @ref{gnutls_session_ticket_enable_client} and servers use
704 @ref{gnutls_session_ticket_key_generate} to generate a key and
705 @ref{gnutls_session_ticket_enable_server} to enable the extension.
706 Clients resume sessions using the ticket using the normal session
707 resume functions, @ref{resume}.
709 @subsection Safe Renegotiation
710 @cindex renegotiation
712 TLS gives the option to two communicating parties to renegotiate
713 and update their security parameters. One useful example of this feature
714 was for a client to initially connect using anonymous negotiation to a
715 server, and the renegotiate using some authenticated ciphersuite. This occured
716 to avoid having the client sending its credentials in the clear.
718 However this renegotiation, as initially designed would not ensure that
719 the party one is renegotiating is the same as the one in the initial negotiation.
720 For example one server could forward all renegotiation traffic to an other
721 server who will see this traffic as an initial negotiation attempt.
723 This might be seen as a valid design decision, but it seems it was
724 not widely known or understood, thus today some application protocols the TLS
725 renegotiation feature in a manner that enables a malicious server to insert
726 content of his choice in the beginning of a TLS session.
728 The most prominent vulnerability was with HTTPS. There servers request
729 a renegotiation to enforce an anonymous user to use a certificate in order
730 to access certain parts of a web site.  The
731 attack works by having the attacker simulate a client and connect to a
732 server, with server-only authentication, and send some data intended
733 to cause harm.  The server will then require renegotiation from him
734 in order to perform the request. 
735 When the proper client attempts to contact the server,
736 the attacker hijacks that connection and forwards traffic to
737 the initial server that requested renegotiation.  The
738 attacker will not be able to read the data exchanged between the
739 client and the server.  However, the server will (incorrectly) assume
740 that the initial request sent by the attacker was sent by the now authenticated
741 client.  The result is a prefix plain-text injection attack.
743 The above is just one example.  Other vulnerabilities exists that do
744 not rely on the TLS renegotiation to change the client's authenticated
745 status (either TLS or application layer).
747 While fixing these application protocols and implementations would be
748 one natural reaction, an extension to TLS has been designed that
749 cryptographically binds together any renegotiated handshakes with the
750 initial negotiation.  When the extension is used, the attack is
751 detected and the session can be terminated.  The extension is
752 specified in @xcite{RFC5746}.
754 GnuTLS supports the safe renegotiation extension.  The default
755 behavior is as follows.  Clients will attempt to negotiate the safe
756 renegotiation extension when talking to servers.  Servers will accept
757 the extension when presented by clients.  Clients and servers will
758 permit an initial handshake to complete even when the other side does
759 not support the safe renegotiation extension.  Clients and servers
760 will refuse renegotiation attempts when the extension has not been
761 negotiated.
763 Note that permitting clients to connect to servers when the safe
764 renegotiation extension is not enabled, is open up for attacks.
765 Changing this default behaviour would prevent interoperability against
766 the majority of deployed servers out there.  We will reconsider this
767 default behaviour in the future when more servers have been upgraded.
768 Note that it is easy to configure clients to always require the safe
769 renegotiation extension from servers (see below on the
770 @code{%SAFE_RENEGOTIATION} priority string).
772 To modify the default behaviour, we have introduced some new priority
773 strings.  The priority strings can be used by applications
774 (@pxref{gnutls_priority_set}) and end users (e.g., @code{--priority}
775 parameter to @code{gnutls-cli} and @code{gnutls-serv}).
777 The @code{%UNSAFE_RENEGOTIATION} priority string permits
778 (re-)handshakes even when the safe renegotiation extension was not
779 negotiated. The default behavior is @code{%PARTIAL_RENEGOTIATION} that will
780 prevent renegotiation with clients and servers not supporting the
781 extension. This is secure for servers but leaves clients vulnerable
782 to some attacks, but this is a tradeoff between security and compatibility
783 with old servers. The @code{%SAFE_RENEGOTIATION} priority string makes
784 clients and servers require the extension for every handshake. The latter
785 is the most secure option for clients, at the cost of not being able
786 to connect to legacy servers. Servers will also deny clients that
787 do not support the extension from connecting.
789 It is possible to disable use of the extension completely, in both
790 clients and servers, by using the @code{%DISABLE_SAFE_RENEGOTIATION}
791 priority string however we strongly recommend you to only do this for
792 debugging and test purposes.
794 The default values if the flags above are not specified are:
795 @table @code
797 @item Server:
798 %PARTIAL_RENEGOTIATION
800 @item Client:
801 %PARTIAL_RENEGOTIATION
803 @end table
805 For applications we have introduced a new API related to safe
806 renegotiation.  The @ref{gnutls_safe_renegotiation_status} function is
807 used to check if the extension has been negotiated on a session, and
808 can be used both by clients and servers.
810 @node Selecting cryptographic key sizes
811 @section Selecting Cryptographic Key Sizes
812 @cindex key sizes
814 In TLS, since a lot of algorithms are involved, it is not easy to set
815 a consistent security level.  For this reason this section will
816 present some correspondance between key sizes of symmetric algorithms
817 and public key algorithms based on the ``ECRYPT II Yearly Report on Algorithms and Keysizes (2009-2010)''
818 in @xcite{ECRYPT}.  Those can be used to generate certificates with
819 appropriate key sizes as well as parameters for Diffie-Hellman and SRP
820 authentication.
822 @multitable @columnfractions .10 .15 .10 .20 .35
824 @item Security bits
825 @tab RSA, DH and SRP parameter size
826 @tab ECC key size
827 @tab @code{gnutls_sec_param_t}
828 @tab Description
830 @item 64
831 @tab 816
832 @tab 128
833 @tab @code{WEAK}
834 @tab Very short term protection against small organizations
836 @item 80
837 @tab 1248
838 @tab 160
839 @tab @code{LOW}
840 @tab Very short term protection against agencies
842 @item 112
843 @tab 2432
844 @tab 224
845 @tab @code{NORMAL}
846 @tab Medium-term protection
848 @item 128
849 @tab 3248
850 @tab 256
851 @tab @code{HIGH}
852 @tab Long term protection
854 @item 256
855 @tab 15424
856 @tab 512
857 @tab @code{ULTRA}
858 @tab Foreseeable future
860 @end multitable
862 The first column provides a security parameter in a number of bits. This
863 gives an indication of the number of combinations to be tried by an adversary
864 to brute force a key. For example to test all possible keys in a 112 bit security parameter
865 @math{2^{112}} combinations have to be tried. For today's technology this is infeasible.
866 The next two columns correlate the security
867 parameter with actual bit sizes of parameters for DH, RSA, SRP and ECC algorithms.
868 A mapping to @code{gnutls_sec_param_t} value is given for each security parameter, on
869 the next column, and finally a brief description of the level.
871 Note however that the values suggested here are nothing more than an
872 educated guess that is valid today. There are no guarrantees that an
873 algorithm will remain unbreakable or that these values will remain
874 constant in time. There could be scientific breakthroughs that cannot
875 be predicted or total failure of the current public key systems by
876 quantum computers. On the other hand though the cryptosystems used in
877 TLS are selected in a conservative way and such catastrophic
878 breakthroughs or failures are believed to be unlikely.
880 NIST publication SP 800-57 @xcite{NISTSP80057} contains a similar
881 table.
883 When using @acronym{GnuTLS} and a decision on bit sizes for a public
884 key algorithm is required, use of the following functions is  
885 recommended:
886 @itemize
888 @item @ref{gnutls_pk_bits_to_sec_param}
890 @item @ref{gnutls_sec_param_to_pk_bits}
892 @end itemize
893 Those functions will convert a human understandable security parameter
894 of @code{gnutls_sec_param_t} type, to a number of bits suitable for a public 
895 key algorithm.
897 @node On SSL 2 and older protocols
898 @section On SSL 2 and Older Protocols
899 @cindex SSL 2
901 One of the initial decisions in the @acronym{GnuTLS} development was
902 to implement the known security protocols for the transport layer.
903 Initially @acronym{TLS} 1.0 was implemented since it was the latest at
904 that time, and was considered to be the most advanced in security
905 properties.  Later the @acronym{SSL} 3.0 protocol was implemented
906 since it is still the only protocol supported by several servers and
907 there are no serious security vulnerabilities known.
909 One question that may arise is why we didn't implement @acronym{SSL}
910 2.0 in the library.  There are several reasons, most important being
911 that it has serious security flaws, unacceptable for a modern security
912 library.  Other than that, this protocol is barely used by anyone
913 these days since it has been deprecated since 1996.  The security
914 problems in @acronym{SSL} 2.0 include:
916 @itemize
918 @item Message integrity compromised.
919 The @acronym{SSLv2} message authentication uses the MD5 function, and
920 is insecure.
922 @item Man-in-the-middle attack.
923 There is no protection of the handshake in @acronym{SSLv2}, which
924 permits a man-in-the-middle attack.
926 @item Truncation attack.
927 @acronym{SSLv2} relies on TCP FIN to close the session, so the
928 attacker can forge a TCP FIN, and the peer cannot tell if it was a
929 legitimate end of data or not.
931 @item Weak message integrity for export ciphers.
932 The cryptographic keys in @acronym{SSLv2} are used for both message
933 authentication and encryption, so if weak encryption schemes are
934 negotiated (say 40-bit keys) the message authentication code use the
935 same weak key, which isn't necessary.
937 @end itemize
939 @cindex PCT
940 Other protocols such as Microsoft's @acronym{PCT} 1 and @acronym{PCT}
941 2 were not implemented because they were also abandoned and deprecated
942 by @acronym{SSL} 3.0 and later @acronym{TLS} 1.0.