doc: update for TLS 1.3tmp-update-doc-tls13

Signed-off-by: Daiki Ueno <dueno@redhat.com>

3 files changed, 53 insertions, 22 deletions

diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index f6710a0a16..5fe0a327eb 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -1563,8 +1563,8 @@ and SRP authentication.
 * Virtual hosts and credentials::
 * Session resumption::
 * Certificate verification::
-* TLS 1.2 Re-authentication::
-* TLS 1.3 Re-authentication and re-key::
+* TLS 1.2 re-authentication::
+* TLS 1.3 re-authentication and re-key::
 * Parameter generation::
 * Deriving keys for other applications/protocols::
 * Channel Bindings::
@@ -1632,16 +1632,30 @@ int main()
 @cindex resuming sessions
 @cindex session resumption
 
+To reduce time and network traffic spent in a handshake the client can
+request session resumption from a server that previously shared a
+session with the client.
+
+Under TLS 1.2, in order to support resumption a server can either store
+the session security parameters in a local database or use session
+tickets (see @ref{Session tickets}) to delegate storage to the client.
+
+Under TLS 1.3, session resumption is only available through session
+tickets, and multiple tickets could be sent from server to client. That
+provides the following advantages:
+@itemize
+@item When tickets are not re-used the subsequent client sessions cannot be associated with each other by an eavesdropper
+@item On post-handshake authentication the server may send different tickets asynchronously for each identity used by client.
+@end itemize
+
 @subsubheading Client side
 
-To reduce time and roundtrips spent in a handshake the client can   
-request session resumption from a server that previously shared
-a session with the client. For that the client has to retrieve and store
-the session parameters. Before establishing a new session to the same 
-server the parameters must be re-associated with the GnuTLS session
-using @funcref{gnutls_session_set_data}.
+The client has to retrieve and store the session parameters. Before
+establishing a new session to the same server the parameters must be
+re-associated with the GnuTLS session using
+@funcref{gnutls_session_set_data}.
 
-@showfuncC{gnutls_session_get_data2,gnutls_session_get_id2,gnutls_session_set_data}
+@showfuncB{gnutls_session_get_data2,gnutls_session_set_data}
 
 Keep in mind that sessions will be expired after some time, depending
 on the server, and a server may choose not to resume a session
@@ -1651,16 +1665,13 @@ using the priority functions, at least the algorithms used in the last session.
 
 @showfuncdesc{gnutls_session_is_resumed}
 
+@showfuncdesc{gnutls_session_get_id2}
+
 @subsubheading Server side
 
-Under TLS 1.2, in order to support resumption a server can either store
-the session security parameters in a local database or use session
-tickets (see @ref{Session tickets}) to delegate storage to the client.
 A server enabling both session tickets and a storage for session data
 would use session tickets when clients support it and the storage otherwise.
 
-Under TLS1.3 a server can only send session tickets.
-
 A storing server needs to specify callback functions to store, retrieve and delete session data. These can be
 registered with the functions below. The stored sessions in the database can be checked using @funcref{gnutls_db_check_entry}
 for expiration.
@@ -1682,6 +1693,11 @@ if revealed could be used to decrypt all previous sessions.
 The expiration time for session resumption, either in tickets or stored data
 is set using @funcref{gnutls_db_set_cache_expiration}.
 
+Under TLS 1.3, the server can send a new session ticket at any time
+using @funcref{gnutls_session_ticket_send}.
+
+@showfuncdesc{gnutls_session_ticket_send}
+
 @node Certificate verification
 @subsection Certificate verification
 @cindex DANE
@@ -1755,8 +1771,8 @@ you may use danetool (see @ref{danetool Invocation}).
 
 
 
-@node TLS 1.2 Re-authentication
-@subsection TLS 1.2 Re-authentication
+@node TLS 1.2 re-authentication
+@subsection TLS 1.2 re-authentication
 @cindex re-negotiation
 @cindex re-authentication
 
@@ -1803,14 +1819,14 @@ even drop the connection.
 
 @showfuncdesc{gnutls_rehandshake}
 
-@node TLS 1.3 Re-authentication and re-key
-@subsection TLS 1.3 Re-authentication and re-key
+@node TLS 1.3 re-authentication and re-key
+@subsection TLS 1.3 re-authentication and re-key
 @cindex re-key
 @cindex re-negotiation
 @cindex re-authentication
 @cindex post-handshake authentication
 
