Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_use_psk_identity_hint.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_USE_PSK_IDENTITY_HINT 3SSL"
58 .TH SSL_CTX_USE_PSK_IDENTITY_HINT 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_server_cb_func,
65 SSL_psk_find_session_cb_func,
66 SSL_CTX_use_psk_identity_hint,
67 SSL_use_psk_identity_hint,
68 SSL_CTX_set_psk_server_callback,
69 SSL_set_psk_server_callback,
70 SSL_CTX_set_psk_find_session_callback,
71 SSL_set_psk_find_session_callback
72 \&\- set PSK identity hint to use
73 .SH SYNOPSIS
74 .IX Header "SYNOPSIS"
75 .Vb 1
76 \& #include <openssl/ssl.h>
77 \&
78 \& typedef int (*SSL_psk_find_session_cb_func)(SSL *ssl,
79 \& const unsigned char *identity,
80 \& size_t identity_len,
81 \& SSL_SESSION **sess);
82 \&
83 \&
84 \& void SSL_CTX_set_psk_find_session_callback(SSL_CTX *ctx,
85 \& SSL_psk_find_session_cb_func cb);
86 \& void SSL_set_psk_find_session_callback(SSL *s, SSL_psk_find_session_cb_func cb);
87 \&
88 \& typedef unsigned int (*SSL_psk_server_cb_func)(SSL *ssl,
89 \& const char *identity,
90 \& unsigned char *psk,
91 \& unsigned int max_psk_len);
92 \&
93 \& int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint);
94 \& int SSL_use_psk_identity_hint(SSL *ssl, const char *hint);
95 \&
96 \& void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx, SSL_psk_server_cb_func cb);
97 \& void SSL_set_psk_server_callback(SSL *ssl, SSL_psk_server_cb_func cb);
98 .Ve
99 .SH DESCRIPTION
100 .IX Header "DESCRIPTION"
101 A server application wishing to use TLSv1.3 PSKs should set a callback
102 using either \fBSSL_CTX_set_psk_find_session_callback()\fR or
103 \&\fBSSL_set_psk_find_session_callback()\fR as appropriate.
104 .PP
105 The callback function is given a pointer to the SSL connection in \fBssl\fR and
106 an identity in \fBidentity\fR of length \fBidentity_len\fR. The callback function
107 should identify an SSL_SESSION object that provides the PSK details and store it
108 in \fB*sess\fR. The SSL_SESSION object should, as a minimum, set the master key,
109 the ciphersuite and the protocol version. See
110 \&\fBSSL_CTX_set_psk_use_session_callback\fR\|(3) for details.
111 .PP
112 It is also possible for the callback to succeed but not supply a PSK. In this
113 case no PSK will be used but the handshake will continue. To do this the
114 callback should return successfully and ensure that \fB*sess\fR is
115 NULL.
116 .PP
117 Identity hints are not relevant for TLSv1.3. A server application wishing to use
118 PSK ciphersuites for TLSv1.2 and below may call \fBSSL_CTX_use_psk_identity_hint()\fR
119 to set the given \fBNUL\fR\-terminated PSK identity hint \fBhint\fR for SSL context
120 object \fBctx\fR. \fBSSL_use_psk_identity_hint()\fR sets the given \fBNUL\fR\-terminated PSK
121 identity hint \fBhint\fR for the SSL connection object \fBssl\fR. If \fBhint\fR is
122 \&\fBNULL\fR the current hint from \fBctx\fR or \fBssl\fR is deleted.
123 .PP
124 In the case where PSK identity hint is \fBNULL\fR, the server does not send the
125 ServerKeyExchange message to the client.
126 .PP
127 A server application wishing to use PSKs for TLSv1.2 and below must provide a
128 callback function which is called when the server receives the
129 ClientKeyExchange message from the client. The purpose of the callback function
130 is to validate the received PSK identity and to fetch the pre-shared key used
131 during the connection setup phase. The callback is set using the functions
132 \&\fBSSL_CTX_set_psk_server_callback()\fR or \fBSSL_set_psk_server_callback()\fR. The callback
133 function is given the connection in parameter \fBssl\fR, \fBNUL\fR\-terminated PSK
134 identity sent by the client in parameter \fBidentity\fR, and a buffer \fBpsk\fR of
135 length \fBmax_psk_len\fR bytes where the pre-shared key is to be stored.
136 .PP
137 The callback for use in TLSv1.2 will also work in TLSv1.3 although it is
138 recommended to use \fBSSL_CTX_set_psk_find_session_callback()\fR
139 or \fBSSL_set_psk_find_session_callback()\fR for this purpose instead. If TLSv1.3 has
140 been negotiated then OpenSSL will first check to see if a callback has been set
141 via \fBSSL_CTX_set_psk_find_session_callback()\fR or \fBSSL_set_psk_find_session_callback()\fR
142 and it will use that in preference. If no such callback is present then it will
143 check to see if a callback has been set via \fBSSL_CTX_set_psk_server_callback()\fR or
144 \&\fBSSL_set_psk_server_callback()\fR and use that. In this case the handshake digest
145 will default to SHA\-256 for any returned PSK. TLSv1.3 early data exchanges are
146 possible in PSK connections only with the \fBSSL_psk_find_session_cb_func\fR
147 callback, and are not possible with the \fBSSL_psk_server_cb_func\fR callback.
148 .PP
149 A connection established via a TLSv1.3 PSK will appear as if session resumption
150 has occurred so that \fBSSL_session_reused\fR\|(3) will return true.
151 .SH "RETURN VALUES"
152 .IX Header "RETURN VALUES"
153 \&\fBSSL_CTX_use_psk_identity_hint()\fR and \fBSSL_use_psk_identity_hint()\fR return
154 1 on success, 0 otherwise.
155 .PP
156 Return values from the TLSv1.2 and below server callback are interpreted as
157 follows:
158 .IP 0 4
159 PSK identity was not found. An "unknown_psk_identity" alert message
160 will be sent and the connection setup fails.
161 .IP >0 4
162 .IX Item ">0"
163 PSK identity was found and the server callback has provided the PSK
164 successfully in parameter \fBpsk\fR. Return value is the length of
165 \&\fBpsk\fR in bytes. It is an error to return a value greater than
166 \&\fBmax_psk_len\fR.
167 .Sp
168 If the PSK identity was not found but the callback instructs the
169 protocol to continue anyway, the callback must provide some random
170 data to \fBpsk\fR and return the length of the random data, so the
171 connection will fail with decryption_error before it will be finished
172 completely.
173 .PP
174 The \fBSSL_psk_find_session_cb_func\fR callback should return 1 on success or 0 on
175 failure. In the event of failure the connection setup fails.
176 .SH NOTES
177 .IX Header "NOTES"
178 There are no known security issues with sharing the same PSK between TLSv1.2 (or
179 below) and TLSv1.3. However, the RFC has this note of caution:
180 .PP
181 "While there is no known way in which the same PSK might produce related output
182 in both versions, only limited analysis has been done. Implementations can
183 ensure safety from cross-protocol related output by not reusing PSKs between
184 TLS 1.3 and TLS 1.2."
185 .SH "SEE ALSO"
186 .IX Header "SEE ALSO"
187 \&\fBssl\fR\|(7),
188 \&\fBSSL_CTX_set_psk_use_session_callback\fR\|(3),
189 \&\fBSSL_set_psk_use_session_callback\fR\|(3)
190 .SH HISTORY
191 .IX Header "HISTORY"
192 \&\fBSSL_CTX_set_psk_find_session_callback()\fR and \fBSSL_set_psk_find_session_callback()\fR
193 were added in OpenSSL 1.1.1.
194 .SH COPYRIGHT
195 .IX Header "COPYRIGHT"
196 Copyright 2006\-2020 The OpenSSL Project Authors. All Rights Reserved.
197 .PP
198 Licensed under the Apache License 2.0 (the "License"). You may not use
199 this file except in compliance with the License. You can obtain a copy
200 in the file LICENSE in the source distribution or at
201 <https://www.openssl.org/source/license.html>.