Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_set_psk_client_callback.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_CTX_SET_PSK_CLIENT_CALLBACK 3SSL"
58 .TH SSL_CTX_SET_PSK_CLIENT_CALLBACK 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_psk_client_cb_func,
65 SSL_psk_use_session_cb_func,
66 SSL_CTX_set_psk_client_callback,
67 SSL_set_psk_client_callback,
68 SSL_CTX_set_psk_use_session_callback,
69 SSL_set_psk_use_session_callback
70 \&\- set PSK client callback
71 .SH SYNOPSIS
72 .IX Header "SYNOPSIS"
73 .Vb 1
74 \& #include <openssl/ssl.h>
75 \&
76 \& typedef int (*SSL_psk_use_session_cb_func)(SSL *ssl, const EVP_MD *md,
77 \& const unsigned char **id,
78 \& size_t *idlen,
79 \& SSL_SESSION **sess);
80 \&
81 \&
82 \& void SSL_CTX_set_psk_use_session_callback(SSL_CTX *ctx,
83 \& SSL_psk_use_session_cb_func cb);
84 \& void SSL_set_psk_use_session_callback(SSL *s, SSL_psk_use_session_cb_func cb);
85 \&
86 \&
87 \& typedef unsigned int (*SSL_psk_client_cb_func)(SSL *ssl,
88 \& const char *hint,
89 \& char *identity,
90 \& unsigned int max_identity_len,
91 \& unsigned char *psk,
92 \& unsigned int max_psk_len);
93 \&
94 \& void SSL_CTX_set_psk_client_callback(SSL_CTX *ctx, SSL_psk_client_cb_func cb);
95 \& void SSL_set_psk_client_callback(SSL *ssl, SSL_psk_client_cb_func cb);
96 .Ve
97 .SH DESCRIPTION
98 .IX Header "DESCRIPTION"
99 A client application wishing to use TLSv1.3 PSKs should use either
100 \&\fBSSL_CTX_set_psk_use_session_callback()\fR or \fBSSL_set_psk_use_session_callback()\fR as
101 appropriate. These functions cannot be used for TLSv1.2 and below PSKs.
102 .PP
103 The callback function is given a pointer to the SSL connection in \fBssl\fR.
104 .PP
105 The first time the callback is called for a connection the \fBmd\fR parameter is
106 NULL. In some circumstances the callback will be called a second time. In that
107 case the server will have specified a ciphersuite to use already and the PSK
108 must be compatible with the digest for that ciphersuite. The digest will be
109 given in \fBmd\fR. The PSK returned by the callback is allowed to be different
110 between the first and second time it is called.
111 .PP
112 On successful completion the callback must store a pointer to an identifier for
113 the PSK in \fB*id\fR. The identifier length in bytes should be stored in \fB*idlen\fR.
114 The memory pointed to by \fB*id\fR remains owned by the application and should
115 be freed by it as required at any point after the handshake is complete.
116 .PP
117 Additionally the callback should store a pointer to an SSL_SESSION object in
118 \&\fB*sess\fR. This is used as the basis for the PSK, and should, at a minimum, have
119 the following fields set:
120 .IP "The master key" 4
121 .IX Item "The master key"
122 This can be set via a call to \fBSSL_SESSION_set1_master_key\fR\|(3).
123 .IP "A ciphersuite" 4
124 .IX Item "A ciphersuite"
125 Only the handshake digest associated with the ciphersuite is relevant for the
126 PSK (the server may go on to negotiate any ciphersuite which is compatible with
127 the digest). The application can use any TLSv1.3 ciphersuite. If \fBmd\fR is
128 not NULL the handshake digest for the ciphersuite should be the same.
129 The ciphersuite can be set via a call to <\fBSSL_SESSION_set_cipher\fR\|(3)>. The
130 handshake digest of an SSL_CIPHER object can be checked using
131 <\fBSSL_CIPHER_get_handshake_digest\fR\|(3)>.
132 .IP "The protocol version" 4
133 .IX Item "The protocol version"
134 This can be set via a call to \fBSSL_SESSION_set_protocol_version\fR\|(3) and should
135 be TLS1_3_VERSION.
136 .PP
137 Additionally the maximum early data value should be set via a call to
138 \&\fBSSL_SESSION_set_max_early_data\fR\|(3) if the PSK will be used for sending early
139 data.
140 .PP
141 Alternatively an SSL_SESSION created from a previous non-PSK handshake may also
142 be used as the basis for a PSK.
143 .PP
144 Ownership of the SSL_SESSION object is passed to the OpenSSL library and so it
145 should not be freed by the application.
146 .PP
147 Note that as described above, the callback may be called a second time during a
148 handshake. Since ownership of the SSL_SESSION is transferred to OpenSSL on each
149 call, if the callback wishes to return the same SSL_SESSION pointer on a
150 subsequent invocation, it must first call \fBSSL_SESSION_up_ref\fR\|(3) to increment
151 the reference count. Failure to do so will result in a use-after-free error.
152 Alternatively, the callback may return a different SSL_SESSION object on each
153 call (e.g., by calling \fBSSL_SESSION_dup\fR\|(3)).
154 .PP
155 It is also possible for the callback to succeed but not supply a PSK. In this
156 case no PSK will be sent to the server but the handshake will continue. To do
157 this the callback should return successfully and ensure that \fB*sess\fR is
158 NULL. The contents of \fB*id\fR and \fB*idlen\fR will be ignored.
159 .PP
160 A client application wishing to use PSK ciphersuites for TLSv1.2 and below must
161 provide a different callback function. This function will be called when the
162 client is sending the ClientKeyExchange message to the server.
163 .PP
164 The purpose of the callback function is to select the PSK identity and
165 the pre-shared key to use during the connection setup phase.
166 .PP
167 The callback is set using functions \fBSSL_CTX_set_psk_client_callback()\fR
168 or \fBSSL_set_psk_client_callback()\fR. The callback function is given the
169 connection in parameter \fBssl\fR, a \fBNUL\fR\-terminated PSK identity hint
170 sent by the server in parameter \fBhint\fR, a buffer \fBidentity\fR of
171 length \fBmax_identity_len\fR bytes (including the \fBNUL\fR\-terminator) where the
172 resulting \fBNUL\fR\-terminated identity is to be stored, and a buffer \fBpsk\fR
173 of length \fBmax_psk_len\fR bytes where the resulting pre-shared key is to
174 be stored.
175 .PP
176 The callback for use in TLSv1.2 will also work in TLSv1.3 although it is
177 recommended to use \fBSSL_CTX_set_psk_use_session_callback()\fR
178 or \fBSSL_set_psk_use_session_callback()\fR for this purpose instead. If TLSv1.3 has
179 been negotiated then OpenSSL will first check to see if a callback has been set
180 via \fBSSL_CTX_set_psk_use_session_callback()\fR or \fBSSL_set_psk_use_session_callback()\fR
181 and it will use that in preference. If no such callback is present then it will
182 check to see if a callback has been set via \fBSSL_CTX_set_psk_client_callback()\fR or
183 \&\fBSSL_set_psk_client_callback()\fR and use that. In this case the \fBhint\fR value will
184 always be NULL and the handshake digest will default to SHA\-256 for any returned
185 PSK. TLSv1.3 early data exchanges are possible in PSK connections only with the
186 \&\fBSSL_psk_use_session_cb_func\fR callback, and are not possible with the
187 \&\fBSSL_psk_client_cb_func\fR callback.
188 .SH NOTES
189 .IX Header "NOTES"
190 Note that parameter \fBhint\fR given to the callback may be \fBNULL\fR.
191 .PP
192 A connection established via a TLSv1.3 PSK will appear as if session resumption
193 has occurred so that \fBSSL_session_reused\fR\|(3) will return true.
194 .PP
195 There are no known security issues with sharing the same PSK between TLSv1.2 (or
196 below) and TLSv1.3. However, the RFC has this note of caution:
197 .PP
198 "While there is no known way in which the same PSK might produce related output
199 in both versions, only limited analysis has been done. Implementations can
200 ensure safety from cross-protocol related output by not reusing PSKs between
201 TLS 1.3 and TLS 1.2."
202 .SH "RETURN VALUES"
203 .IX Header "RETURN VALUES"
204 Return values from the \fBSSL_psk_client_cb_func\fR callback are interpreted as
205 follows:
206 .PP
207 On success (callback found a PSK identity and a pre-shared key to use)
208 the length (> 0) of \fBpsk\fR in bytes is returned.
209 .PP
210 Otherwise or on errors the callback should return 0. In this case
211 the connection setup fails.
212 .PP
213 The SSL_psk_use_session_cb_func callback should return 1 on success or 0 on
214 failure. In the event of failure the connection setup fails.
215 .SH "SEE ALSO"
216 .IX Header "SEE ALSO"
217 \&\fBssl\fR\|(7),
218 \&\fBSSL_CTX_set_psk_find_session_callback\fR\|(3),
219 \&\fBSSL_set_psk_find_session_callback\fR\|(3)
220 .SH HISTORY
221 .IX Header "HISTORY"
222 \&\fBSSL_CTX_set_psk_use_session_callback()\fR and \fBSSL_set_psk_use_session_callback()\fR
223 were added in OpenSSL 1.1.1.
224 .SH COPYRIGHT
225 .IX Header "COPYRIGHT"
226 Copyright 2006\-2026 The OpenSSL Project Authors. All Rights Reserved.
227 .PP
228 Licensed under the Apache License 2.0 (the "License"). You may not use
229 this file except in compliance with the License. You can obtain a copy
230 in the file LICENSE in the source distribution or at
231 <https://www.openssl.org/source/license.html>.