-The TLS 1.3 protocol distinguishes between between re-key and re-authentication.
+The TLS 1.3 protocol distinguishes between re-key and re-authentication.
 The re-key process ensures that fresh keys are supplied to the already
 negotiated parameters, and on GnuTLS can be initiated using
 @funcref{gnutls_session_key_update}. The re-key process can be one-way
@@ -1825,7 +1841,7 @@ post-handshake authentication can be initiated only by the server using
 Both server and client have to explicitly enable support for post handshake
 authentication using the @code{GNUTLS_POST_HANDSHAKE_AUTH} flag at @funcref{gnutls_init}.
 
-A client receing an re-authentication request will "see" the error code
+A client receiving a re-authentication request will "see" the error code
 @code{GNUTLS_E_REAUTH_REQUEST} at @funcref{gnutls_record_recv}. At this
 point, it should also call @funcref{gnutls_reauth}.
 
diff --git a/doc/cha-library.texi b/doc/cha-library.texi
index 33a98861ed..7fe7fb7297 100644
--- a/doc/cha-library.texi
+++ b/doc/cha-library.texi
@@ -7,7 +7,7 @@ privacy over insecure lines, and were designed to prevent
 eavesdropping, tampering, or message forgery.
 
 Technically @acronym{GnuTLS} is a portable ANSI C based library which
-implements the protocols ranging from SSL 3.0 to TLS 1.2 (see @ref{Introduction to TLS}, 
+implements the protocols ranging from SSL 3.0 to TLS 1.3 (see @ref{Introduction to TLS}, 
 for a detailed description of the protocols), accompanied
 with the required framework for authentication and public key
 infrastructure.  Important features of the @acronym{GnuTLS} library
@@ -15,7 +15,7 @@ include:
 
 @itemize
 
-@item Support for TLS 1.2, TLS 1.1, TLS 1.0 and SSL 3.0 protocols.
+@item Support for TLS 1.3, TLS 1.2, TLS 1.1, TLS 1.0 and SSL 3.0 protocols.
 
 @item Support for Datagram TLS 1.0 and 1.2.
 
diff --git a/doc/cha-upgrade.texi b/doc/cha-upgrade.texi
index a5819cf8dd..3e593dffb7 100644
--- a/doc/cha-upgrade.texi
+++ b/doc/cha-upgrade.texi
@@ -234,4 +234,19 @@ TLS 1.3 is done via session tickets, c.f. @funcref{gnutls_session_ticket_enable_
 milliseconds. Check output of @funcref{gnutls_session_get_flags} for GNUTLS_SFLAGS_SESSION_TICKET
 before calling this function to avoid delays.
 
+@item SRP and RSA-PSK key exchanges are not supported under TLS 1.3
+@tab SRP and RSA-PSK key exchanges are not supported in TLS 1.3, so when these key exchanges are present in a priority string, TLS 1.3 is disabled.
+
+@item Anonymous key exchange is not supported under TLS 1.3
+@tab There is no anonymous key exchange supported under TLS 1.3, so if an anonymous key exchange method is set in a priority string, and no certificate credentials are set in the client or server, TLS 1.3 will not be negotiated.
+
+@item ECDHE-PSK and DHE-PSK keywords have the same meaning under TLS 1.3
+@tab In the priority strings, both @code{ECDHE@-PSK} and @code{DHE@-PSK} indicate the intent to support an ephemeral key exchange with the pre-shared key.  The parameters of the key exchange are negotiated with the supported groups specified in the priority string.
+
+@item Authentication-only ciphersuites are not supported under TLS 1.3
+@tab Ciphersuites with the @code{NULL} cipher (i.e., authentication-only) are not supported in TLS 1.3, so when they are specified in a priority string, TLS 1.3 is disabled.
+
+@item Supplemental data is not supported under TLS 1.3
+@tab The TLS supplemental data handshake message (RFC 4680) is not supported under TLS 1.3, so if the application calls @funcref{gnutls_supplemental_register} or @funcref{gnutls_session_supplemental_register}, TLS 1.3 is disabled.
+
 @end multitable