From d857a4accf688533b3ea0b0507b4e97f2aa53b8e Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Tue, 30 Apr 2024 15:35:42 +0100 Subject: [PATCH] Document the SSL_set_session_secret_cb() function This function is only useful for EAP-FAST, but was previously undocumented. --- doc/build.info | 6 +++ doc/man3/SSL_set_session_secret_cb.pod | 68 ++++++++++++++++++++++++++ util/missingssl.txt | 1 - util/other.syms | 1 + 4 files changed, 75 insertions(+), 1 deletion(-) create mode 100644 doc/man3/SSL_set_session_secret_cb.pod diff --git a/doc/build.info b/doc/build.info index c7cb6d5d4fb3e..65cedb9d48526 100644 --- a/doc/build.info +++ b/doc/build.info @@ -2743,6 +2743,10 @@ DEPEND[html/man3/SSL_set_session.html]=man3/SSL_set_session.pod GENERATE[html/man3/SSL_set_session.html]=man3/SSL_set_session.pod DEPEND[man/man3/SSL_set_session.3]=man3/SSL_set_session.pod GENERATE[man/man3/SSL_set_session.3]=man3/SSL_set_session.pod +DEPEND[html/man3/SSL_set_session_secret_cb.html]=man3/SSL_set_session_secret_cb.pod +GENERATE[html/man3/SSL_set_session_secret_cb.html]=man3/SSL_set_session_secret_cb.pod +DEPEND[man/man3/SSL_set_session_secret_cb.3]=man3/SSL_set_session_secret_cb.pod +GENERATE[man/man3/SSL_set_session_secret_cb.3]=man3/SSL_set_session_secret_cb.pod DEPEND[html/man3/SSL_set_shutdown.html]=man3/SSL_set_shutdown.pod GENERATE[html/man3/SSL_set_shutdown.html]=man3/SSL_set_shutdown.pod DEPEND[man/man3/SSL_set_shutdown.3]=man3/SSL_set_shutdown.pod @@ -3645,6 +3649,7 @@ html/man3/SSL_set_fd.html \ html/man3/SSL_set_incoming_stream_policy.html \ html/man3/SSL_set_retry_verify.html \ html/man3/SSL_set_session.html \ +html/man3/SSL_set_session_secret_cb.html \ html/man3/SSL_set_shutdown.html \ html/man3/SSL_set_verify_result.html \ html/man3/SSL_shutdown.html \ @@ -4297,6 +4302,7 @@ man/man3/SSL_set_fd.3 \ man/man3/SSL_set_incoming_stream_policy.3 \ man/man3/SSL_set_retry_verify.3 \ man/man3/SSL_set_session.3 \ +man/man3/SSL_set_session_secret_cb.3 \ man/man3/SSL_set_shutdown.3 \ man/man3/SSL_set_verify_result.3 \ man/man3/SSL_shutdown.3 \ diff --git a/doc/man3/SSL_set_session_secret_cb.pod b/doc/man3/SSL_set_session_secret_cb.pod new file mode 100644 index 0000000000000..41d752a872285 --- /dev/null +++ b/doc/man3/SSL_set_session_secret_cb.pod @@ -0,0 +1,68 @@ +=pod + +=head1 NAME + +SSL_set_session_secret_cb, tls_session_secret_cb_fn +- set the session secret callback + +=head1 SYNOPSIS + + #include + + typedef int (*tls_session_secret_cb_fn)(SSL *s, void *secret, int *secret_len, + STACK_OF(SSL_CIPHER) *peer_ciphers, + const SSL_CIPHER **cipher, void *arg); + + int SSL_set_session_secret_cb(SSL *s, + tls_session_secret_cb_fn session_secret_cb, + void *arg); + +=head1 DESCRIPTION + +SSL_set_session_secret_cb() sets the session secret callback to be used +(B), and an optional argument (B) to be passed to that +callback when it is called. This is only useful for an implementation of +EAP-FAST (RFC4851). The presence of the callback also modifies the internal +OpenSSL TLS state machine to match the modified TLS behaviour as described in +RFC4851. Therefore this callback should not be used except when implementing +EAP-FAST. + +The callback is expected to set the master secret to be used by filling in the +data pointed to by B<*secret>. The size of the secret buffer is initially +available in B<*secret_len> and may be updated by the callback (but must not be +larger than the initial value). + +On the server side the set of ciphersuites offered by the peer is provided in +the B stack. Optionally the callback may select the preferred +ciphersuite by setting it in B<*cipher>. + +On the client side the B stack will always be NULL. The callback +may specify the preferred cipher in B<*cipher> and this will be associated with +the SSL_SESSION - but it does not affect the ciphersuite selected by the server. + +The callback is also supplied with an additional argument in B which is the +argument that was provided to the original SSL_set_session_secret_cb() call. + +=head1 RETURN VALUES + +SSL_set_session_secret_cb() returns 1 on success and 0 on failure. + +If the callback returns 1 then this indicates it has successfully set the +secret. A return value of 0 indicates that the secret has not been set. On the +client this will cause an immediate abort of the handshake. + +=head1 SEE ALSO + +L, +L + +=head1 COPYRIGHT + +Copyright 2024 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 diff --git a/util/missingssl.txt b/util/missingssl.txt index 1338feed71188..8da9842a0b57d 100644 --- a/util/missingssl.txt +++ b/util/missingssl.txt @@ -25,7 +25,6 @@ SSL_get_peer_finished(3) SSL_set_SSL_CTX(3) SSL_set_debug(3) SSL_set_not_resumable_session_callback(3) -SSL_set_session_secret_cb(3) SSL_set_session_ticket_ext(3) SSL_set_session_ticket_ext_cb(3) SSL_srp_server_param_with_username(3) diff --git a/util/other.syms b/util/other.syms index bf6ae33d5acb9..cdd585589adae 100644 --- a/util/other.syms +++ b/util/other.syms @@ -144,6 +144,7 @@ custom_ext_free_cb datatype custom_ext_parse_cb datatype pem_password_cb datatype ssl_ct_validation_cb datatype +tls_session_secret_cb_fn datatype ASYNC_stack_alloc_fn datatype ASYNC_stack_free_fn datatype PKCS12_create_cb datatype