Document changes to SSL_OP_NO_TICKET for TLSv1.3

[openssl.git] / doc / man3 / SSL_CTX_set_options.pod

diff --git a/doc/man3/SSL_CTX_set_options.pod b/doc/man3/SSL_CTX_set_options.pod
index 552de07f8ab0bdad7c7d1f2af5afbeb77b367934..f04de32f6c6e6ffde863fa94146cd0eeda1722e9 100644 (file)
--- 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
 
 
 =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
 
 
 =item SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION