From e521131c60e25e6fb2269f4ff9c2619d89ac95a3 Mon Sep 17 00:00:00 2001 From: Neil Horman Date: Thu, 30 Jan 2025 12:14:26 -0500 Subject: [PATCH] Rename token_store functions to make them consistent MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit 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 Reviewed-by: Saša Nedvědický (Merged from https://github.com/openssl/openssl/pull/26517) --- doc/man3/SSL_CTX_get0_token_store.pod | 49 +++++++++++++++++++++++---- include/internal/quic_ssl.h | 4 +-- include/openssl/ssl.h.in | 2 +- ssl/quic/quic_impl.c | 4 +-- ssl/ssl_lib.c | 6 ++-- util/libssl.num | 2 +- 6 files changed, 52 insertions(+), 15 deletions(-) diff --git a/doc/man3/SSL_CTX_get0_token_store.pod b/doc/man3/SSL_CTX_get0_token_store.pod index f353e0989dd..77858d64a7a 100644 --- 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 objects to share those tokens between B connections allocated fr disparate B 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 object. +in a subsequent call to SSL_CTX_set1_token_store() on another B 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 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 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 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 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 95b837da5cb..17cac02cc03 100644 --- 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 393a3a0fa69..b337ef0f3d2 100644 --- 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 5915c25fa5b..b0ad6fdfa77 100644 --- 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 9334af39a5d..19d274b1b9a 100644 --- 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 bd442eaa75b..36a9545fbba 100644 --- 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: -- 2.47.2