From 3649a47f823fb366a5dc71216e0a0fb07072158a Mon Sep 17 00:00:00 2001 From: Neil Horman Date: Wed, 15 Jan 2025 12:01:31 -0500 Subject: [PATCH] Add docs for token store manipulation MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Reviewed-by: Matt Caswell Reviewed-by: Saša Nedvědický (Merged from https://github.com/openssl/openssl/pull/26517) --- doc/build.info | 6 +++ doc/man3/SSL_CTX_get0_token_store.pod | 66 +++++++++++++++++++++++++++ 2 files changed, 72 insertions(+) create mode 100644 doc/man3/SSL_CTX_get0_token_store.pod diff --git a/doc/build.info b/doc/build.info index 4a4cf94b437..79afa9b4651 100644 --- a/doc/build.info +++ b/doc/build.info @@ -2259,6 +2259,10 @@ DEPEND[html/man3/SSL_CTX_get0_param.html]=man3/SSL_CTX_get0_param.pod GENERATE[html/man3/SSL_CTX_get0_param.html]=man3/SSL_CTX_get0_param.pod DEPEND[man/man3/SSL_CTX_get0_param.3]=man3/SSL_CTX_get0_param.pod GENERATE[man/man3/SSL_CTX_get0_param.3]=man3/SSL_CTX_get0_param.pod +DEPEND[html/man3/SSL_CTX_get0_token_store.html]=man3/SSL_CTX_get0_token_store.pod +GENERATE[html/man3/SSL_CTX_get0_token_store.html]=man3/SSL_CTX_get0_token_store.pod +DEPEND[man/man3/SSL_CTX_get0_token_store.3]=man3/SSL_CTX_get0_token_store.pod +GENERATE[man/man3/SSL_CTX_get0_token_store.3]=man3/SSL_CTX_get0_token_store.pod DEPEND[html/man3/SSL_CTX_get_verify_mode.html]=man3/SSL_CTX_get_verify_mode.pod GENERATE[html/man3/SSL_CTX_get_verify_mode.html]=man3/SSL_CTX_get_verify_mode.pod DEPEND[man/man3/SSL_CTX_get_verify_mode.3]=man3/SSL_CTX_get_verify_mode.pod @@ -3610,6 +3614,7 @@ html/man3/SSL_CTX_dane_enable.html \ html/man3/SSL_CTX_flush_sessions.html \ html/man3/SSL_CTX_free.html \ html/man3/SSL_CTX_get0_param.html \ +html/man3/SSL_CTX_get0_token_store.html \ html/man3/SSL_CTX_get_verify_mode.html \ html/man3/SSL_CTX_has_client_custom_ext.html \ html/man3/SSL_CTX_load_verify_locations.html \ @@ -4282,6 +4287,7 @@ man/man3/SSL_CTX_dane_enable.3 \ man/man3/SSL_CTX_flush_sessions.3 \ man/man3/SSL_CTX_free.3 \ man/man3/SSL_CTX_get0_param.3 \ +man/man3/SSL_CTX_get0_token_store.3 \ man/man3/SSL_CTX_get_verify_mode.3 \ man/man3/SSL_CTX_has_client_custom_ext.3 \ man/man3/SSL_CTX_load_verify_locations.3 \ diff --git a/doc/man3/SSL_CTX_get0_token_store.pod b/doc/man3/SSL_CTX_get0_token_store.pod new file mode 100644 index 00000000000..f353e0989dd --- /dev/null +++ b/doc/man3/SSL_CTX_get0_token_store.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + +SSL_CTX_get0_token_store, SSL_CTX_set_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); + +=head1 DESCRIPTION +The QUIC protocol supports the exchange of opaque tokens which a client can use +to reduce the time for a server to validate a client address. These tokens are +stored on receipt from a server, and automatically reused in the establishment +of a new future connection to the same server. A token store is automatically +created on the creation of an B and freed on its release. The +functions above can be used to fetch and set the token store between independent +B objects to share those tokens between B connections allocated from +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. + +SSL_CTX_set_token_store() assigns a token store fetched fom SSL_CTX_get0_token_store +to a second B object. + +=head1 NOTES + +Token stores are internally reference counted. Note that a call to SSL_CTX_get0_token_store +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 +incremented. It will be decremented when that B is freed via a call to +SSL_CTX_free(). + +These functions are only applicable to QUIC B objects. Using them on +non-QUIC objects will result in error returns. + +=head1 RETURN VALUES + +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. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +The NEW_TOKEN store manipulation functions were added in OpenSSL 3.5.0. + +=head1 COPYRIGHT + +Copyright 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 +in the file LICENSE in the source distribution or at +L. + +=cut -- 2.47.2