Debian Codegraph @

upstream/debian-unstable/man3/SSL_set_session_secret_cb.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_SET_SESSION_SECRET_CB 3SSL"
58 .TH SSL_SET_SESSION_SECRET_CB 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_set_session_secret_cb, tls_session_secret_cb_fn
65 \&\- set the session secret callback
66 .SH SYNOPSIS
67 .IX Header "SYNOPSIS"
68 .Vb 1
69 \& #include <openssl/ssl.h>
70 \&
71 \& typedef int (*tls_session_secret_cb_fn)(SSL *s, void *secret, int *secret_len,
72 \& STACK_OF(SSL_CIPHER) *peer_ciphers,
73 \& const SSL_CIPHER **cipher, void *arg);
74 \&
75 \& int SSL_set_session_secret_cb(SSL *s,
76 \& tls_session_secret_cb_fn session_secret_cb,
77 \& void *arg);
78 .Ve
79 .SH DESCRIPTION
80 .IX Header "DESCRIPTION"
81 \&\fBSSL_set_session_secret_cb()\fR sets the session secret callback to be used
82 (\fIsession_secret_cb\fR), and an optional argument (\fIarg\fR) to be passed to that
83 callback when it is called. This is only useful for an implementation of
84 EAP-FAST (RFC4851). The presence of the callback also modifies the internal
85 OpenSSL TLS state machine to match the modified TLS behaviour as described in
86 RFC4851. Therefore this callback should not be used except when implementing
87 EAP-FAST.
88 .PP
89 The callback is expected to set the master secret to be used by filling in the
90 data pointed to by \fI*secret\fR. The size of the secret buffer is initially
91 available in \fI*secret_len\fR and may be updated by the callback (but must not be
92 larger than the initial value).
93 .PP
94 On the server side the set of ciphersuites offered by the peer is provided in
95 the \fIpeer_ciphers\fR stack. Optionally the callback may select the preferred
96 ciphersuite by setting it in \fI*cipher\fR.
97 .PP
98 On the client side the \fIpeer_ciphers\fR stack will always be NULL. The callback
99 may specify the preferred cipher in \fI*cipher\fR and this will be associated with
100 the \fBSSL_SESSION\fR \- but it does not affect the ciphersuite selected by the
101 server.
102 .PP
103 The callback is also supplied with an additional argument in \fIarg\fR which is the
104 argument that was provided to the original \fBSSL_set_session_secret_cb()\fR call.
105 .SH "RETURN VALUES"
106 .IX Header "RETURN VALUES"
107 \&\fBSSL_set_session_secret_cb()\fR returns 1 on success and 0 on failure.
108 .PP
109 If the callback returns 1 then this indicates it has successfully set the
110 secret. A return value of 0 indicates that the secret has not been set. On the
111 client this will cause an immediate abort of the handshake.
112 .SH "SEE ALSO"
113 .IX Header "SEE ALSO"
114 \&\fBssl\fR\|(7),
115 \&\fBSSL_get_session\fR\|(3)
116 .SH COPYRIGHT
117 .IX Header "COPYRIGHT"
118 Copyright 2024 The OpenSSL Project Authors. All Rights Reserved.
119 .PP
120 Licensed under the Apache License 2.0 (the "License"). You may not use
121 this file except in compliance with the License. You can obtain a copy
122 in the file LICENSE in the source distribution or at
123 <https://www.openssl.org/source/license.html>.