ssl_sess.c: deprecate SSL_CTX_flush_sessions in favour of _ex() replacement

The original function is using long for time and is therefore
not Y2038-safe.

Signed-off-by: Alexander Kanavin <alex@linutronix.de>

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/24307)

6 files changed, 33 insertions, 12 deletions

diff --git a/doc/man3/SSL_CTX_flush_sessions.pod b/doc/man3/SSL_CTX_flush_sessions.pod
index 2ab7c88382..9558e4389c 100644
--- a/doc/man3/SSL_CTX_flush_sessions.pod
+++ b/doc/man3/SSL_CTX_flush_sessions.pod
@@ -2,19 +2,28 @@
 
 =head1 NAME
 
-SSL_CTX_flush_sessions - remove expired sessions
+SSL_CTX_flush_sessions_ex, SSL_CTX_flush_sessions - remove expired sessions
 
 =head1 SYNOPSIS
 
  #include <openssl/ssl.h>
 
+ void SSL_CTX_flush_sessions_ex(SSL_CTX *ctx, time_t tm);
+
+The following functions have been deprecated since OpenSSL 3.4, and can be
+hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
+see L<openssl_user_macros(7)>:
+
  void SSL_CTX_flush_sessions(SSL_CTX *ctx, long tm);
 
 =head1 DESCRIPTION
 
-SSL_CTX_flush_sessions() causes a run through the session cache of
+SSL_CTX_flush_sessions_ex() causes a run through the session cache of
 B<ctx> to remove sessions expired at time B<tm>.
 
+SSL_CTX_flush_sessions() is an older variant of the function that is not
+Y2038 safe due to usage of long datatype instead of time_t.
+
 =head1 NOTES
 
 If enabled, the internal session cache will collect all sessions established
@@ -23,20 +32,20 @@ As sessions will not be reused ones they are expired, they should be
 removed from the cache to save resources. This can either be done
 automatically whenever 255 new sessions were established (see
 L<SSL_CTX_set_session_cache_mode(3)>)
-or manually by calling SSL_CTX_flush_sessions().
+or manually by calling SSL_CTX_flush_sessions_ex().
 
 The parameter B<tm> specifies the time which should be used for the
 expiration test, in most cases the actual time given by time(0)
 will be used.
 
-SSL_CTX_flush_sessions() will only check sessions stored in the internal
+SSL_CTX_flush_sessions_ex() will only check sessions stored in the internal
 cache. When a session is found and removed, the remove_session_cb is however
 called to synchronize with the external cache (see
 L<SSL_CTX_sess_set_get_cb(3)>).
 
 =head1 RETURN VALUES
 
-SSL_CTX_flush_sessions() does not return a value.
+SSL_CTX_flush_sessions_ex() does not return a value.
 
 =head1 SEE ALSO
 
diff --git a/include/openssl/ssl.h.in b/include/openssl/ssl.h.in
index 7ffce7fdd3..6ed3ce5ba7 100644
--- a/include/openssl/ssl.h.in
+++ b/include/openssl/ssl.h.in
@@ -1569,7 +1569,11 @@ void SSL_CTX_set1_cert_store(SSL_CTX *, X509_STORE *);
 __owur int SSL_want(const SSL *s);
 __owur int SSL_clear(SSL *s);
 
+#ifndef OPENSSL_NO_DEPRECATED_3_4
+OSSL_DEPRECATEDIN_3_4_FOR("not Y2038-safe, replace with SSL_CTX_flush_sessions_ex()")
 void SSL_CTX_flush_sessions(SSL_CTX *ctx, long tm);
+#endif
+void SSL_CTX_flush_sessions_ex(SSL_CTX *ctx, time_t tm);
 
 __owur const SSL_CIPHER *SSL_get_current_cipher(const SSL *s);
 __owur const SSL_CIPHER *SSL_get_pending_cipher(const SSL *s);
diff --git a/ssl/ssl_lib.c b/ssl/ssl_lib.c
index 6af23612ee..178ccd0734 100644
--- a/ssl/ssl_lib.c
+++ b/ssl/ssl_lib.c
@@ -4151,7 +4151,7 @@ void SSL_CTX_free(SSL_CTX *a)
      * (See ticket [openssl.org #212].)
      */
     if (a->sessions != NULL)
-        SSL_CTX_flush_sessions(a, 0);
+        SSL_CTX_flush_sessions_ex(a, 0);
 
     CRYPTO_free_ex_data(CRYPTO_EX_INDEX_SSL_CTX, a, &a->ex_data);
     lh_SSL_SESSION_free(a->sessions);
@@ -4544,7 +4544,7 @@ void ssl_update_cache(SSL_CONNECTION *s, int mode)
         else
             stat = &s->session_ctx->stats.sess_accept_good;
         if ((ssl_tsan_load(s->session_ctx, stat) & 0xff) == 0xff)
-            SSL_CTX_flush_sessions(s->session_ctx, (unsigned long)time(NULL));
+            SSL_CTX_flush_sessions_ex(s->session_ctx, time(NULL));
     }
 }
 
