doc: updated for TLS1.3

Signed-off-by: Nikos Mavrogiannopoulos <nmav@redhat.com>

4 files changed, 139 insertions, 160 deletions

diff --git a/doc/cha-cert-auth2.texi b/doc/cha-cert-auth2.texi
index f0f0f825c5..e325b614c1 100644
--- a/doc/cha-cert-auth2.texi
+++ b/doc/cha-cert-auth2.texi
@@ -341,7 +341,7 @@ expiration can be obtained using the @funcref{gnutls_certificate_get_ocsp_expira
 
 @showfuncdesc{gnutls_certificate_get_ocsp_expiration}
 
-Prior to GnuTLS 3.6.xx, the functions
+Prior to GnuTLS 3.6.4, the functions
 @funcref{gnutls_certificate_set_ocsp_status_request_function2}
 @funcref{gnutls_certificate_set_ocsp_status_request_file} were provided
 to set OCSP responses. These functions are still functional, but cannot be used
diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 655046c917..6fbf490288 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -888,25 +888,25 @@ no data have been received.
 
 The full TLS 1.2 handshake requires 2 round-trips to complete, and when
 combined with TCP's SYN and SYN-ACK negotiation it extends to 3 full
-round-trips. While, the abbreviated (resumed) TLS handshake drops that to 2.5
-round-trips, it still adds considerable latency, reducing its applicability
-to certain applications.
+round-trips. While, TLS 1.3 reduces that to two round-trips when under TCP,
+it still adds considerable latency, making the protocol unsuitable for
+certain applications.
 
-In client side, it is possible to take advantage of the TCP fast open
-@xcite{RFC7413} mechanism on operating
+To optimize the handshake latency, in client side, it is possible to take
+advantage of the TCP fast open @xcite{RFC7413} mechanism on operating
 systems that support it. That can be done either by manually crafting the push and pull
 callbacks, or by utilizing @funcref{gnutls_transport_set_fastopen}. In that
-case the initial TCP handshake is eliminated, reducing the TLS handshake round-trip to 2.
-Note, that in that case any connection failures will be reported during the
-@funcref{gnutls_handshake} function call with error code
-@code{GNUTLS_E_PUSH_ERROR}.
+case the initial TCP handshake is eliminated, reducing the TLS 1.2 handshake round-trip
+to 2, and the TLS 1.3 handshake to a single round-trip.
+Note, that when this function is used, any connection failures will be reported during the
+@funcref{gnutls_handshake} function call with error code @code{GNUTLS_E_PUSH_ERROR}.
 
 @showfuncdesc{gnutls_transport_set_fastopen}
 
-In non-resumed sessions it is possible to further reduce the round-trips to
-a single one by taking advantage of the @ref{False Start} TLS extension.
-This can be enabled by setting the @acronym{GNUTLS_ENABLE_FALSE_START} flag
-on @funcref{gnutls_init}.
+When restricted to TLS 1.2, and non-resumed sessions, it is possible to further
+reduce the round-trips to a single one by taking advantage of the @ref{False Start}
+TLS extension. This can be enabled by setting the @acronym{GNUTLS_ENABLE_FALSE_START}
+flag on @funcref{gnutls_init}.
 
 @node DTLS sessions
 @subsection DTLS sessions
@@ -1228,11 +1228,10 @@ all the algorithms from NORMAL priority.
 
 @item Key exchange @tab
 RSA, DHE-RSA, DHE-DSS, SRP, SRP-RSA, SRP-DSS,
-PSK, DHE-PSK, ECDHE-RSA, ECDHE-ECDSA, ECDHE-PSK, ANON-ECDH, ANON-DH. The
+PSK, DHE-PSK, ECDHE-PSK, ECDHE-RSA, ECDHE-ECDSA, ANON-ECDH, ANON-DH. The
 Catch all name is KX-ALL which will add all the algorithms from NORMAL
-priority.
-
-Add @code{!DHE-RSA:!DHE-DSS} to the priority string to disable DHE.
+priority. Under TLS1.3, the DHE-PSK and ECDHE-PSK strings are equivalent
+and instruct for a Diffie-Hellman key exchange using the enabled groups.
 
 @item MAC @tab
 MD5, SHA1, SHA256, SHA384, AEAD (used with
@@ -1242,10 +1241,11 @@ GCM ciphers only). All algorithms from NORMAL priority can be accessed with MAC-
 COMP-NULL, COMP-DEFLATE. Catch all is COMP-ALL.
 
 @item TLS versions @tab
-VERS-TLS1.0, VERS-TLS1.1, VERS-TLS1.2,
+VERS-TLS1.0, VERS-TLS1.1, VERS-TLS1.2, VERS-TLS1.3,
 VERS-DTLS1.0, VERS-DTLS1.2. 
-Catch all are VERS-ALL, VERS-TLS-ALL and VERS-DTLS-ALL, and will enable
-all protocols from NORMAL priority.
+Catch all are VERS-ALL, and will enable
+all protocols from NORMAL priority. To distinguish between TLS and DTLS
+versions you can use VERS-TLS-ALL and VERS-DTLS-ALL.
 
 @item Signature algorithms @tab
 SIGN-RSA-SHA1, SIGN-RSA-SHA224,
@@ -1256,13 +1256,6 @@ SIGN-RSA-PSS-SHA256, SIGN-RSA-PSS-SHA384, SIGN-RSA-PSS-SHA512.
 Catch all which enables all algorithms from NORMAL priority is SIGN-ALL.
 This option is only considered for TLS 1.2 and later.
 
-@item Elliptic curves @tab
-CURVE-SECP192R1, CURVE-SECP224R1, CURVE-SECP256R1, CURVE-SECP384R1,
-CURVE-SECP521R1, and CURVE-X25519.
-Catch all which enables all curves from NORMAL priority is CURVE-ALL. Note
-that the CURVE keyword is kept for backwards compatibility only, for new
-applications see the GROUP keyword below.
-
 @item Groups @tab
 GROUP-SECP256R1, GROUP-SECP384R1, GROUP-SECP521R1, GROUP-X25519,
 GROUP-FFDHE2048, GROUP-FFDHE3072, GROUP-FFDHE4096 and GROUP-FFDHE8192.
@@ -1272,15 +1265,22 @@ from NORMAL priority is GROUP-ALL. The helper keywords GROUP-DH-ALL and
 GROUP-EC-ALL are also available, restricting the groups to finite fields
 (DH) and elliptic curves.
 
-@item Certificate type @tab
-The only option currently is CTYPE-X509. Catch all is CTYPE-ALL.
+@item Elliptic curves (legacy) @tab
+CURVE-SECP192R1, CURVE-SECP224R1, CURVE-SECP256R1, CURVE-SECP384R1,
+CURVE-SECP521R1, and CURVE-X25519.
+Catch all which enables all curves from NORMAL priority is CURVE-ALL. Note
+that the CURVE keyword is kept for backwards compatibility only, for new
+applications see the GROUP keyword above.
+
+@c @item Certificate type @tab
+@c The only option currently is CTYPE-X509. Catch all is CTYPE-ALL.
 
 @end multitable
 @caption{The supported algorithm keywords in priority strings.}
 @end float
 
-Note that the DHE key exchange methods are generally
-slower@footnote{It depends on the group in use.  Groups with
+Note that the finite field groups (indicated by the FFDHE prefix) and DHE key
+exchange methods are generally slower@footnote{It depends on the group in use.  Groups with
 less bits are always faster, but the number of bits ties with the security
 parameter.  See @ref{Selecting cryptographic key sizes}
 for the acceptable security levels.} than their elliptic curves counterpart
diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi
index 1d508bbca0..a7c8a55112 100644
--- a/doc/cha-intro-tls.texi
+++ b/doc/cha-intro-tls.texi
@@ -94,7 +94,6 @@ just after the handshake protocol has finished.
 @menu
 * Encryption algorithms used in the record layer::
 * Compression algorithms and the record layer::
-* Weaknesses and countermeasures::
 * On Record Padding::
 @end menu
 
@@ -117,56 +116,65 @@ The supported in @acronym{GnuTLS} ciphers and MAC algorithms are shown in @ref{t
 @ref{tab:macs}.
 
 @float Table,tab:ciphers
-@multitable @columnfractions .20 .20 .60
-@headitem Algorithm @tab Type @tab Description
+@multitable @columnfractions .20 .10 .15 .55
+@headitem Algorithm @tab Type @tab Applicable Protocols @tab Description
 @item AES-128-GCM, AES-256-GCM @tab
 AEAD @tab
+TLS 1.2, TLS 1.3 @tab
 This is the AES algorithm in the authenticated encryption GCM mode.
 This mode combines message authentication and encryption and can
 be extremely fast on CPUs that support hardware acceleration.
 
 @item AES-128-CCM, AES-256-CCM @tab
 AEAD @tab
+TLS 1.2, TLS 1.3 @tab
 This is the AES algorithm in the authenticated encryption CCM mode.
 This mode combines message authentication and encryption and is
 often used by systems without AES or GCM acceleration support.
 
+@item CHACHA20-POLY1305 @tab
+AEAD @tab
+TLS 1.2, TLS 1.3 @tab
+CHACHA20-POLY1305 is an authenticated encryption algorithm based on CHACHA20 cipher and
+POLY1305 MAC. CHACHA20 is a refinement of SALSA20 algorithm, an approved cipher by
+the European ESTREAM project. POLY1305 is Wegman-Carter, one-time authenticator. The
+combination provides a fast stream cipher suitable for systems where a hardware AES
+accelerator is not available.
+
 @item AES-128-CCM-8, AES-256-CCM-8 @tab
 AEAD @tab
+TLS 1.2, TLS 1.3 @tab
 This is the AES algorithm in the authenticated encryption CCM mode
 with a truncated to 64-bit authentication tag. This mode is for
 communication with restricted systems.
 
 @item CAMELLIA-128-GCM, CAMELLIA-256-GCM @tab
 AEAD @tab
+TLS 1.2 @tab
 This is the CAMELLIA algorithm in the authenticated encryption GCM mode.
 
-@item CHACHA20-POLY1305 @tab
-AEAD @tab
-CHACHA20-POLY1305 is an authenticated encryption algorithm based on CHACHA20 cipher and
-POLY1305 MAC. CHACHA20 is a refinement of SALSA20 algorithm, an approved cipher by
-the European ESTREAM project. POLY1305 is Wegman-Carter, one-time authenticator. The
-combination provides a fast stream cipher suitable for systems where a hardware AES
-accelerator is not available.
-
 @item AES-128-CBC, AES-256-CBC @tab
 Legacy (block) @tab
+TLS 1.0, TLS 1.1, TLS 1.2 @tab
 AES or RIJNDAEL is the block cipher algorithm that replaces the old
 DES algorithm.  It has 128 bits block size and is used in CBC mode.
 
 @item CAMELLIA-128-CBC, CAMELLIA-256-CBC @tab
 Legacy (block) @tab
+TLS 1.0, TLS 1.1, TLS 1.2 @tab
 This is an 128-bit block cipher developed by Mitsubishi and NTT. It
 is one of the approved ciphers of the European NESSIE and Japanese
 CRYPTREC projects.
 
 @item 3DES-CBC @tab
 Legacy (block) @tab
+TLS 1.0, TLS 1.1, TLS 1.2 @tab
 This is the DES block cipher algorithm used with triple
 encryption (EDE). Has 64 bits block size and is used in CBC mode.
 
 @item ARCFOUR-128 @tab
 Legacy (stream) @tab
+TLS 1.0, TLS 1.1, TLS 1.2 @tab
 ARCFOUR-128 is a compatible algorithm with RSA's RC4 algorithm, which is considered to be a trade
 secret. It is a considered to be broken, and is only used for compatibility
 purposed. For this reason it is not enabled by default.
@@ -212,71 +220,26 @@ based on traffic analysis on the transported data. For that newer versions of th
 offer compression, and @acronym{GnuTLS} since 3.6.0 no longer implements any
 support for compression.
 
-@node Weaknesses and countermeasures
-@subsection Weaknesses and countermeasures
-
-Some weaknesses that may affect the security of the record layer have
-been found in @acronym{TLS} 1.0 protocol. These weaknesses can be
-exploited by active attackers, and exploit the facts that
-
-@enumerate
-
-@item
-@acronym{TLS} has separate alerts for ``decryption_failed'' and
-``bad_record_mac''
-
-@item
-The decryption failure reason can be detected by timing the response
-time.
-
-@item
-The IV for CBC encrypted packets is the last block of the previous
-encrypted packet.
-
-@end enumerate
-
-Those weaknesses were solved in @acronym{TLS} 1.1 @xcite{RFC4346}
-which is implemented in @acronym{GnuTLS}. For this reason we suggest
-to always negotiate the highest supported TLS version with the 
-peer@footnote{If this is not possible then please consult @ref{Interoperability}.}.
-For a detailed discussion of the issues see the archives of the TLS 
-Working Group mailing list and @xcite{CBCATT}.
-
 @node On Record Padding
 @subsection On record padding
 @cindex record padding
 @cindex bad_record_mac
 
-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 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
-non-minimal record padding.  What happens when one of these clients
-handshake with a GnuTLS server is that the client will fail to compute
-the correct MAC for the record.  The client sends a TLS alert
-(@code{bad_record_mac}) and disconnects.  Typically this will result
-in error messages such as 'A TLS fatal alert has been received', 'Bad
-record MAC', or both, on the GnuTLS server side.
-
-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 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
-flexibility, make it possible to have a different priority string for
-different incoming IP addresses.
+The TLS 1.3 protocol allows for extra padding of records to prevent
+statistical analysis based on the length of exchanged messages.
+GnuTLS takes advantage of this feature, by allowing the user
+to specify the amount of padding for a particular message. The simplest
+interface is provided by @funcref{gnutls_record_send2}, and is made
+available when under TLS1.3; alternatively @funcref{gnutls_record_can_use_length_hiding}
+can be queried.
+
+@showfuncdesc{gnutls_record_send2}
 
+Older GnuTLS versions provided an API suitable for cases where the sender
+sends data that are always within a given range. That API is still
+available, and consists of the following functions.
+
+@showfuncB{gnutls_record_can_use_length_hiding,gnutls_record_send_range}
 
 @node The TLS Alert Protocol
 @section The TLS alert protocol
@@ -290,9 +253,9 @@ protocol and the application protocol does not have to cope with them
 (e.g. @code{GNUTLS_@-A_@-CLOSE_@-NOTIFY}), and others refer to the
 application protocol solely (e.g. @code{GNUTLS_@-A_@-USER_@-CANCELLED}).  An
 alert signal includes a level indication which may be either fatal or
-warning. Fatal alerts always terminate the current connection, and
-prevent future re-negotiations using the current session ID. All alert
-messages are summarized in the table below.
+warning (under TLS1.3 all alerts are fatal). Fatal alerts always terminate
+the current connection, and prevent future re-negotiations using the current
+session ID. All supported alert messages are summarized in the table below.
 
 The alert messages are protected by the record protocol, thus the
 information that is included does not leak. You must take extreme care
@@ -325,9 +288,14 @@ the handshake protocol, i.e., the ciphersuite negotiation.
 @node TLS Cipher Suites
 @subsection TLS ciphersuites
 
-The handshake protocol of @acronym{TLS} negotiates cipher suites of
-a special form illustrated by the @code{TLS_DHE_RSA_WITH_3DES_CBC_SHA} cipher suite name.  A typical cipher
-suite contains these parameters:
+The TLS cipher suites have slightly different meaning under different
+protocols. Under @acronym{TLS 1.3}, a cipher suite indicates the symmetric
+encryption algorithm in use, as well as the pseudo-random function (PRF)
+used in the TLS session.
+
+Under TLS 1.2 or early the handshake protocol negotiates cipher suites of
+a special form illustrated by the @code{TLS_DHE_RSA_WITH_3DES_CBC_SHA} cipher suite name.
+A typical cipher suite contains these parameters:
 
 @itemize
 
@@ -355,13 +323,22 @@ All the supported ciphersuites are listed in @ref{ciphersuites}.
 
 The key exchange algorithms of the @acronym{TLS} protocol offer
 authentication, which is a prerequisite for a secure connection. 
-The available authentication methods in @acronym{GnuTLS} follow.
+The available authentication methods in @acronym{GnuTLS}, under
+TLS 1.3 or earlier versions, follow.
 
 @itemize
 
 @item Certificate authentication: Authenticated key exchange using public key infrastructure and X.509 certificates.
-@item @acronym{SRP} authentication: Authenticated key exchange using a password.
 @item @acronym{PSK} authentication: Authenticated key exchange using a pre-shared key.
+
+@end itemize
+
+Under TLS 1.2 or earlier versions, the following authentication methods
+are also available.
+
+@itemize
+
+@item @acronym{SRP} authentication: Authenticated key exchange using a password.
 @item Anonymous authentication: Key exchange without peer authentication.
 
 @end itemize
diff --git a/doc/cha-shared-key.texi b/doc/cha-shared-key.texi
index 78c1f36240..8d1b4db4c8 100644
--- a/doc/cha-shared-key.texi
+++ b/doc/cha-shared-key.texi
@@ -6,11 +6,58 @@ used with password, shared-key and anonymous authentication methods.
 The rest of this chapter discusses details of these methods.
 
 @menu
-* SRP authentication::
 * PSK authentication::
+* SRP authentication::
 * Anonymous authentication::
 @end menu
 
+@node PSK authentication
+@subsection PSK authentication
+
+@menu
+* Authentication using PSK::
+* psktool Invocation::             Invoking psktool
+@end menu
+
+@node Authentication using PSK
+@subsubsection Authentication using @acronym{PSK}
+@cindex PSK authentication
+
+Authentication using Pre-shared keys is a method to authenticate using
+usernames and binary keys. This protocol avoids making use of public
+key infrastructure and expensive calculations, thus it is suitable for
+constraint clients. It is available under all TLS protocol versions.
+
+The implementation in @acronym{GnuTLS} is based on @xcite{TLSPSK}.  
+The supported @acronym{PSK} key exchange methods are:
+
+@table @code
+
+@item PSK:
+Authentication using the @acronym{PSK} protocol (no forward secrecy).
+
+@item DHE-PSK:
+Authentication using the @acronym{PSK} protocol and Diffie-Hellman key
+exchange.  This method offers perfect forward secrecy.
+
+@item ECDHE-PSK:
+Authentication using the @acronym{PSK} protocol and Elliptic curve Diffie-Hellman key
+exchange.  This method offers perfect forward secrecy.
+
+@item RSA-PSK:
+Authentication using the @acronym{PSK} protocol for the client and an RSA certificate
+for the server. This is not available under TLS 1.3.
+
+@end table
+
+Helper functions to generate and maintain @acronym{PSK} keys are also included
+in @acronym{GnuTLS}.
+
+@showfuncC{gnutls_key_generate,gnutls_hex_encode,gnutls_hex_decode}
+
+@include invoke-psktool.texi
+
+
 @node SRP authentication
 @subsection SRP authentication
 
@@ -29,7 +76,8 @@ The @acronym{SRP} key exchange is an extension to the
 @acronym{TLS} protocol, and it provides an authenticated with a 
 password key exchange. The peers can be identified using a single password, 
 or there can be combinations where the client is authenticated using @acronym{SRP}
-and the server using a certificate.
+and the server using a certificate. It is only available under TLS 1.2 or earlier
+versions.
 
 The advantage of @acronym{SRP} authentication, over other proposed
 secure password authentication schemes, is that @acronym{SRP} is not
@@ -77,53 +125,6 @@ authenticated using a certificate with RSA parameters.
 
 @include invoke-srptool.texi
 
-@node PSK authentication
-@subsection PSK authentication
-
-@menu
-* Authentication using PSK::
-* psktool Invocation::             Invoking psktool
-@end menu
-
-@node Authentication using PSK
-@subsubsection Authentication using @acronym{PSK}
-@cindex PSK authentication
-
-Authentication using Pre-shared keys is a method to authenticate using
-usernames and binary keys. This protocol avoids making use of public
-key infrastructure and expensive calculations, thus it is suitable for
-constraint clients.
-
-The implementation in @acronym{GnuTLS} is based on @xcite{TLSPSK}.  
-The supported @acronym{PSK} key exchange methods are:
-
-@table @code
-
-@item PSK:
-Authentication using the @acronym{PSK} protocol.
-
-@item DHE-PSK:
-Authentication using the @acronym{PSK} protocol and Diffie-Hellman key
-exchange.  This method offers perfect forward secrecy.
-
-@item ECDHE-PSK:
-Authentication using the @acronym{PSK} protocol and Elliptic curve Diffie-Hellman key
-exchange.  This method offers perfect forward secrecy.
-
-@item RSA-PSK:
-Authentication using the @acronym{PSK} protocol for the client and an RSA certificate
-for the server.
-
-@end table
-
-
-Helper functions to generate and maintain @acronym{PSK} keys are also included
-in @acronym{GnuTLS}.
-
-@showfuncC{gnutls_key_generate,gnutls_hex_encode,gnutls_hex_decode}
-
-@include invoke-psktool.texi
-
 @node Anonymous authentication
 @subsection Anonymous authentication
 @cindex anonymous authentication
@@ -134,7 +135,8 @@ is vulnerable to a man in the middle attack, but can be
 used even if there is no prior communication or shared trusted parties 
 with the peer. It is useful to establish a session over which certificate
 authentication will occur in order to hide the indentities of the participants
-from passive eavesdroppers.
+from passive eavesdroppers. It is only available under TLS 1.2 or earlier
+versions.
 
 Unless in the above case, it is not recommended to use anonymous authentication. 
 In the cases where there is no prior communication with the peers,