The handshake protocol is responsible for the security parameters'
negotiation, the initial key exchange and authentication.
@xref{The Handshake Protocol}, for more information about the handshake
-protocol. The protocol layering in TLS is shown in @ref{fig:tls-layers}.
+protocol. The protocol layering in TLS is shown in @ref{fig-tls-layers}.
-@float Figure,fig:tls-layers
+@float Figure,fig-tls-layers
@image{gnutls-layers,12cm}
@caption{The TLS protocol layers.}
@end float
ARCFOUR_128 is a compatible algorithm with RSA's RC4 algorithm, which is considered to be a trade
secret. It is a fast cipher but considered weak today.
-@item ARCFOUR_@-40 @tab
-This is the ARCFOUR cipher fed with a 40 bit key,
-which is considered weak.
-
@item AES_@-CBC @tab
AES or RIJNDAEL is the block cipher algorithm that replaces the old
DES algorithm. Has 128 bits block size and is used in CBC mode.
Note that compression enables attacks such as traffic analysis, or even
plaintext recovery under certain circumstances. To avoid some of these
attacks GnuTLS allows each record to be compressed independently (i.e.,
-stateless compression), by using the "%STATELESS_COMPRESSION" priority string.
+stateless compression), by using the "%STATELESS_COMPRESSION" priority string,
+in order to be used in cases where the attacker controlled data are
+pt in separate records.
@node Weaknesses and countermeasures
@subsection Weaknesses and countermeasures
@cindex record padding
@cindex bad_record_mac
-The TLS protocol allows for random padding of records in CBC ciphers, to prevent
+The TLS protocol allows for extra padding of records in CBC ciphers, to prevent
statistical analysis based on the length of exchanged messages (see @xcite{RFC5246} section 6.2.3.2).
-GnuTLS appears to be one of few implementation that take advantage of this text,
-and pad records by a random length.
+GnuTLS appears to be one of few implementations that take advantage of this feature:
+the user can provide some plaintext data with a range of lengths she wishes to hide,
+and GnuTLS adds extra padding to make sure the attacker cannot tell the real plaintext
+length is in a range smaller than the user-provided one.
+Use @funcref{gnutls_record_send_range} to send length-hidden messages and
+@funcref{gnutls_record_can_use_length_hiding} to check whether the current
+session supports length hiding. Using the standard @funcref{gnutls_record_send}
+will only add minimal padding.
The TLS implementation in the Symbian operating system, frequently
used by Nokia and Sony-Ericsson mobile phones, cannot handle
in error messages such as 'A TLS fatal alert has been received', 'Bad
record MAC', or both, on the GnuTLS server side.
-GnuTLS implements a work around for this problem. However, it has to
-be enabled specifically. It can be enabled by using
-@funcref{gnutls_record_disable_padding}, or @funcref{gnutls_priority_set} with
-the @code{%COMPAT} priority string (see @ref{Priority Strings}).
+If compatibility with such devices is a concern, not sending length-hidden messages
+solves the problem by using minimal padding.
-If you implement an application that have a configuration file, we
+If you implement an application that has a configuration file, we
recommend that you make it possible for users or administrators to
specify a GnuTLS protocol priority string, which is used by your
application via @funcref{gnutls_priority_set}. To allow the best
connections (unless session tickets are used -- @ref{Session tickets}).
Session resumption is an integral part of @acronym{GnuTLS}, and
-@ref{Session resumption} and @ref{ex:resume-client} illustrate typical
+@ref{Session resumption}, @ref{ex-resume-client} illustrate typical
uses of it.
@node TLS Extensions
A number of extensions to the @acronym{TLS} protocol have been
proposed mainly in @xcite{TLSEXT}. The extensions supported
-in @acronym{GnuTLS} are:
-
-@itemize
-@item Maximum fragment length negotiation
-@item Server name indication
-@item Session tickets
-@item Safe Renegotiation
-@end itemize
-
-and they will be discussed in the subsections that follow.
+in @acronym{GnuTLS} are discussed in the subsections that follow.
@menu
* Maximum fragment length negotiation::
* Server name indication::
* Session tickets::
+* HeartBeat::
* Safe renegotiation::
+* OCSP status request::
+* SRTP::
+* Application Layer Protocol Negotiation (ALPN)::
@end menu
@node Maximum fragment length negotiation
@cindex session tickets
@cindex tickets
-To resume a TLS session the server normally store session parameters. This
-complicates deployment, and could be avoiding by delegating the storage
+To resume a TLS session, the server normally stores session parameters. This
+complicates deployment, and can be avoided by delegating the storage
to the client. Because session parameters are sensitive they are encrypted
and authenticated with a key only known to the server and then sent to the
-client. The Session Tickets in RFC 5077 @xcite{TLSTKT}, describe this
-idea, which is implemented in GnuTLS.
+client. The Session Tickets extension is described in RFC 5077 @xcite{TLSTKT}.
+
+A disadvantage of session tickets is that they eliminate the effects of
+forward secrecy when a server uses the same key for long time. That is,
+the secrecy of all sessions on a server using tickets depends on the ticket
+key being kept secret. For that reason server keys should be rotated and discarded
+regularly.
+
+Since version 3.1.3 GnuTLS clients transparently support session tickets.
+
+@node HeartBeat
+@subsection HeartBeat
+@cindex TLS extensions
+@cindex heartbeat
+
+This is a TLS extension that allows to ping and receive confirmation from the peer,
+and is described in @xcite{RFC6520}. The extension is disabled by default and
+@funcref{gnutls_heartbeat_enable} can be used to enable it. A policy
+may be negotiated to only allow sending heartbeat messages or sending and receiving.
+The current session policy can be checked with @funcref{gnutls_heartbeat_allowed}.
+The requests coming from the peer result to @code{GNUTLS_@-E_@-HERTBEAT_@-PING_@-RECEIVED}
+being returned from the receive function. Ping requests to peer can be send via
+@funcref{gnutls_heartbeat_ping}.
+
+@showfuncB{gnutls_heartbeat_allowed,gnutls_heartbeat_enable}
+
+@showfuncD{gnutls_heartbeat_ping,gnutls_heartbeat_pong,gnutls_heartbeat_set_timeouts,gnutls_heartbeat_get_timeout}
@node Safe renegotiation
@subsection Safe renegotiation
server who will see this traffic as an initial negotiation attempt.
This might be seen as a valid design decision, but it seems it was
-not widely known or understood, thus today some application protocols the TLS
+not widely known or understood, thus today some application protocols use the TLS
renegotiation feature in a manner that enables a malicious server to insert
content of his choice in the beginning of a TLS session.
used to check if the extension has been negotiated on a session, and
can be used both by clients and servers.
+@node OCSP status request
+@subsection OCSP status request
+@cindex OCSP status request
+@cindex Certificate status request
+
+The Online Certificate Status Protocol (OCSP) is a protocol that allows the
+client to verify the server certificate for revocation without messing with
+certificate revocation lists. Its drawback is that it requires the client
+to connect to the server's CA OCSP server and request the status of the
+certificate. This extension however, enables a TLS server to include
+its CA OCSP server response in the handshake. That is an HTTPS server
+may periodically run @code{ocsptool} (see @ref{ocsptool Invocation}) to obtain
+its certificate revocation status and serve it to the clients. That
+way a client avoids an additional connection to the OCSP server.
+
+@showfuncD{gnutls_certificate_set_ocsp_status_request_function,gnutls_certificate_set_ocsp_status_request_file,gnutls_ocsp_status_request_enable_client,gnutls_ocsp_status_request_is_checked}
+
+A server is required to provide the OCSP server's response using the @funcref{gnutls_certificate_set_ocsp_status_request_file}.
+The response may be obtained periodically using the following command.
+
+@example
+ocsptool --ask --load-cert server_cert.pem --load-issuer the_issuer.pem
+ --load-signer the_issuer.pem --outfile ocsp.response
+@end example
+
+Since version 3.1.3 GnuTLS clients transparently support the certificate status
+request.
+
+@node SRTP
+@subsection SRTP
+@cindex SRTP
+@cindex Secure RTP
+
+The TLS protocol was extended in @xcite{RFC5764} to provide keying material to the
+Secure RTP (SRTP) protocol. The SRTP protocol provides an encapsulation of encrypted
+data that is optimized for voice data. With the SRTP TLS extension two peers can
+negotiate keys using TLS or DTLS and obtain keying material for use with SRTP. The
+available SRTP profiles are listed below.
+
+@showenumdesc{gnutls_srtp_profile_t,Supported SRTP profiles}
+
+To enable use the following functions.
+
+@showfuncB{gnutls_srtp_set_profile,gnutls_srtp_set_profile_direct}
+
+To obtain the negotiated keys use the function below.
+
+@showfuncdesc{gnutls_srtp_get_keys}
+
+Other helper functions are listed below.
+
+@showfuncC{gnutls_srtp_get_selected_profile,gnutls_srtp_get_profile_name,gnutls_srtp_get_profile_id}
+
+@node Application Layer Protocol Negotiation (ALPN)
+@subsection Application Layer Protocol Negotiation (ALPN)
+@cindex ALPN
+@cindex Application Layer Protocol Negotiation
+
+The TLS protocol was extended in @code{draft-ietf-tls-applayerprotoneg-00}
+to provide the application layer a method of
+negotiating the application protocol version. This allows for negotiation
+of the application protocol during the TLS handshake, thus reducing
+round-trips. The application protocol is described by an opaque
+string. To enable, use the following functions.
+
+@showfuncB{gnutls_alpn_set_protocols,gnutls_alpn_get_selected_protocol}
+
+Note that these functions are intended to be used with protocols that are
+registered in the Application Layer Protocol Negotiation IANA registry. While
+you can use them for other protocols (at the risk of collisions), it is preferable
+to register them.
+
@include sec-tls-app.texi
@node On SSL 2 and older protocols
projects / platform / upstream / gnutls.git / blobdiff