diff --git a/ssl/ssl_sess.c b/ssl/ssl_sess.c
index e7c5c2a36f..c57d18984c 100644
--- a/ssl/ssl_sess.c
+++ b/ssl/ssl_sess.c
@@ -1183,8 +1183,15 @@ int SSL_set_session_ticket_ext(SSL *s, void *ext_data, int ext_len)
     return 0;
 }
 
+#ifndef OPENSSL_NO_DEPRECATED_3_4
 void SSL_CTX_flush_sessions(SSL_CTX *s, long t)
 {
+    SSL_CTX_flush_sessions_ex(s, (time_t) t);
+}
+#endif
+
+void SSL_CTX_flush_sessions_ex(SSL_CTX *s, time_t t)
+{
     STACK_OF(SSL_SESSION) *sk;
     SSL_SESSION *current;
     unsigned long i;
diff --git a/test/sslapitest.c b/test/sslapitest.c
index ffa8213fe3..8a88558458 100644
--- a/test/sslapitest.c
+++ b/test/sslapitest.c
@@ -9377,21 +9377,21 @@ static int test_session_timeout(int test)
         goto end;
 
     /* This should remove "early" */
-    SSL_CTX_flush_sessions(ctx, now + TIMEOUT - 1);
+    SSL_CTX_flush_sessions_ex(ctx, now + TIMEOUT - 1);
     if (!TEST_ptr_null(early->prev)
         || !TEST_ptr(middle->prev)
         || !TEST_ptr(late->prev))
         goto end;
 
     /* This should remove "middle" */
-    SSL_CTX_flush_sessions(ctx, now + TIMEOUT + 1);
+    SSL_CTX_flush_sessions_ex(ctx, now + TIMEOUT + 1);
     if (!TEST_ptr_null(early->prev)
         || !TEST_ptr_null(middle->prev)
         || !TEST_ptr(late->prev))
         goto end;
 
     /* This should remove "late" */
-    SSL_CTX_flush_sessions(ctx, now + TIMEOUT + 11);
+    SSL_CTX_flush_sessions_ex(ctx, now + TIMEOUT + 11);
     if (!TEST_ptr_null(early->prev)
         || !TEST_ptr_null(middle->prev)
         || !TEST_ptr_null(late->prev))
@@ -9410,7 +9410,7 @@ static int test_session_timeout(int test)
         goto end;
 
     /* This should remove all of them */
-    SSL_CTX_flush_sessions(ctx, 0);
+    SSL_CTX_flush_sessions_ex(ctx, 0);
     if (!TEST_ptr_null(early->prev)
         || !TEST_ptr_null(middle->prev)
         || !TEST_ptr_null(late->prev))
diff --git a/util/libssl.num b/util/libssl.num
index da18be5a62..d7c7ff09b7 100644
--- a/util/libssl.num
+++ b/util/libssl.num
@@ -186,7 +186,7 @@ TLSv1_2_client_method                   186	3_0_0	EXIST::FUNCTION:DEPRECATEDIN_1
 SSL_add_client_CA                       187	3_0_0	EXIST::FUNCTION:
 SSL_CTX_get0_security_ex_data           188	3_0_0	EXIST::FUNCTION:
 SSL_get_ex_data                         189	3_0_0	EXIST::FUNCTION:
-SSL_CTX_flush_sessions                  190	3_0_0	EXIST::FUNCTION:
+SSL_CTX_flush_sessions                  190	3_0_0	EXIST::FUNCTION:DEPRECATEDIN_3_4
 SSL_use_PrivateKey                      191	3_0_0	EXIST::FUNCTION:
 DTLSv1_client_method                    192	3_0_0	EXIST::FUNCTION:DEPRECATEDIN_1_1_0,DTLS1_METHOD
 SSL_CTX_dane_mtype_set                  193	3_0_0	EXIST::FUNCTION:
@@ -583,3 +583,4 @@ SSL_set_value_uint                      583	3_3_0	EXIST::FUNCTION:
 SSL_poll                                584	3_3_0	EXIST::FUNCTION:
 SSL_SESSION_get_time_ex                 585	3_3_0	EXIST::FUNCTION:
 SSL_SESSION_set_time_ex                 586	3_3_0	EXIST::FUNCTION:
+SSL_CTX_flush_sessions_ex               587	3_4_0	EXIST::FUNCTION: