Add client-side session caching

Add support for client-side caching.
Uses an application defined "cache_id" to identify a connection.
This cache_id may be an IP address, DNS name or anything else the
client wishes to use.

Author: tmshort

crypto/err/openssl.txt

@@ -1346,6 +1346,7 @@ SSL_R_ATTEMPT_TO_REUSE_SESSION_IN_DIFFERENT_CONTEXT:272:\
 	attempt to reuse session in different context
 SSL_R_AT_LEAST_TLS_1_2_NEEDED_IN_SUITEB_MODE:158:\
 	at least (D)TLS 1.2 needed in Suite B mode
+SSL_R_BAD_CACHE_MODE:424:bad cache mode
 SSL_R_BAD_CERTIFICATE:348:bad certificate
 SSL_R_BAD_CHANGE_CIPHER_SPEC:103:bad change cipher spec
 SSL_R_BAD_CIPHER:186:bad cipher
@@ -1517,6 +1518,7 @@ SSL_R_NOT_ON_RECORD_BOUNDARY:182:not on record boundary
 SSL_R_NOT_REPLACING_CERTIFICATE:289:not replacing certificate
 SSL_R_NOT_SERVER:284:not server
 SSL_R_NO_APPLICATION_PROTOCOL:235:no application protocol
+SSL_R_NO_CACHE_ID_ON_SERVER:425:no cache id on server
 SSL_R_NO_CERTIFICATES_RETURNED:176:no certificates returned
 SSL_R_NO_CERTIFICATE_ASSIGNED:177:no certificate assigned
 SSL_R_NO_CERTIFICATE_SET:179:no certificate set
@@ -1590,6 +1592,8 @@ SSL_R_SCSV_RECEIVED_WHEN_RENEGOTIATING:345:scsv received when renegotiating
 SSL_R_SCT_VERIFICATION_FAILED:208:sct verification failed
 SSL_R_SEQUENCE_CTR_WRAPPED:327:sequence ctr wrapped
 SSL_R_SERVERHELLO_TLSEXT:275:serverhello tlsext
+SSL_R_SESSION_ALREADY_IN_CACHE:426:session already in cache
+SSL_R_SESSION_ALREADY_SET:427:session already set
 SSL_R_SESSION_ID_CONTEXT_UNINITIALIZED:277:session id context uninitialized
 SSL_R_SHUTDOWN_WHILE_IN_INIT:407:shutdown while in init
 SSL_R_SIGNATURE_ALGORITHMS_ERROR:360:signature algorithms error

crypto/ssl_err.c

@@ -23,6 +23,7 @@ static const ERR_STRING_DATA SSL_str_reasons[] = {
      "attempt to reuse session in different context"},
     {ERR_PACK(ERR_LIB_SSL, 0, SSL_R_AT_LEAST_TLS_1_2_NEEDED_IN_SUITEB_MODE),
      "at least (D)TLS 1.2 needed in Suite B mode"},
+    {ERR_PACK(ERR_LIB_SSL, 0, SSL_R_BAD_CACHE_MODE), "bad cache mode"},
     {ERR_PACK(ERR_LIB_SSL, 0, SSL_R_BAD_CERTIFICATE), "bad certificate"},
     {ERR_PACK(ERR_LIB_SSL, 0, SSL_R_BAD_CHANGE_CIPHER_SPEC),
      "bad change cipher spec"},
