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 <beldmit@gmail.com>
Reviewed-by: Tomas Mraz <tomas@openssl.foundation>
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 c9572bd0d83f2166a2d4528c4897d819a4248b69..a2a588d36b3c061418f6dcd2ee7c8b868d4fc4de 100644 (file)
--- 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<sid_ctx> is limited to
 B<SSL_MAX_SID_CTX_LENGTH>.
 
@@ -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<SSL_CTX_set_tlsext_servername_callback(3)> 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<SSL_CTX_set_client_hello_cb(3)>
+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 654d182e5e22cf521576b8f1f7efacdde0cf7966..03d7cb860cf789fcfaf0d7fee0a1ed5bd067c0d8 100644 (file)
--- 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<cb>
 used by a server to perform any actions or configuration required based on
 the servername extension received in the incoming connection. When B<cb>
-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<SSL_set_session_id_context(3)> since it is too late to affect the session
+resumption for the current handshake.
 
 The servername callback should return one of the following values: