From: Matt Caswell Date: Mon, 13 Apr 2026 13:27:58 +0000 (+0100) Subject: Clarify the set_session_id_context functions X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=91ce06e984d7621a07c48e0618fac1b64c9e80d8;p=thirdparty%2Fopenssl.git Clarify the set_session_id_context functions Clarify when they can be used, and introduce some warnings about using them too late in the handshake. In particular using them in the server name callback is too late. Reviewed-by: Dmitry Belyavskiy Reviewed-by: Tomas Mraz MergeDate: Thu Apr 16 16:46:26 2026 (Merged from https://github.com/openssl/openssl/pull/30797) --- diff --git a/doc/man3/SSL_CTX_set_session_id_context.pod b/doc/man3/SSL_CTX_set_session_id_context.pod index c9572bd0d83..a2a588d36b3 100644 --- a/doc/man3/SSL_CTX_set_session_id_context.pod +++ b/doc/man3/SSL_CTX_set_session_id_context.pod @@ -38,9 +38,6 @@ is set by the SSL/TLS server. The SSL_CTX_set_session_id_context() and SSL_set_session_id_context() functions are therefore only useful on the server side. -OpenSSL clients will check the session id context returned by the server -when reusing a session. - The maximum length of the B is limited to B. @@ -51,11 +48,24 @@ certificates are used, stored sessions will not be reused but a fatal error will be flagged and the handshake will fail. -If a server returns a different session id context to an OpenSSL client -when reusing a session, an error will be flagged and the handshake will -fail. OpenSSL servers will always return the correct session id context, -as an OpenSSL server checks the session id context itself before reusing -a session as described above. +If a client attempts to resume a session and the server detects that the session +id context associated with the session is different to the current session id +context then the resumption will fail. The handshake will continue normally but +no resumption will occur. + +It is vital that the session id context is set before any session resumption +occurs. Sessions get created early in the handshake. If the session id context +is not set by the time the session gets created then the session will be +associated with an empty session id context. The already created session will +not get updated if the session id context is later set. In particular the +callback set via the L function will +be invoked after the session gets created, so if the session id context is set +in the callback then this will be too late for the current handshake and the +session id context setting will be ignored with respect to resumption. Typically +the session id context should be set before the TLS handshake starts, but it may +occur as late as in the callback set via the L +function. + =head1 RETURN VALUES diff --git a/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod b/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod index 654d182e5e2..03d7cb860cf 100644 --- a/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod +++ b/doc/man3/SSL_CTX_set_tlsext_servername_callback.pod @@ -29,7 +29,11 @@ still necessary in order to acknowledge the servername requested by the client. SSL_CTX_set_tlsext_servername_callback() sets the application callback B used by a server to perform any actions or configuration required based on the servername extension received in the incoming connection. When B -is NULL, SNI is not used. +is NULL, SNI is not used. Note that this callback occurs late in the processing +of the ClientHello message. In particular it happens after session resumption +has occurred, and so typically this callback should not call functions such +as L since it is too late to affect the session +resumption for the current handshake. The servername callback should return one of the following values: