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_set1_cache_id.pod

@@ -0,0 +1,115 @@
+=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,
+the functions will fail.
+
+=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

include/openssl/ssl.h.in

@@ -1823,6 +1823,7 @@ int SSL_up_ref(SSL *s);
 int SSL_is_dtls(const SSL *s);
 int SSL_is_tls(const SSL *s);
 int SSL_is_quic(const SSL *s);
+
 __owur int SSL_set_session_id_context(SSL *ssl, const unsigned char *sid_ctx,
                                       unsigned int sid_ctx_len);
 
@@ -2822,7 +2823,6 @@ typedef unsigned int (*DTLS_timer_cb)(SSL *s, unsigned int timer_us);
 
 void DTLS_set_timer_cb(SSL *s, DTLS_timer_cb cb);
 
-
 typedef int (*SSL_allow_early_data_cb_fn)(SSL *s, void *arg);
 void SSL_CTX_set_allow_early_data_cb(SSL_CTX *ctx,
                                      SSL_allow_early_data_cb_fn cb,
@@ -2880,6 +2880,14 @@ int SSL_set_quic_tls_transport_params(SSL *s,
 
 int SSL_set_quic_tls_early_data_enabled(SSL *s, int enabled);
 
+/* Client cache implementation */
+__owur SSL_SESSION *SSL_get1_previous_client_session(SSL *s);
+__owur int SSL_set1_cache_id(SSL *s, const unsigned char *data, size_t len);
+__owur int SSL_get0_cache_id(const SSL *s, const unsigned char **data, size_t *len);
+__owur int SSL_SESSION_set1_cache_id(SSL_SESSION *ss, const unsigned char *data, size_t len);
+__owur int SSL_SESSION_get0_cache_id(const SSL_SESSION *ss, const unsigned char **data,
+                                     size_t *len);
+
 # ifdef  __cplusplus
 }
 # endif

include/openssl/sslerr.h

@@ -25,6 +25,7 @@
 # define SSL_R_APP_DATA_IN_HANDSHAKE                      100
 # define SSL_R_ATTEMPT_TO_REUSE_SESSION_IN_DIFFERENT_CONTEXT 272
 # define SSL_R_AT_LEAST_TLS_1_2_NEEDED_IN_SUITEB_MODE     158
+# define SSL_R_BAD_CACHE_MODE                             424
 # define SSL_R_BAD_CERTIFICATE                            348
 # define SSL_R_BAD_CHANGE_CIPHER_SPEC                     103
 # define SSL_R_BAD_CIPHER                                 186
@@ -190,6 +191,7 @@
 # define SSL_R_NOT_REPLACING_CERTIFICATE                  289
 # define SSL_R_NOT_SERVER                                 284
 # define SSL_R_NO_APPLICATION_PROTOCOL                    235
+# define SSL_R_NO_CACHE_ID_ON_SERVER                      425
 # define SSL_R_NO_CERTIFICATES_RETURNED                   176
 # define SSL_R_NO_CERTIFICATE_ASSIGNED                    177
 # define SSL_R_NO_CERTIFICATE_SET                         179
@@ -260,6 +262,8 @@
 # define SSL_R_SCT_VERIFICATION_FAILED                    208
 # define SSL_R_SEQUENCE_CTR_WRAPPED                       327
 # define SSL_R_SERVERHELLO_TLSEXT                         275
+# define SSL_R_SESSION_ALREADY_IN_CACHE                   426
+# define SSL_R_SESSION_ALREADY_SET                        427
 # define SSL_R_SESSION_ID_CONTEXT_UNINITIALIZED           277
 # define SSL_R_SHUTDOWN_WHILE_IN_INIT                     407
 # define SSL_R_SIGNATURE_ALGORITHMS_ERROR                 360