Rename token_store functions to make them consistent

we use get0 to get a token store, but set to set it.  Since the latter
takes a refcount, change that to set1.  Also rename the interal quic
functions to match.

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Saša Nedvědický <sashan@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/26517)

diff --git a/doc/man3/SSL_CTX_get0_token_store.pod b/doc/man3/SSL_CTX_get0_token_store.pod
index f353e0989ddf456737e7744bdf9eac84d97ee5f9..77858d64a7a988eedcd5e409f421d82354b1fc1b 100644 (file)
--- a/doc/man3/SSL_CTX_get0_token_store.pod
+++ b/doc/man3/SSL_CTX_get0_token_store.pod
@@ -2,13 +2,13 @@
 
 =head1 NAME
 
-SSL_CTX_get0_token_store, SSL_CTX_set_token_store
+SSL_CTX_get0_token_store, SSL_CTX_set1_token_store
 - QUIC NEW_TOKEN store manipulation 
 
 =head1 SYNOPSIS
 
  SSL_TOKEN_STORE_HANDLE *SSL_CTX_get0_token_store(SSL_CTX *ctx);
- int SSL_CTX_set_token_store(SSL_CTX *ctx, SSL_TOKEN_STORE_HANDLE *hdl);
+ int SSL_CTX_set1_token_store(SSL_CTX *ctx, SSL_TOKEN_STORE_HANDLE *hdl);
 
 =head1 DESCRIPTION
 The QUIC protocol supports the exchange of opaque tokens which a client can use
@@ -21,9 +21,9 @@ B<SSL_CTX> objects to share those tokens between B<SSL> connections allocated fr
 disparate B<SSL_CTX> objects.
 
 SSL_CTX_get0_token_store() returns an opaque handle to the token store for use
-in a subsequent call to SSL_CTX_set_token_store() on another B<SSL_CTX> object.
+in a subsequent call to SSL_CTX_set1_token_store() on another B<SSL_CTX> object.
 
-SSL_CTX_set_token_store() assigns a token store fetched fom SSL_CTX_get0_token_store
+SSL_CTX_set1_token_store() assigns a token store fetched fom SSL_CTX_get0_token_store
 to a second B<SSL_CTX> object.
 
 =head1 NOTES
@@ -32,7 +32,7 @@ Token stores are internally reference counted.  Note that a call to SSL_CTX_get0
 does not increment the internal reference count.  As such, no freeing of the object
 is needed.
 
-When SSL_CTX_set_token_store() is called, the passed store has its reference count
+When SSL_CTX_set1_token_store() is called, the passed store has its reference count
 incremented.  It will be decremented when that B<SSL_CTX> is freed via a call to
 SSL_CTX_free().
 
@@ -44,7 +44,44 @@ non-QUIC objects will result in error returns.
 SSL_CTX_get0_token_store() returns an opaque handle to a token store, or NULL in
 the event that an error occured, or if the B<SSL_CTX> object has no store.
 
-SSL_CTX_set_token_store returns 1 on success or 0 on error.
+SSL_CTX_set1_token_store returns 1 on success or 0 on error.
+
+=head1 EXAMPLES
+
+The following code snippet shows how to share a token store between separate 
+B<SSL_CTX> objects
+
+    SSL_CTX *ctx1, *ctx2;
+    SSL_TOKEN_CACHE_HANDLE *tc;
+
+    /*
+     * token stores are generally only used for quic client contexts
+     */
+    ctx1 = SSL_CTX_new(libctx, NULL, OSSL_QUIC_client_method());
+    ctx2 = SSL_CTX_new(libctx, NULL, OSSL_QUIC_client_method());
+
+    if (ctx1 == NULL || ctx2 == NULL)
+        goto err;
+    /*
+     * Fetch the token store for ctx1
+     * Note: no reference is taken on the store
+     */
+    tc = SSL_CTX_get0_token_store(ctx1);
+    if (tc == NULL)
+        goto err;
+
+    /*
+     * Assign the token store from ctx1 to ctx2
+     * ctx2 take a reference on the passed store
+     * and begins using it
+     * At this point any NEW_TOKEN frames received
+     * by SSL objects allocated from either CTX are
+     * visible and usable by SSL objects allocated
+     * from the other CTX
+     */
+    if (!SSL_CTX_set1_token_store(ctx2, tc))
+        goto err;
+
 
 =head1 SEE ALSO
 

diff --git a/include/internal/quic_ssl.h b/include/internal/quic_ssl.h
index 95b837da5cbfbfb1fd3320e868385e2c5da149ea..17cac02cc033c6c0f56c37b69e8e1afe43a451b1 100644 (file)
--- a/include/internal/quic_ssl.h
+++ b/include/internal/quic_ssl.h
@@ -28,8 +28,8 @@ __owur SSL *ossl_quic_new_domain(SSL_CTX *ctx, uint64_t flags);
 typedef void QTOK;
 SSL_TOKEN_STORE_HANDLE *ossl_quic_new_token_store(void);
 void ossl_quic_free_token_store(SSL_TOKEN_STORE_HANDLE *hdl);
