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