Document changes to SSL_OP_NO_TICKET for TLSv1.3

Reviewed-by: Rich Salz <rsalz@openssl.org>
Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/6563)

2 files changed, 41 insertions, 13 deletions

diff --git a/doc/man3/SSL_CTX_set_options.pod b/doc/man3/SSL_CTX_set_options.pod
index 552de07..f04de32 100644
--- a/doc/man3/SSL_CTX_set_options.pod
+++ b/doc/man3/SSL_CTX_set_options.pod
@@ -145,13 +145,39 @@ DTLS connections.
 
 =item SSL_OP_NO_TICKET
 
-Normally clients and servers will, where possible, transparently make use
-of RFC4507bis tickets for stateless session resumption.
-
-If this option is set this functionality is disabled and tickets will
-not be used by clients or servers.
-
-This option only applies to TLSv1.2 and below. It is ignored for TLSv1.3.
+SSL/TLS supports two mechanisms for resuming sessions: session ids and stateless
+session tickets.
+
+When using session ids a copy of the session information is
+cached on the server and a unique id is sent to the client. When the client
+wishes to resume it provides the unique id so that the server can retrieve the
+session information from its cache.
+
+When using stateless session tickets the server uses a session ticket encryption
+key to encrypt the session information. This encrypted data is sent to the
+client as a "ticket". When the client wishes to resume it sends the encrypted
+data back to the server. The server uses its key to decrypt the data and resume
+the session. In this way the server can operate statelessly - no session
+information needs to be cached locally.
+
+The TLSv1.3 protocol only supports tickets and does not directly support session
+ids. However OpenSSL allows two modes of ticket operation in TLSv1.3: stateful
+and stateless. Stateless tickets work the same way as in TLSv1.2 and below.
+Stateful tickets mimic the session id behaviour available in TLSv1.2 and below.
+The session information is cached on the server and the session id is wrapped up
+in a ticket and sent back to the client. When the client wishes to resume, it
+presents a ticket in the same way as for stateless tickets. The server can then
+extract the session id from the ticket and retrieve the session information from
+its cache.
+
+By default OpenSSL will use stateless tickets. The SSL_OP_NO_TICKET option will
+cause stateless tickets to not be issued. In TLSv1.2 and below this means no
+ticket gets sent to the client at all. In TLSv1.3 a stateful ticket will be
+sent. This is a server-side option only.
+
+In TLSv1.3 it is possible to suppress all tickets (stateful and stateless) from
+being sent by calling L<SSL_CTX_set_num_tickets(3)> or
+L<SSL_set_num_tickets(3)>.
 
 =item SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION
 
diff --git a/doc/man3/SSL_read_early_data.pod b/doc/man3/SSL_read_early_data.pod
index bc5bd0a..6a76ec2 100644
--- a/doc/man3/SSL_read_early_data.pod
+++ b/doc/man3/SSL_read_early_data.pod
@@ -226,12 +226,14 @@ was submitted will be ignored). Note that single use tickets are enforced even
 if a client does not send any early data.
 
 The replay protection mechanism relies on the internal OpenSSL server session
-cache (see L<SSL_CTX_set_session_cache_mode(3)>). By default sessions will be
-added to the cache whenever a session ticket is issued. When a client attempts
-to resume the session OpenSSL will check for its presence in the internal cache.
-If it exists then the resumption is allowed and the session is removed from the
-cache. If it does not exist then the resumption is not allowed and a full
-handshake will occur.
+cache (see L<SSL_CTX_set_session_cache_mode(3)>). When replay protection is
+being used the server will operate as if the SSL_OP_NO_TICKET option had been
+selected (see L<SSL_CTX_set_options(3)>). Sessions will be added to the cache
+whenever a session ticket is issued. When a client attempts to resume the
+session, OpenSSL will check for its presence in the internal cache. If it exists
+then the resumption is allowed and the session is removed from the cache. If it
+does not exist then the resumption is not allowed and a full handshake will
+occur.
 
 Note that some applications may maintain an external cache of sessions (see
 L<SSL_CTX_sess_set_new_cb(3)> and similar functions). It is the application's