Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_set_tlsext_ticket_key_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_CTX_SET_TLSEXT_TICKET_KEY_CB 3SSL"
58 .TH SSL_CTX_SET_TLSEXT_TICKET_KEY_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_CTX_set_tlsext_ticket_key_evp_cb,
65 SSL_CTX_set_tlsext_ticket_key_cb
66 \&\- set a callback for session ticket processing
67 .SH SYNOPSIS
68 .IX Header "SYNOPSIS"
69 .Vb 1
70 \& #include <openssl/tls1.h>
71 \&
72 \& int SSL_CTX_set_tlsext_ticket_key_evp_cb(SSL_CTX sslctx,
73 \& int (*cb)(SSL *s, unsigned char key_name[16],
74 \& unsigned char iv[EVP_MAX_IV_LENGTH],
75 \& EVP_CIPHER_CTX *ctx, EVP_MAC_CTX *hctx, int enc));
76 .Ve
77 .PP
78 The following function has been deprecated since OpenSSL 3.0, and can be
79 hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value,
80 see \fBopenssl_user_macros\fR\|(7):
81 .PP
82 .Vb 4
83 \& int SSL_CTX_set_tlsext_ticket_key_cb(SSL_CTX sslctx,
84 \& int (*cb)(SSL *s, unsigned char key_name[16],
85 \& unsigned char iv[EVP_MAX_IV_LENGTH],
86 \& EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc));
87 .Ve
88 .SH DESCRIPTION
89 .IX Header "DESCRIPTION"
90 \&\fBSSL_CTX_set_tlsext_ticket_key_evp_cb()\fR sets a callback function \fIcb\fR for handling
91 session tickets for the ssl context \fIsslctx\fR. Session tickets, defined in
92 RFC5077 provide an enhanced session resumption capability where the server
93 implementation is not required to maintain per session state. It only applies
94 to TLS and there is no SSLv3 implementation.
95 .PP
96 The callback function \fIcb\fR will be called for every client instigated TLS
97 session when session ticket extension is presented in the TLS hello
98 message. It is the responsibility of this function to create or retrieve the
99 cryptographic parameters and to maintain their state.
100 .PP
101 The OpenSSL library uses your callback function to help implement a common TLS
102 ticket construction state according to RFC5077 Section 4 such that per session
103 state is unnecessary and a small set of cryptographic variables needs to be
104 maintained by the callback function implementation.
105 .PP
106 In order to reuse a session, a TLS client must send the session ticket
107 extension to the server. The client must send exactly one session ticket.
108 The server, through the callback function, either agrees to reuse the session
109 ticket information or it starts a full TLS handshake to create a new session
110 ticket.
111 .PP
112 Before the callback function is started \fIctx\fR and \fIhctx\fR have been
113 initialised with \fBEVP_CIPHER_CTX_reset\fR\|(3) and \fBEVP_MAC_CTX_new\fR\|(3)
114 respectively.
115 .PP
116 For new sessions tickets, when the client doesn't present a session ticket, or
117 an attempted retrieval of the ticket failed, or a renew option was indicated,
118 the callback function will be called with \fIenc\fR equal to 1. The OpenSSL
119 library expects that the function will set an arbitrary \fIname\fR, initialize
120 \&\fIiv\fR, and set the cipher context \fIctx\fR and the hash context \fIhctx\fR.
121 .PP
122 The \fIname\fR is 16 characters long and is used as a key identifier.
123 .PP
124 The \fIiv\fR length is the length of the IV of the corresponding cipher. The
125 maximum IV length is \fBEVP_MAX_IV_LENGTH\fR bytes defined in \fI<openssl/evp.h>\fR.
126 .PP
127 The initialization vector \fIiv\fR should be a random value. The cipher context
128 \&\fIctx\fR should use the initialisation vector \fIiv\fR. The cipher context can be
129 set using \fBEVP_EncryptInit_ex\fR\|(3). The hmac context and digest can be set using
130 \&\fBEVP_MAC_CTX_set_params\fR\|(3) with the \fBOSSL_MAC_PARAM_KEY\fR and
131 \&\fBOSSL_MAC_PARAM_DIGEST\fR parameters respectively.
132 .PP
133 When the client presents a session ticket, the callback function with be called
134 with \fIenc\fR set to 0 indicating that the \fIcb\fR function should retrieve a set
135 of parameters. In this case \fIname\fR and \fIiv\fR have already been parsed out of
136 the session ticket. The OpenSSL library expects that the \fIname\fR will be used
137 to retrieve a cryptographic parameters and that the cryptographic context
138 \&\fIctx\fR will be set with the retrieved parameters and the initialization vector
139 \&\fIiv\fR. using a function like \fBEVP_DecryptInit_ex\fR\|(3). The key material and
140 digest for \fIhctx\fR need to be set using \fBEVP_MAC_CTX_set_params\fR\|(3) with the
141 \&\fBOSSL_MAC_PARAM_KEY\fR and \fBOSSL_MAC_PARAM_DIGEST\fR parameters respectively.
142 .PP
143 If the \fIname\fR is still valid but a renewal of the ticket is required the
144 callback function should return 2. The library will call the callback again
145 with an argument of enc equal to 1 to set the new ticket.
146 .PP
147 The return value of the \fIcb\fR function is used by OpenSSL to determine what
148 further processing will occur. The following return values have meaning:
149 .IP 2 4
150 .IX Item "2"
151 This indicates that the \fIctx\fR and \fIhctx\fR have been set and the session can
152 continue on those parameters. Additionally it indicates that the session
153 ticket is in a renewal period and should be replaced. The OpenSSL library will
154 call \fIcb\fR again with an enc argument of 1 to set the new ticket (see RFC5077
155 3.3 paragraph 2).
156 .IP 1 4
157 .IX Item "1"
158 This indicates that the \fIctx\fR and \fIhctx\fR have been set and the session can
159 continue on those parameters.
160 .IP 0 4
161 This indicates that it was not possible to set/retrieve a session ticket and
162 the SSL/TLS session will continue by negotiating a set of cryptographic
163 parameters or using the alternate SSL/TLS resumption mechanism, session ids.
164 .Sp
165 If called with enc equal to 0 the library will call the \fIcb\fR again to get
166 a new set of parameters.
167 .IP "less than 0" 4
168 .IX Item "less than 0"
169 This indicates an error.
170 .PP
171 The \fBSSL_CTX_set_tlsext_ticket_key_cb()\fR function is identical to
172 \&\fBSSL_CTX_set_tlsext_ticket_key_evp_cb()\fR except that it takes a deprecated
173 HMAC_CTX pointer instead of an EVP_MAC_CTX one.
174 Before this callback function is started \fIhctx\fR will have been
175 initialised with \fBEVP_MAC_CTX_new\fR\|(3) and the digest set with
176 \&\fBEVP_MAC_CTX_set_params\fR\|(3).
177 The \fIhctx\fR key material can be set using \fBHMAC_Init_ex\fR\|(3).
178 .SH NOTES
179 .IX Header "NOTES"
180 Session resumption shortcuts the TLS handshake so that the client certificate
181 negotiation doesn't occur. It makes up for this by storing the client certificate
182 and all other negotiated state information encrypted within the ticket. In a
183 resumed session the applications will have all this state information available
184 exactly as if a full negotiation had occurred.
185 .PP
186 If an attacker can obtain the key used to encrypt a session ticket, they can
187 obtain the master secret for any ticket using that key and decrypt any traffic
188 using that session: even if the cipher suite supports forward secrecy. As
189 a result applications may wish to use multiple keys and avoid using long term
190 keys stored in files.
191 .PP
192 Applications can use longer keys to maintain a consistent level of security.
193 For example if a cipher suite uses 256 bit ciphers but only a 128 bit ticket key
194 the overall security is only 128 bits because breaking the ticket key will
195 enable an attacker to obtain the session keys.
196 .SH "RETURN VALUES"
197 .IX Header "RETURN VALUES"
198 Returns 1 to indicate the callback function was set and 0 otherwise.
199 .SH EXAMPLES
200 .IX Header "EXAMPLES"
201 Reference Implementation:
202 .PP
203 .Vb 2
204 \& SSL_CTX_set_tlsext_ticket_key_evp_cb(SSL, ssl_tlsext_ticket_key_cb);
205 \& ...
206 \&
207 \& static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16],
208 \& unsigned char *iv, EVP_CIPHER_CTX *ctx,
209 \& EVP_MAC_CTX *hctx, int enc)
210 \& {
211 \& OSSL_PARAM params[3];
212 \& your_type_t *key; /* something that you need to implement */
213 \&
214 \& if (enc) { /* create new session */
215 \& if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) <= 0)
216 \& return \-1; /* insufficient random */
217 \&
218 \& key = currentkey(); /* something that you need to implement */
219 \& if (key == NULL) {
220 \& /* current key doesn\*(Aqt exist or isn\*(Aqt valid */
221 \& key = createkey(); /*
222 \& * Something that you need to implement.
223 \& * createkey needs to initialise a name,
224 \& * an aes_key, a hmac_key and optionally
225 \& * an expire time.
226 \& */
227 \& if (key == NULL) /* key couldn\*(Aqt be created */
228 \& return 0;
229 \& }
230 \& memcpy(key_name, key\->name, 16);
231 \&
232 \& if (EVP_EncryptInit_ex(&ctx, EVP_aes_256_cbc(), NULL, key\->aes_key,
233 \& iv) == 0)
234 \& return \-1; /* error in cipher initialisation */
235 \&
236 \& params[0] = OSSL_PARAM_construct_octet_string(OSSL_MAC_PARAM_KEY,
237 \& key\->hmac_key, 32);
238 \& params[1] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST,
239 \& "sha256", 0);
240 \& params[2] = OSSL_PARAM_construct_end();
241 \& if (EVP_MAC_CTX_set_params(hctx, params) == 0)
242 \& return \-1; /* error in mac initialisation */
243 \&
244 \& return 1;
245 \&
246 \& } else { /* retrieve session */
247 \& time_t t = time(NULL);
248 \& key = findkey(key_name); /* something that you need to implement */
249 \&
250 \& if (key == NULL || key\->expire < t)
251 \& return 0;
252 \&
253 \& params[0] = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
254 \& key\->hmac_key, 32);
255 \& params[1] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST,
256 \& "sha256", 0);
257 \& params[2] = OSSL_PARAM_construct_end();
258 \& if (EVP_MAC_CTX_set_params(hctx, params) == 0)
259 \& return \-1; /* error in mac initialisation */
260 \&
261 \& if (EVP_DecryptInit_ex(&ctx, EVP_aes_256_cbc(), NULL, key\->aes_key,
262 \& iv) == 0)
263 \& return \-1; /* error in cipher initialisation */
264 \&
265 \& if (key\->expire < t \- RENEW_TIME) { /* RENEW_TIME: implement */
266 \& /*
267 \& * return 2 \- This session will get a new ticket even though the
268 \& * current one is still valid.
269 \& */
270 \& return 2;
271 \& }
272 \& return 1;
273 \& }
274 \& }
275 .Ve
276 .SH "SEE ALSO"
277 .IX Header "SEE ALSO"
278 \&\fBssl\fR\|(7), \fBSSL_set_session\fR\|(3),
279 \&\fBSSL_session_reused\fR\|(3),
280 \&\fBSSL_CTX_add_session\fR\|(3),
281 \&\fBSSL_CTX_sess_number\fR\|(3),
282 \&\fBSSL_CTX_sess_set_get_cb\fR\|(3),
283 \&\fBSSL_CTX_set_session_id_context\fR\|(3),
284 .SH HISTORY
285 .IX Header "HISTORY"
286 The \fBSSL_CTX_set_tlsext_ticket_key_cb()\fR function was deprecated in OpenSSL 3.0.
287 .PP
288 The \fBSSL_CTX_set_tlsext_ticket_key_evp_cb()\fR function was introduced in
289 OpenSSL 3.0.
290 .SH COPYRIGHT
291 .IX Header "COPYRIGHT"
292 Copyright 2014\-2024 The OpenSSL Project Authors. All Rights Reserved.
293 .PP
294 Licensed under the Apache License 2.0 (the "License"). You may not use
295 this file except in compliance with the License. You can obtain a copy
296 in the file LICENSE in the source distribution or at
297 <https://www.openssl.org/source/license.html>.