@@ -292,6 +293,8 @@ static const ERR_STRING_DATA SSL_str_reasons[] = {
     {ERR_PACK(ERR_LIB_SSL, 0, SSL_R_NOT_SERVER), "not server"},
     {ERR_PACK(ERR_LIB_SSL, 0, SSL_R_NO_APPLICATION_PROTOCOL),
      "no application protocol"},
+    {ERR_PACK(ERR_LIB_SSL, 0, SSL_R_NO_CACHE_ID_ON_SERVER),
+     "no cache id on server"},
     {ERR_PACK(ERR_LIB_SSL, 0, SSL_R_NO_CERTIFICATES_RETURNED),
      "no certificates returned"},
     {ERR_PACK(ERR_LIB_SSL, 0, SSL_R_NO_CERTIFICATE_ASSIGNED),
@@ -407,6 +410,10 @@ static const ERR_STRING_DATA SSL_str_reasons[] = {
     {ERR_PACK(ERR_LIB_SSL, 0, SSL_R_SEQUENCE_CTR_WRAPPED),
      "sequence ctr wrapped"},
     {ERR_PACK(ERR_LIB_SSL, 0, SSL_R_SERVERHELLO_TLSEXT), "serverhello tlsext"},
+    {ERR_PACK(ERR_LIB_SSL, 0, SSL_R_SESSION_ALREADY_IN_CACHE),
+     "session already in cache"},
+    {ERR_PACK(ERR_LIB_SSL, 0, SSL_R_SESSION_ALREADY_SET),
+     "session already set"},
     {ERR_PACK(ERR_LIB_SSL, 0, SSL_R_SESSION_ID_CONTEXT_UNINITIALIZED),
      "session id context uninitialized"},
     {ERR_PACK(ERR_LIB_SSL, 0, SSL_R_SHUTDOWN_WHILE_IN_INIT),

doc/build.info

@@ -2775,6 +2775,10 @@ DEPEND[html/man3/SSL_session_reused.html]=man3/SSL_session_reused.pod
 GENERATE[html/man3/SSL_session_reused.html]=man3/SSL_session_reused.pod
 DEPEND[man/man3/SSL_session_reused.3]=man3/SSL_session_reused.pod
 GENERATE[man/man3/SSL_session_reused.3]=man3/SSL_session_reused.pod
+DEPEND[html/man3/SSL_set1_cache_id.html]=man3/SSL_set1_cache_id.pod
+GENERATE[html/man3/SSL_set1_cache_id.html]=man3/SSL_set1_cache_id.pod
+DEPEND[man/man3/SSL_set1_cache_id.3]=man3/SSL_set1_cache_id.pod
+GENERATE[man/man3/SSL_set1_cache_id.3]=man3/SSL_set1_cache_id.pod
 DEPEND[html/man3/SSL_set1_host.html]=man3/SSL_set1_host.pod
 GENERATE[html/man3/SSL_set1_host.html]=man3/SSL_set1_host.pod
 DEPEND[man/man3/SSL_set1_host.3]=man3/SSL_set1_host.pod
@@ -3739,6 +3743,7 @@ html/man3/SSL_read.html \
 html/man3/SSL_read_early_data.html \
 html/man3/SSL_rstate_string.html \
 html/man3/SSL_session_reused.html \
+html/man3/SSL_set1_cache_id.html \
 html/man3/SSL_set1_host.html \
 html/man3/SSL_set1_initial_peer_addr.html \
 html/man3/SSL_set1_server_cert_type.html \
@@ -4411,6 +4416,7 @@ man/man3/SSL_read.3 \
 man/man3/SSL_read_early_data.3 \
 man/man3/SSL_rstate_string.3 \
 man/man3/SSL_session_reused.3 \
+man/man3/SSL_set1_cache_id.3 \
 man/man3/SSL_set1_host.3 \
 man/man3/SSL_set1_initial_peer_addr.3 \
 man/man3/SSL_set1_server_cert_type.3 \

doc/man3/SSL_CTX_sess_set_get_cb.pod

@@ -14,9 +14,9 @@ SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb, SSL_CTX_sess_set_get_cb, SS
                                  void (*remove_session_cb)(SSL_CTX *ctx,
                                                            SSL_SESSION *));
  void SSL_CTX_sess_set_get_cb(SSL_CTX *ctx,
-                              SSL_SESSION (*get_session_cb)(SSL *,
-                                                            const unsigned char *,
-                                                            int, int *));
+                              SSL_SESSION (*get_session_cb)(SSL *ssl,
+                                                            const unsigned char *data,
+                                                            int len, int *copy));
 
  int (*SSL_CTX_sess_get_new_cb(SSL_CTX *ctx))(struct ssl_st *ssl,
                                               SSL_SESSION *sess);
@@ -86,7 +86,7 @@ for all sessions in the internal session cache when
 L<SSL_CTX_free(3)> is called. The remove_session_cb() is passed
 the B<ctx> and the ssl session B<sess>. It does not provide any feedback.
 
-The get_session_cb() is only called on SSL/TLS servers, and is given
+The get_session_cb() is called on SSL/TLS servers, and is given
 the session id
 proposed by the client. The get_session_cb() is always called, even when
 session caching was disabled. The get_session_cb() is passed the
@@ -98,6 +98,16 @@ If the get_session_cb() does not write to B<copy>, the reference count
 is incremented and the session must be explicitly freed with
 L<SSL_SESSION_free(3)>.
 
+The get_session_cb() is called on SSL/TLS clients with the application-defined
+cache identifier set by the client. The get_session_cb() is always called when
+session caching is disabled. The get_session_cb() is passed the
+B<ssl> connection, the cache identifier of length B<length> at the memory location
+B<data>. With the parameter B<copy> the callback can require the
+library to increment the reference count of the SSL_SESSION object,
+Normally the reference count is not incremented and therefore the
+session must not be explicitly freed with
+L<SSL_SESSION_free(3)>.
+
 =head1 RETURN VALUES
 
 SSL_CTX_sess_get_new_cb(), SSL_CTX_sess_get_remove_cb() and SSL_CTX_sess_get_get_cb()
@@ -109,11 +119,13 @@ L<ssl(7)>, L<d2i_SSL_SESSION(3)>,
 L<SSL_CTX_set_session_cache_mode(3)>,
 L<SSL_CTX_flush_sessions(3)>,
 L<SSL_SESSION_free(3)>,
-L<SSL_CTX_free(3)>
+L<SSL_CTX_free(3)>,
+L<SSL_get1_previous_client_session(3)>,
+L<SSL_set1_cache_id(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2001-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-2025 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy

doc/man3/SSL_CTX_set_session_cache_mode.pod

@@ -49,12 +49,16 @@ No session caching for client or server takes place.
 
 =item SSL_SESS_CACHE_CLIENT
 
-Client sessions are added to the session cache. As there is no reliable way
-for the OpenSSL library to know whether a session should be reused or which
-session to choose (due to the abstract BIO layer the SSL engine does not
-have details about the connection), the application must select the session
-to be reused by using the L<SSL_set_session(3)>
-function. This option is not activated by default.
+Client sessions are added to the session cache. Sessions are identified by their
+cache identifier set via L<SSL_set1_cache_id(3)> when they are created by an SSL.
+This cache identifier must be set before calling L<SSL_connect(3)>.
+
+The application then can retrieve prior sessions via L<SSL_get1_previous_client_session(3)>.
+After the session has been retrieved, it may be examined to determine whether
+it can (or should) be used. The session must then be applied to the SSL object via the
+L<SSL_set_session(3)> before it can be used during L<SSL_connect(3)>.
+
+This option is not activated by default.
 
 =item SSL_SESS_CACHE_SERVER
 
@@ -64,10 +68,19 @@ the internal session cache (unless SSL_SESS_CACHE_NO_INTERNAL_LOOKUP is set),
 then (second) in the external cache if available. If the session is found, the
 server will try to reuse the session.  This is the default.
 
+Servers must not use L<SSL_set1_cache_id(3)>, otherwise, the session will not be
+found in the cache.
+
 =item SSL_SESS_CACHE_BOTH
 
 Enable both SSL_SESS_CACHE_CLIENT and SSL_SESS_CACHE_SERVER at the same time.
 
+Servers must not use L<SSL_set1_cache_id(3)>, otherwise, the session will not be
+found in the cache.
+
+Clients must use L<SSL_set1_cache_id(3)> in order for sessions to be found in the cache
+via L<SSL_get1_previous_client_session(3)>.
+
 =item SSL_SESS_CACHE_NO_AUTO_CLEAR
 
 Normally the session cache is checked for expired sessions every
@@ -121,22 +134,25 @@ SSL_CTX_set_session_cache_mode() returns the previously set cache mode.
 
 SSL_CTX_get_session_cache_mode() returns the currently set cache mode.
 
-
 =head1 SEE ALSO
 
 L<ssl(7)>, L<SSL_set_session(3)>,
 L<SSL_session_reused(3)>,
+L<SSL_get0_cache_id(3)>,
+L<SSL_set1_cache_id(3)>,
+L<SSL_get1_previous_client_session(3)>,
 L<SSL_CTX_add_session(3)>,
 L<SSL_CTX_sess_number(3)>,
 L<SSL_CTX_sess_set_cache_size(3)>,
 L<SSL_CTX_sess_set_get_cb(3)>,
 L<SSL_CTX_set_session_id_context(3)>,
 L<SSL_CTX_set_timeout(3)>,
-L<SSL_CTX_flush_sessions(3)>
+L<SSL_CTX_flush_sessions(3)>,
+L<SSL_connect(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2001-2021 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-2025 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy

doc/man3/SSL_CTX_set_session_id_context.pod

@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-SSL_CTX_set_session_id_context, SSL_set_session_id_context - set context within which session can be reused (server side only)
+SSL_CTX_set_session_id_context, SSL_set_session_id_context
+- set context within which session can be reused (server side only)
 
 =head1 SYNOPSIS
 
@@ -82,7 +83,7 @@ L<ssl(7)>
 
 =head1 COPYRIGHT
 
-Copyright 2001-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-2025 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy

doc/man3/SSL_get_verify_result.pod

@@ -2,25 +2,30 @@
 
 =head1 NAME
 
-SSL_get_verify_result - get result of peer certificate verification
+SSL_get_verify_result,
+SSL_SESSION_get_verify_result
+- get result of peer certificate verification
 
 =head1 SYNOPSIS
 
  #include <openssl/ssl.h>
 
  long SSL_get_verify_result(const SSL *ssl);
+ long SSL_SESSION_get_verify_result(const SSL_SESSION *ss);
 
 =head1 DESCRIPTION
 
-SSL_get_verify_result() returns the result of the verification of the
-X509 certificate presented by the peer, if any. I<ssl> B<MUST NOT> be NULL.
+SSL_get_verify_result() and SSL_SESSION_get_verify_result() return the
+result of the verification of the X509 certificate presented by the peer,
+if any. I<ssl> B<MUST NOT> be NULL.
 
 =head1 NOTES
 
-SSL_get_verify_result() can only return one error code while the verification
+SSL_get_verify_result() and SSL_SESSION_get_verify_result() can only return
+one error code while the verification
 of a certificate can fail because of many reasons at the same time. Only
 the last verification error that occurred during the processing is available
-from SSL_get_verify_result().
+from SSL_get_verify_result() or SSL_SESSION_get_verify_result().
 
 Sometimes there can be a sequence of errors leading to the verification
 failure as reported by SSL_get_verify_result().
@@ -61,9 +66,13 @@ L<ssl(7)>, L<SSL_set_verify_result(3)>,
 L<SSL_get_peer_certificate(3)>,
 L<openssl-verify(1)>
 
+=head1 HISTORY
+
+The SSL_SESSION_get_verify_result() function was added in OpenSSL 3.5.
+
 =head1 COPYRIGHT
 
-Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2025 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy

doc/man3/SSL_set1_cache_id.pod

@@ -0,0 +1,114 @@
+=pod
+
+=head1 NAME
+
+SSL_set1_cache_id,
+SSL_get0_cache_id,
+SSL_SESSION_set1_cache_id,
+SSL_SESSION_get0_cache_id,
+SSL_get1_previous_client_session - use application-defined cache identifier for session caching
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_set1_cache_id(SSL *s, const unsigned char *data, size_t len);
+ int SSL_get0_cache_id(const SSL *s, const unsigned char **data, size_t *len);
+
+ int SSL_SESSION_set1_cache_id(SSL_SESSION *ss, const unsigned char *data, size_t len);
+ int SSL_SESSION_get0_cache_id(const SSL_SESSION *ss, const unsigned char **data, size_t *len);
+
+ int SSL_get1_previous_client_session(SSL *s, int flags);
+
+=head1 DESCRIPTION
+
+SSL_set1_cache_id() sets the cache identifier specified by B<data> and B<len>
+into B<s>. This cache identifier is application-defined, and can be a domain
+name, IP address, port or other identifier.
+
+SSL_get0_cache_id() returns the cache identifier of B<s> into the B<data> and
+B<len> variables. The cache identifier is application-defined.
+
+SSL_SESSION_set1_cache_id() sets the cache identifier specified by B<data> and B<len>
+into B<ss>. This cache identifier is application-defined.
+
+SSL_SESSION_get0_cache_id() returns the cache identifier of B<ss> into the B<data> and
+B<len> variables. The cache identifier is application-defined.
+
+SSL_get1_previous_client_session() is used to search for and return a
+SSL_SESSION in the session cache. A cache identifier must first be set
+via SSL_set1_cache_id().
+
+=head1 NOTES
+
+The OpenSSL library can store/retrieve SSL/TLS sessions for later reuse.
+The sessions can be held in memory for each B<ctx>; if more than one
+SSL_CTX object is being maintained, the sessions are unique for each SSL_CTX
+object. The cache mode must be set to SSL_SESS_CACHE_CLIENT via
+L<SSL_CTX_set_session_cache_mode(3)> in order to use application-defined
+cache identifiers. When the cache mode is set to SSL_SESSION_CACHE_SERVER or
+SSL_SESSION_CACHE_BOTH, session IDs are used as the cache identifier.
+
+To reuse a client session, use the SSL_set1_cache_id() function to specify the
+cache identifier of the server that the client is attempting to connect to. Set the
+optional session ID context via L<SSL_CTX_set_session_id_context(3)> or
+L<SSL_set_session_id_context(3)> before calling SSL_get1_previous_client_session().
+
+After the session has been retrieved, it may be examined to determine whether
+it can (or should) be used. The session must then be applied to the SSL object via the
+L<SSL_set_session(3)> before it can be used during L<SSL_connect(3)>.
+
+The session cache that is searched is specified by the SSL_CTX used in
+L<SSL_new(3)>. The SSL_CTX set via L<SSL_set_SSL_CTX(3)> is not used
+for the session cache.
+
+SSL_SESSION_set1_cache_id() will fail if the B<ss> is already in a cache. This
+function can only be used on non-cached SSL_SESSIONs.
+
+SSL_set1_cache_id() and SSL_SESSION_set1_cache_id() should not be used by servers.
+
+=head1 RETURN VALUES
+
+The SSL_set1_cache_id(), SSL_get0_cache_id(), SSL_SESSION_set1_cache_id() and
+SSL_SESSION_get0_cache_id() functions return 1 on success, 0 on failure.
+
+The SSL_get0_cache_id() function fills in the B<data> and B<len> parameters
+with the data from the B<s>.
+
+The SSL_get_previous_client_session() returns an SSL_SESSION on success, or NULL on
+failure. The error stack should be checked on error.
+
+=head1 SEE ALSO
+
+L<SSL_set_session(3)>
+L<SSL_session_reused(3)>
+L<SSL_CTX_add_session(3)>
+L<SSL_CTX_sess_number(3)>
+L<SSL_CTX_sess_set_cache_size(3)>
+L<SSL_CTX_sess_set_get_cb(3)>
+L<SSL_CTX_set_session_id_context(3)>
+L<SSL_CTX_set_timeout(3)>
+L<SSL_CTX_flush_sessions(3)>
+L<SSL_CTX_set_session_cache_mode(3)>,
+L<SSL_connect(3)>,
+L<SSL_new(3)>,
+L<SSL_set_SSL_CTX(3)>,
+
+=head1 HISTORY
+
+The SSL_set1_cache_id(),
+SSL_get0_cache_id(),
+SSL_SESSION_set1_cache_id(),
+SSL_SESSION_get0_cache_id(), and
+SSL_get1_previous_client_session() functions were added in OpenSSL 3.5.
+
+=head1 COPYRIGHT
+
+Copyright 2000-2025 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut