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-2022 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_cacheid(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-2022 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,9 @@
 
 =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,
+SSL_CTX_get0_session_id_context, SSL_get0_session_id_context
+- set context within which session can be reused (server side only)
 
 =head1 SYNOPSIS
 
@@ -13,6 +15,13 @@ SSL_CTX_set_session_id_context, SSL_set_session_id_context - set context within
  int SSL_set_session_id_context(SSL *ssl, const unsigned char *sid_ctx,
                                 unsigned int sid_ctx_len);
 
+ int SSL_CTX_get0_session_id_context(const SSL_CTX *ctx,
+                                     const unsigned char **sid_ctx,
+                                     size_t *sid_ctx_len);
+ int SSL_get0_session_id_context(const SSL *ssl,
+                                 const unsigned char **sid_ctx,
+                                 size_t *sid_ctx_len);
+
 =head1 DESCRIPTION
 
 SSL_CTX_set_session_id_context() sets the context B<sid_ctx> of length
@@ -21,6 +30,12 @@ B<sid_ctx_len> within which a session can be reused for the B<ctx> object.
 SSL_set_session_id_context() sets the context B<sid_ctx> of length
 B<sid_ctx_len> within which a session can be reused for the B<ssl> object.
 
+SSL_CTX_get0_session_id_context() retrieves the context into B<sid_ctx>
+and the length into B<sid_ctx_len>.
+
+SSL_get0_session_id_context() retrieves the context into B<sid_ctx>
+and the length into B<sid_ctx_len>.
+
 =head1 NOTES
 
 Sessions are generated within a certain context. When exporting/importing
@@ -59,6 +74,10 @@ a session as described above.
 
 =head1 RETURN VALUES
 
+SSL_CTX_get0_session_id_context() and SSL_get0_session_id_context()
+return 1 on success and 0 on failure. The B<sid_ctx> and B<sid_ctx_len>
+values are filled in and may be NULL and 0 respectively.
+
 SSL_CTX_set_session_id_context() and SSL_set_session_id_context()
 return the following values:
 
@@ -82,7 +101,7 @@ L<ssl(7)>
 
 =head1 COPYRIGHT
 
-Copyright 2001-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-2022 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_SESSION_get_time.pod

@@ -4,8 +4,7 @@
 
 SSL_SESSION_get_time, SSL_SESSION_set_time, SSL_SESSION_get_timeout,
 SSL_SESSION_set_timeout, SSL_SESSION_get_time_ex, SSL_SESSION_set_time_ex,
-SSL_get_time, SSL_set_time, SSL_get_timeout, SSL_set_timeout
-- retrieve and manipulate session time and timeout settings
+SSL_get_time, SSL_set_time, SSL_get_timeout, SSL_set_timeout,
 
 =head1 SYNOPSIS
 

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().