1*e7be843bSPierre Pronchery=pod 2*e7be843bSPierre Pronchery 3*e7be843bSPierre Pronchery=head1 NAME 4*e7be843bSPierre Pronchery 5*e7be843bSPierre ProncherySSL_set_session_secret_cb, tls_session_secret_cb_fn 6*e7be843bSPierre Pronchery- set the session secret callback 7*e7be843bSPierre Pronchery 8*e7be843bSPierre Pronchery=head1 SYNOPSIS 9*e7be843bSPierre Pronchery 10*e7be843bSPierre Pronchery #include <openssl/ssl.h> 11*e7be843bSPierre Pronchery 12*e7be843bSPierre Pronchery typedef int (*tls_session_secret_cb_fn)(SSL *s, void *secret, int *secret_len, 13*e7be843bSPierre Pronchery STACK_OF(SSL_CIPHER) *peer_ciphers, 14*e7be843bSPierre Pronchery const SSL_CIPHER **cipher, void *arg); 15*e7be843bSPierre Pronchery 16*e7be843bSPierre Pronchery int SSL_set_session_secret_cb(SSL *s, 17*e7be843bSPierre Pronchery tls_session_secret_cb_fn session_secret_cb, 18*e7be843bSPierre Pronchery void *arg); 19*e7be843bSPierre Pronchery 20*e7be843bSPierre Pronchery=head1 DESCRIPTION 21*e7be843bSPierre Pronchery 22*e7be843bSPierre ProncherySSL_set_session_secret_cb() sets the session secret callback to be used 23*e7be843bSPierre Pronchery(I<session_secret_cb>), and an optional argument (I<arg>) to be passed to that 24*e7be843bSPierre Proncherycallback when it is called. This is only useful for an implementation of 25*e7be843bSPierre ProncheryEAP-FAST (RFC4851). The presence of the callback also modifies the internal 26*e7be843bSPierre ProncheryOpenSSL TLS state machine to match the modified TLS behaviour as described in 27*e7be843bSPierre ProncheryRFC4851. Therefore this callback should not be used except when implementing 28*e7be843bSPierre ProncheryEAP-FAST. 29*e7be843bSPierre Pronchery 30*e7be843bSPierre ProncheryThe callback is expected to set the master secret to be used by filling in the 31*e7be843bSPierre Proncherydata pointed to by I<*secret>. The size of the secret buffer is initially 32*e7be843bSPierre Proncheryavailable in I<*secret_len> and may be updated by the callback (but must not be 33*e7be843bSPierre Proncherylarger than the initial value). 34*e7be843bSPierre Pronchery 35*e7be843bSPierre ProncheryOn the server side the set of ciphersuites offered by the peer is provided in 36*e7be843bSPierre Proncherythe I<peer_ciphers> stack. Optionally the callback may select the preferred 37*e7be843bSPierre Proncheryciphersuite by setting it in I<*cipher>. 38*e7be843bSPierre Pronchery 39*e7be843bSPierre ProncheryOn the client side the I<peer_ciphers> stack will always be NULL. The callback 40*e7be843bSPierre Proncherymay specify the preferred cipher in I<*cipher> and this will be associated with 41*e7be843bSPierre Proncherythe B<SSL_SESSION> - but it does not affect the ciphersuite selected by the 42*e7be843bSPierre Proncheryserver. 43*e7be843bSPierre Pronchery 44*e7be843bSPierre ProncheryThe callback is also supplied with an additional argument in I<arg> which is the 45*e7be843bSPierre Proncheryargument that was provided to the original SSL_set_session_secret_cb() call. 46*e7be843bSPierre Pronchery 47*e7be843bSPierre Pronchery=head1 RETURN VALUES 48*e7be843bSPierre Pronchery 49*e7be843bSPierre ProncherySSL_set_session_secret_cb() returns 1 on success and 0 on failure. 50*e7be843bSPierre Pronchery 51*e7be843bSPierre ProncheryIf the callback returns 1 then this indicates it has successfully set the 52*e7be843bSPierre Proncherysecret. A return value of 0 indicates that the secret has not been set. On the 53*e7be843bSPierre Proncheryclient this will cause an immediate abort of the handshake. 54*e7be843bSPierre Pronchery 55*e7be843bSPierre Pronchery=head1 SEE ALSO 56*e7be843bSPierre Pronchery 57*e7be843bSPierre ProncheryL<ssl(7)>, 58*e7be843bSPierre ProncheryL<SSL_get_session(3)> 59*e7be843bSPierre Pronchery 60*e7be843bSPierre Pronchery=head1 COPYRIGHT 61*e7be843bSPierre Pronchery 62*e7be843bSPierre ProncheryCopyright 2024 The OpenSSL Project Authors. All Rights Reserved. 63*e7be843bSPierre Pronchery 64*e7be843bSPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 65*e7be843bSPierre Proncherythis file except in compliance with the License. You can obtain a copy 66*e7be843bSPierre Proncheryin the file LICENSE in the source distribution or at 67*e7be843bSPierre ProncheryL<https://www.openssl.org/source/license.html>. 68*e7be843bSPierre Pronchery 69*e7be843bSPierre Pronchery=cut 70