-SSL_TOKEN_STORE_HANDLE *ossl_quic_get_token_store(SSL_CTX *ctx);
-int ossl_quic_set_token_store(SSL_CTX *ctx, SSL_TOKEN_STORE_HANDLE *hdl);
+SSL_TOKEN_STORE_HANDLE *ossl_quic_get0_token_store(SSL_CTX *ctx);
+int ossl_quic_set1_token_store(SSL_CTX *ctx, SSL_TOKEN_STORE_HANDLE *hdl);
 int ossl_quic_set_peer_token(SSL_CTX *ctx, BIO_ADDR *peer,
                              const uint8_t *token, size_t token_len);
 int ossl_quic_get_peer_token(SSL_CTX *ctx, BIO_ADDR *peer,

diff --git a/include/openssl/ssl.h.in b/include/openssl/ssl.h.in
index 393a3a0fa698ee889191108ea71577aeca5be379..b337ef0f3d24916daa202b66d560f65d59856ceb 100644 (file)
--- a/include/openssl/ssl.h.in
+++ b/include/openssl/ssl.h.in
@@ -2309,7 +2309,7 @@ __owur int SSL_is_connection(SSL *s);
 
 typedef void SSL_TOKEN_STORE_HANDLE;
 __owur SSL_TOKEN_STORE_HANDLE *SSL_CTX_get0_token_store(SSL_CTX *ctx);
-__owur int SSL_CTX_set_token_store(SSL_CTX *ctx, SSL_TOKEN_STORE_HANDLE *hdl);
+__owur int SSL_CTX_set1_token_store(SSL_CTX *ctx, SSL_TOKEN_STORE_HANDLE *hdl);
 
 __owur int SSL_is_listener(SSL *ssl);
 __owur SSL *SSL_get0_listener(SSL *s);

diff --git a/ssl/quic/quic_impl.c b/ssl/quic/quic_impl.c
index 5915c25fa5b9ae876e7957e3bbcdebb924b51e58..b0ad6fdfa7719b88691ba0dd98b347c431e64a19 100644 (file)
--- a/ssl/quic/quic_impl.c
+++ b/ssl/quic/quic_impl.c
@@ -4731,12 +4731,12 @@ void ossl_quic_free_token_store(SSL_TOKEN_STORE_HANDLE *hdl)
     return;
 }
 
-SSL_TOKEN_STORE_HANDLE *ossl_quic_get_token_store(SSL_CTX *ctx)
+SSL_TOKEN_STORE_HANDLE *ossl_quic_get0_token_store(SSL_CTX *ctx)
 {
     return ctx->tokencache;
 }
 
-int ossl_quic_set_token_store(SSL_CTX *ctx, SSL_TOKEN_STORE_HANDLE *hdl)
+int ossl_quic_set1_token_store(SSL_CTX *ctx, SSL_TOKEN_STORE_HANDLE *hdl)
 {
     SSL_TOKEN_STORE *new = hdl;
     SSL_TOKEN_STORE_HANDLE *old = ctx->tokencache;

diff --git a/ssl/ssl_lib.c b/ssl/ssl_lib.c
index 9334af39a5dba8652402ecf070a82c7b6d4650f1..19d274b1b9a45f94cc5272fc27a254b86dada8a7 100644 (file)
--- a/ssl/ssl_lib.c
+++ b/ssl/ssl_lib.c
@@ -7989,16 +7989,16 @@ SSL *SSL_new_from_listener(SSL *ssl, uint64_t flags)
 SSL_TOKEN_STORE_HANDLE *SSL_CTX_get0_token_store(SSL_CTX *ctx)
 {
 #ifndef OPENSSL_NO_QUIC
-    return ossl_quic_get_token_store(ctx);
+    return ossl_quic_get0_token_store(ctx);
 #else
     return NULL;
 #endif
 }
 
-int SSL_CTX_set_token_store(SSL_CTX *ctx, SSL_TOKEN_STORE_HANDLE *hdl)
+int SSL_CTX_set1_token_store(SSL_CTX *ctx, SSL_TOKEN_STORE_HANDLE *hdl)
 {
 #ifndef OPENSSL_NO_QUIC
-    return ossl_quic_set_token_store(ctx, hdl);
+    return ossl_quic_set1_token_store(ctx, hdl);
 #else
     return 0;
 #endif

diff --git a/util/libssl.num b/util/libssl.num
index bd442eaa75b5412022b88b5f1e0b912469916598..36a9545fbba2f688fd18399269a92fcf9043c7e8 100644 (file)
--- a/util/libssl.num
+++ b/util/libssl.num
@@ -606,4 +606,4 @@ SSL_CTX_get_domain_flags                ?   3_5_0   EXIST::FUNCTION:
 SSL_get_domain_flags                    ?      3_5_0   EXIST::FUNCTION:
 SSL_CTX_set_new_pending_conn_cb         ?      3_5_0   EXIST::FUNCTION:
 SSL_CTX_get0_token_store                ?      3_5_0   EXIST::FUNCTION:
-SSL_CTX_set_token_store                 ?      3_5_0   EXIST::FUNCTION:
+SSL_CTX_set1_token_store                ?      3_5_0   EXIST::FUNCTION: