1 @node Introduction to TLS
2 @chapter Introduction to @acronym{TLS} and @acronym{DTLS}
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 @xcite{RFC5246}.
13 confidentiality, and authentication layers over any reliable transport
14 layer. The description, above, refers to @acronym{TLS} 1.0 but applies
15 to all other TLS versions as the differences between the protocols are not major.
17 The @acronym{DTLS} protocol, or ``Datagram @acronym{TLS}'' @xcite{RFC4347} is a
18 protocol with identical goals as @acronym{TLS}, but can operate
19 under unreliable transport layers such as @acronym{UDP}. The
20 discussions below apply to this protocol as well, except when
25 * The transport layer::
26 * The TLS record protocol::
27 * The TLS Alert Protocol::
28 * The TLS Handshake Protocol::
30 * How to use TLS in application protocols::
31 * On SSL 2 and older protocols::
38 @acronym{TLS} is a layered protocol, and consists of the record
39 protocol, the handshake protocol and the alert protocol. The record
40 protocol is to serve all other protocols and is above the transport
41 layer. The record protocol offers symmetric encryption, data
42 authenticity, and optionally compression.
43 The alert protocol offers some signaling to the other protocols. It
44 can help informing the peer for the cause of failures and other error
45 conditions. @xref{The Alert Protocol}, for more information. The
46 alert protocol is above the record protocol.
48 The handshake protocol is responsible for the security parameters'
49 negotiation, the initial key exchange and authentication.
50 @xref{The Handshake Protocol}, for more information about the handshake
51 protocol. The protocol layering in TLS is shown in @ref{fig:tls-layers}.
53 @float Figure,fig:tls-layers
54 @image{gnutls-layers,12cm}
55 @caption{The TLS protocol layers.}
58 @node The transport layer
59 @section The transport layer
60 @cindex transport protocol
61 @cindex transport layer
63 @acronym{TLS} is not limited to any transport layer and can be used
64 above any transport layer, as long as it is a reliable one. @acronym{DTLS}
65 can be used over reliable and unreliable transport layers.
66 @acronym{GnuTLS} supports TCP and UDP layers transparently using
67 the Berkeley sockets API. However, any transport layer can be used
68 by providing callbacks for @acronym{GnuTLS} to access the transport layer
69 (for details see @ref{Setting up the transport layer}).
71 @node The TLS record protocol
72 @section The TLS record protocol
73 @cindex record protocol
75 The record protocol is the secure communications provider. Its purpose
76 is to encrypt, authenticate and ---optionally--- compress packets.
77 The record layer functions can be called at any time after
78 the handshake process is finished, when there is need to receive
79 or send data. In @acronym{DTLS} however, due to re-transmission
80 timers used in the handshake out-of-order handshake data might
81 be received for some time (maximum 60 seconds) after the handshake
84 The functions to access the record protocol are limited to send
85 and receive functions, which might, given
86 the importance of this protocol in @acronym{TLS}, seem awkward. This is because
87 the record protocol's parameters are all set by the handshake protocol.
88 The record protocol initially starts with NULL parameters, which means
89 no encryption, and no MAC is used. Encryption and authentication begin
90 just after the handshake protocol has finished.
93 * Encryption algorithms used in the record layer::
94 * Compression algorithms used in the record layer::
95 * Weaknesses and countermeasures::
99 @node Encryption algorithms used in the record layer
100 @subsection Encryption algorithms used in the record layer
101 @cindex symmetric encryption algorithms
103 Confidentiality in the record layer is achieved by using symmetric
104 block encryption algorithms like @code{3DES}, @code{AES}
105 or stream algorithms like @code{ARCFOUR_128}.
106 Ciphers are encryption algorithms that use a single, secret,
107 key to encrypt and decrypt data. Block algorithms in CBC mode also provide
108 protection against statistical analysis of the data. Thus, if you're
109 using the @acronym{TLS} protocol, a random number of blocks will be
110 appended to data, to prevent eavesdroppers from guessing the actual
113 The supported in @acronym{GnuTLS} ciphers and MAC algorithms are shown in @ref{tab:ciphers} and
116 @float Table,tab:ciphers
117 @multitable @columnfractions .20 .70
118 @headitem Algorithm @tab Description
119 @item 3DES_@-CBC @tab
120 This is the DES block cipher algorithm used with triple
121 encryption (EDE). Has 64 bits block size and is used in CBC mode.
123 @item ARCFOUR_@-128 @tab
124 ARCFOUR_128 is a compatible algorithm with RSA's RC4 algorithm, which is considered to be a trade
125 secret. It is a fast cipher but considered weak today.
127 @item ARCFOUR_@-40 @tab
128 This is the ARCFOUR cipher fed with a 40 bit key,
129 which is considered weak.
132 AES or RIJNDAEL is the block cipher algorithm that replaces the old
133 DES algorithm. Has 128 bits block size and is used in CBC mode.
136 This is the AES algorithm in the authenticated encryption GCM mode.
137 This mode combines message authentication and encryption and can
138 be extremely fast on CPUs that support hardware acceleration.
140 @item CAMELLIA_@-CBC @tab
141 This is an 128-bit block cipher developed by Mitsubishi and NTT. It
142 is one of the approved ciphers of the European NESSIE and Japanese
146 @caption{Supported ciphers.}
150 @float Table,tab:macs
151 @multitable @columnfractions .20 .70
152 @headitem Algorithm @tab Description
154 This is an HMAC based on MD5 a cryptographic hash algorithm designed
155 by Ron Rivest. Outputs 128 bits of data.
157 @item MAC_@-SHA1 @tab
158 An HMAC based on the SHA1 cryptographic hash algorithm
159 designed by NSA. Outputs 160 bits of data.
161 @item MAC_@-SHA256 @tab
162 An HMAC based on SHA256. Outputs 256 bits of data.
164 @item MAC_@-AEAD @tab
165 This indicates that an authenticated encryption algorithm, such as
169 @caption{Supported MAC algorithms.}
173 @node Compression algorithms used in the record layer
174 @subsection Compression algorithms used in the record layer
175 @cindex compression algorithms
177 The TLS record layer also supports compression. The algorithms
178 implemented in @acronym{GnuTLS} can be found in the table below.
179 The included algorithms perform really good when text, or other
180 compressible data are to be transferred, but offer nothing on already
181 compressed data, such as compressed images, zipped archives etc.
182 These compression algorithms, may be useful in high bandwidth TLS
183 tunnels, and in cases where network usage has to be minimized. It
184 should be noted however that compression increases latency.
186 The record layer compression in @acronym{GnuTLS} is implemented based
187 on @xcite{RFC3749}. The supported algorithms are shown below.
189 @showenumdesc{gnutls_compression_method_t,Supported compression algorithms}
191 Note that compression enables attacks such as traffic analysis, or even
192 plaintext recovery under certain circumstances. To avoid some of these
193 attacks GnuTLS allows each record to be compressed independently (i.e.,
194 stateless compression), by using the "%STATELESS_COMPRESSION" priority string,
195 in order to be used in cases where the attacker controlled data are
196 pt in separate records.
198 @node Weaknesses and countermeasures
199 @subsection Weaknesses and countermeasures
201 Some weaknesses that may affect the security of the record layer have
202 been found in @acronym{TLS} 1.0 protocol. These weaknesses can be
203 exploited by active attackers, and exploit the facts that
208 @acronym{TLS} has separate alerts for ``decryption_failed'' and
212 The decryption failure reason can be detected by timing the response
216 The IV for CBC encrypted packets is the last block of the previous
221 Those weaknesses were solved in @acronym{TLS} 1.1 @xcite{RFC4346}
222 which is implemented in @acronym{GnuTLS}. For this reason we suggest
223 to always negotiate the highest supported TLS version with the
224 peer@footnote{If this is not possible then please consult @ref{Interoperability}.}.
225 For a detailed discussion of the issues see the archives of the TLS
226 Working Group mailing list and @xcite{CBCATT}.
228 @node On Record Padding
229 @subsection On record padding
230 @cindex record padding
231 @cindex bad_record_mac
233 The TLS protocol allows for random padding of records in CBC ciphers, to prevent
234 statistical analysis based on the length of exchanged messages (see @xcite{RFC5246} section 6.2.3.2).
235 GnuTLS appears to be one of few implementation that take advantage of this text,
236 and pad records by a random length.
238 The TLS implementation in the Symbian operating system, frequently
239 used by Nokia and Sony-Ericsson mobile phones, cannot handle
240 non-minimal record padding. What happens when one of these clients
241 handshake with a GnuTLS server is that the client will fail to compute
242 the correct MAC for the record. The client sends a TLS alert
243 (@code{bad_record_mac}) and disconnects. Typically this will result
244 in error messages such as 'A TLS fatal alert has been received', 'Bad
245 record MAC', or both, on the GnuTLS server side.
247 GnuTLS implements a work around for this problem. However, it has to
248 be enabled specifically. It can be enabled by using
249 @funcref{gnutls_record_disable_padding}, or @funcref{gnutls_priority_set} with
250 the @code{%COMPAT} priority string (see @ref{Priority Strings}).
252 If you implement an application that have a configuration file, we
253 recommend that you make it possible for users or administrators to
254 specify a GnuTLS protocol priority string, which is used by your
255 application via @funcref{gnutls_priority_set}. To allow the best
256 flexibility, make it possible to have a different priority string for
257 different incoming IP addresses.
260 @node The TLS Alert Protocol
261 @section The TLS alert protocol
262 @anchor{The Alert Protocol}
263 @cindex alert protocol
265 The alert protocol is there to allow signals to be sent between peers.
266 These signals are mostly used to inform the peer about the cause of a
267 protocol failure. Some of these signals are used internally by the
268 protocol and the application protocol does not have to cope with them
269 (e.g. @code{GNUTLS_@-A_@-CLOSE_@-NOTIFY}), and others refer to the
270 application protocol solely (e.g. @code{GNUTLS_@-A_@-USER_@-CANCELLED}). An
271 alert signal includes a level indication which may be either fatal or
272 warning. Fatal alerts always terminate the current connection, and
273 prevent future re-negotiations using the current session ID. All alert
274 messages are summarized in the table below.
276 The alert messages are protected by the record protocol, thus the
277 information that is included does not leak. You must take extreme care
278 for the alert information not to leak to a possible attacker, via
279 public log files etc.
283 @node The TLS Handshake Protocol
284 @section The TLS handshake protocol
285 @anchor{The Handshake Protocol}
286 @cindex handshake protocol
288 The handshake protocol is responsible for the ciphersuite negotiation,
289 the initial key exchange, and the authentication of the two peers.
290 This is fully controlled by the application layer, thus your program
291 has to set up the required parameters. The main handshake function
292 is @funcref{gnutls_handshake}. In the next paragraphs we elaborate on
293 the handshake protocol, i.e., the ciphersuite negotiation.
297 * TLS Cipher Suites:: TLS session parameters.
298 * Authentication:: TLS authentication.
299 * Client Authentication:: Requesting a certificate from the client.
300 * Resuming Sessions:: Reusing previously established keys.
304 @node TLS Cipher Suites
305 @subsection TLS ciphersuites
307 The handshake protocol of @acronym{TLS} negotiates cipher suites of
308 a special form illustrated by the @code{TLS_DHE_RSA_WITH_3DES_CBC_SHA} cipher suite name. A typical cipher
309 suite contains these parameters:
313 @item The key exchange algorithm.
314 @code{DHE_RSA} in the example.
316 @item The Symmetric encryption algorithm and mode
317 @code{3DES_CBC} in this example.
319 @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.
320 @code{MAC_SHA} is used in the above example.
324 The cipher suite negotiated in the handshake protocol will affect the
325 record protocol, by enabling encryption and data authentication. Note
326 that you should not over rely on @acronym{TLS} to negotiate the
327 strongest available cipher suite. Do not enable ciphers and algorithms
328 that you consider weak.
330 All the supported ciphersuites are listed in @ref{ciphersuites}.
333 @subsection Authentication
335 The key exchange algorithms of the @acronym{TLS} protocol offer
336 authentication, which is a prerequisite for a secure connection.
337 The available authentication methods in @acronym{GnuTLS} follow.
341 @item Certificate authentication: Authenticated key exchange using public key infrastructure and certificates (X.509 or OpenPGP).
342 @item @acronym{SRP} authentication: Authenticated key exchange using a password.
343 @item @acronym{PSK} authentication: Authenticated key exchange using a pre-shared key.
344 @item Anonymous authentication: Key exchange without peer authentication.
348 @node Client Authentication
349 @subsection Client authentication
350 @cindex client certificate authentication
352 In the case of ciphersuites that use certificate authentication, the
353 authentication of the client is optional in @acronym{TLS}. A server
354 may request a certificate from the client using the
355 @funcref{gnutls_certificate_server_set_request} function. We elaborate
356 in @ref{Certificate credentials}.
358 @node Resuming Sessions
359 @subsection Resuming sessions
361 @cindex resuming sessions
362 @cindex session resumption
364 The TLS handshake process performs expensive calculations
365 and a busy server might easily be put under load. To
366 reduce the load, session resumption may be used. This
367 is a feature of the @acronym{TLS} protocol which allows a
368 client to connect to a server after a successful handshake, without
369 the expensive calculations. This is achieved by re-using the previously
370 established keys, meaning the server needs to store the state of established
371 connections (unless session tickets are used -- @ref{Session tickets}).
373 Session resumption is an integral part of @acronym{GnuTLS}, and
374 @ref{Session resumption} and @ref{ex:resume-client} illustrate typical
378 @section TLS extensions
379 @cindex TLS extensions
381 A number of extensions to the @acronym{TLS} protocol have been
382 proposed mainly in @xcite{TLSEXT}. The extensions supported
383 in @acronym{GnuTLS} are:
386 @item Maximum fragment length negotiation
387 @item Server name indication
388 @item Session tickets
390 @item Safe Renegotiation
393 and they will be discussed in the subsections that follow.
396 * Maximum fragment length negotiation::
397 * Server name indication::
400 * Safe renegotiation::
401 * OCSP status request::
404 @node Maximum fragment length negotiation
405 @subsection Maximum fragment length negotiation
406 @cindex TLS extensions
407 @cindex maximum fragment length
409 This extension allows a @acronym{TLS} implementation to negotiate a
410 smaller value for record packet maximum length. This extension may be
411 useful to clients with constrained capabilities. The functions shown
412 below can be used to control this extension.
414 @showfuncB{gnutls_record_get_max_size,gnutls_record_set_max_size}
416 @node Server name indication
417 @subsection Server name indication
419 @cindex TLS extensions
420 @cindex server name indication
422 A common problem in @acronym{HTTPS} servers is the fact that the
423 @acronym{TLS} protocol is not aware of the hostname that a client
424 connects to, when the handshake procedure begins. For that reason the
425 @acronym{TLS} server has no way to know which certificate to send.
427 This extension solves that problem within the @acronym{TLS} protocol,
428 and allows a client to send the HTTP hostname before the handshake
429 begins within the first handshake packet. The functions
430 @funcref{gnutls_server_name_set} and @funcref{gnutls_server_name_get} can be
431 used to enable this extension, or to retrieve the name sent by a
434 @showfuncB{gnutls_server_name_set,gnutls_server_name_get}
436 @node Session tickets
437 @subsection Session tickets
438 @cindex TLS extensions
439 @cindex session tickets
442 To resume a TLS session the server normally store session parameters. This
443 complicates deployment, and could be avoiding by delegating the storage
444 to the client. Because session parameters are sensitive they are encrypted
445 and authenticated with a key only known to the server and then sent to the
446 client. The Session Tickets extension is described in RFC 5077 @xcite{TLSTKT}.
448 Since version 3.1.3 GnuTLS clients transparently support session tickets.
451 @subsection HeartBeat
452 @cindex TLS extensions
455 This TLS extension allows to ping and receive confirmation from the peer,
456 is described in @xcite{RFC6520}. The extension is disabled by default and
457 @funcref{gnutls_heartbeat_enable} can be used to enable it. A policy
458 may be negotiated to only allow sending heartbeat messages or sending and receiving.
459 The current session policy can be checked with @funcref{gnutls_heartbeat_allowed}.
460 The requests coming from the peer result to @code{GNUTLS_@-E_@-HERTBEAT_@-PING_@-RECEIVED}
461 being returned from the receive function. Ping requests to peer can be send via
462 @funcref{gnutls_heartbeat_ping}.
464 @showfuncB{gnutls_heartbeat_allowed,gnutls_heartbeat_enable}
466 @showfuncD{gnutls_heartbeat_ping,gnutls_heartbeat_pong,gnutls_heartbeat_set_timeouts,gnutls_heartbeat_get_timeout}
468 @node Safe renegotiation
469 @subsection Safe renegotiation
470 @cindex renegotiation
471 @cindex safe renegotiation
473 TLS gives the option to two communicating parties to renegotiate
474 and update their security parameters. One useful example of this feature
475 was for a client to initially connect using anonymous negotiation to a
476 server, and the renegotiate using some authenticated ciphersuite. This occurred
477 to avoid having the client sending its credentials in the clear.
479 However this renegotiation, as initially designed would not ensure that
480 the party one is renegotiating is the same as the one in the initial negotiation.
481 For example one server could forward all renegotiation traffic to an other
482 server who will see this traffic as an initial negotiation attempt.
484 This might be seen as a valid design decision, but it seems it was
485 not widely known or understood, thus today some application protocols the TLS
486 renegotiation feature in a manner that enables a malicious server to insert
487 content of his choice in the beginning of a TLS session.
489 The most prominent vulnerability was with HTTPS. There servers request
490 a renegotiation to enforce an anonymous user to use a certificate in order
491 to access certain parts of a web site. The
492 attack works by having the attacker simulate a client and connect to a
493 server, with server-only authentication, and send some data intended
494 to cause harm. The server will then require renegotiation from him
495 in order to perform the request.
496 When the proper client attempts to contact the server,
497 the attacker hijacks that connection and forwards traffic to
498 the initial server that requested renegotiation. The
499 attacker will not be able to read the data exchanged between the
500 client and the server. However, the server will (incorrectly) assume
501 that the initial request sent by the attacker was sent by the now authenticated
502 client. The result is a prefix plain-text injection attack.
504 The above is just one example. Other vulnerabilities exists that do
505 not rely on the TLS renegotiation to change the client's authenticated
506 status (either TLS or application layer).
508 While fixing these application protocols and implementations would be
509 one natural reaction, an extension to TLS has been designed that
510 cryptographically binds together any renegotiated handshakes with the
511 initial negotiation. When the extension is used, the attack is
512 detected and the session can be terminated. The extension is
513 specified in @xcite{RFC5746}.
515 GnuTLS supports the safe renegotiation extension. The default
516 behavior is as follows. Clients will attempt to negotiate the safe
517 renegotiation extension when talking to servers. Servers will accept
518 the extension when presented by clients. Clients and servers will
519 permit an initial handshake to complete even when the other side does
520 not support the safe renegotiation extension. Clients and servers
521 will refuse renegotiation attempts when the extension has not been
524 Note that permitting clients to connect to servers when the safe
525 renegotiation extension is not enabled, is open up for attacks.
526 Changing this default behavior would prevent interoperability against
527 the majority of deployed servers out there. We will reconsider this
528 default behavior in the future when more servers have been upgraded.
529 Note that it is easy to configure clients to always require the safe
530 renegotiation extension from servers.
532 To modify the default behavior, we have introduced some new priority
533 strings (see @ref{Priority Strings}).
534 The @code{%UNSAFE_RENEGOTIATION} priority string permits
535 (re-)handshakes even when the safe renegotiation extension was not
536 negotiated. The default behavior is @code{%PARTIAL_RENEGOTIATION} that will
537 prevent renegotiation with clients and servers not supporting the
538 extension. This is secure for servers but leaves clients vulnerable
539 to some attacks, but this is a trade-off between security and compatibility
540 with old servers. The @code{%SAFE_RENEGOTIATION} priority string makes
541 clients and servers require the extension for every handshake. The latter
542 is the most secure option for clients, at the cost of not being able
543 to connect to legacy servers. Servers will also deny clients that
544 do not support the extension from connecting.
546 It is possible to disable use of the extension completely, in both
547 clients and servers, by using the @code{%DISABLE_SAFE_RENEGOTIATION}
548 priority string however we strongly recommend you to only do this for
549 debugging and test purposes.
551 The default values if the flags above are not specified are:
555 %PARTIAL_RENEGOTIATION
558 %PARTIAL_RENEGOTIATION
562 For applications we have introduced a new API related to safe
563 renegotiation. The @funcref{gnutls_safe_renegotiation_status} function is
564 used to check if the extension has been negotiated on a session, and
565 can be used both by clients and servers.
567 @node OCSP status request
568 @subsection OCSP status request
569 @cindex OCSP status request
570 @cindex Certificate status request
572 The Online Certificate Status Protocol (OCSP) is a protocol that allows the
573 client to verify the server certificate for revocation without messing with
574 certificate revocation lists. Its drawback is that it requires the client
575 to connect to the server's CA OCSP server and request the status of the
576 certificate. This extension however, enables a TLS server to include
577 its CA OCSP server response in the handshake. That is an HTTPS server
578 may periodically run @code{ocsptool} (see @ref{ocsptool Invocation}) to obtain
579 its certificate revocation status and serve it to the clients. This
580 reduces the number of connections a client needs to perform to access a
583 @showfuncB{gnutls_certificate_set_ocsp_status_request_function,gnutls_certificate_set_ocsp_status_request_file}
585 @showfuncA{gnutls_ocsp_status_request_enable_client}
587 Since version 3.1.3 GnuTLS clients transparently support the certificate status
590 @include sec-tls-app.texi
592 @node On SSL 2 and older protocols
593 @section On SSL 2 and older protocols
596 One of the initial decisions in the @acronym{GnuTLS} development was
597 to implement the known security protocols for the transport layer.
598 Initially @acronym{TLS} 1.0 was implemented since it was the latest at
599 that time, and was considered to be the most advanced in security
600 properties. Later the @acronym{SSL} 3.0 protocol was implemented
601 since it is still the only protocol supported by several servers and
602 there are no serious security vulnerabilities known.
604 One question that may arise is why we didn't implement @acronym{SSL}
605 2.0 in the library. There are several reasons, most important being
606 that it has serious security flaws, unacceptable for a modern security
607 library. Other than that, this protocol is barely used by anyone
608 these days since it has been deprecated since 1996. The security
609 problems in @acronym{SSL} 2.0 include:
613 @item Message integrity compromised.
614 The @acronym{SSLv2} message authentication uses the MD5 function, and
617 @item Man-in-the-middle attack.
618 There is no protection of the handshake in @acronym{SSLv2}, which
619 permits a man-in-the-middle attack.
621 @item Truncation attack.
622 @acronym{SSLv2} relies on TCP FIN to close the session, so the
623 attacker can forge a TCP FIN, and the peer cannot tell if it was a
624 legitimate end of data or not.
626 @item Weak message integrity for export ciphers.
627 The cryptographic keys in @acronym{SSLv2} are used for both message
628 authentication and encryption, so if weak encryption schemes are
629 negotiated (say 40-bit keys) the message authentication code uses the
630 same weak key, which isn't necessary.
635 Other protocols such as Microsoft's @acronym{PCT} 1 and @acronym{PCT}
636 2 were not implemented because they were also abandoned and deprecated
637 by @acronym{SSL} 3.0 and later @acronym{TLS} 1.0.