From 41145c35bfee8f2b0822288fcb23a807d06d8e89 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Fri, 22 Jun 2018 15:05:27 +0100 Subject: [PATCH] Document changes to SSL_OP_NO_TICKET for TLSv1.3 Reviewed-by: Rich Salz Reviewed-by: Viktor Dukhovni (Merged from https://github.com/openssl/openssl/pull/6563) --- doc/man3/SSL_CTX_set_options.pod | 40 ++++++++++++++++++++++++++------ doc/man3/SSL_read_early_data.pod | 14 ++++++----- 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 552de07f8a..f04de32f6c 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 or +L. =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 bc5bd0a084..6a76ec2923 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). 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). When replay protection is +being used the server will operate as if the SSL_OP_NO_TICKET option had been +selected (see L). 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 and similar functions). It is the application's -- 2.25.1