Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_set_session_ticket_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_SESSION_TICKET_CB 3SSL"
58 .TH SSL_CTX_SET_SESSION_TICKET_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_session_ticket_cb,
65 SSL_SESSION_get0_ticket_appdata,
66 SSL_SESSION_set1_ticket_appdata,
67 SSL_CTX_generate_session_ticket_fn,
68 SSL_CTX_decrypt_session_ticket_fn \- manage session ticket application data
69 .SH SYNOPSIS
70 .IX Header "SYNOPSIS"
71 .Vb 1
72 \& #include <openssl/ssl.h>
73 \&
74 \& typedef int (*SSL_CTX_generate_session_ticket_fn)(SSL *s, void *arg);
75 \& typedef SSL_TICKET_RETURN (*SSL_CTX_decrypt_session_ticket_fn)(SSL *s, SSL_SESSION *ss,
76 \& const unsigned char *keyname,
77 \& size_t keyname_len,
78 \& SSL_TICKET_STATUS status,
79 \& void *arg);
80 \& int SSL_CTX_set_session_ticket_cb(SSL_CTX *ctx,
81 \& SSL_CTX_generate_session_ticket_fn gen_cb,
82 \& SSL_CTX_decrypt_session_ticket_fn dec_cb,
83 \& void *arg);
84 \& int SSL_SESSION_set1_ticket_appdata(SSL_SESSION *ss, const void *data, size_t len);
85 \& int SSL_SESSION_get0_ticket_appdata(SSL_SESSION *ss, void **data, size_t *len);
86 .Ve
87 .SH DESCRIPTION
88 .IX Header "DESCRIPTION"
89 \&\fBSSL_CTX_set_set_session_ticket_cb()\fR sets the application callbacks \fBgen_cb\fR
90 and \fBdec_cb\fR that are used by a server to set and get application data stored
91 with a session, and placed into a session ticket. Either callback function may
92 be set to NULL. The value of \fBarg\fR is passed to the callbacks.
93 .PP
94 \&\fBgen_cb\fR is the application defined callback invoked when a session ticket is
95 about to be created. The application can call \fBSSL_SESSION_set1_ticket_appdata()\fR
96 at this time to add application data to the session ticket. The value of \fBarg\fR
97 is the same as that given to \fBSSL_CTX_set_session_ticket_cb()\fR. The \fBgen_cb\fR
98 callback is defined as type \fBSSL_CTX_generate_session_ticket_fn\fR.
99 .PP
100 \&\fBdec_cb\fR is the application defined callback invoked after session ticket
101 decryption has been attempted and any session ticket application data is
102 available. If ticket decryption was successful then the \fBss\fR argument contains
103 the session data. The \fBkeyname\fR and \fBkeyname_len\fR arguments identify the key
104 used to decrypt the session ticket. The \fBstatus\fR argument is the result of the
105 ticket decryption. See the "NOTES" section below for further details. The value
106 of \fBarg\fR is the same as that given to \fBSSL_CTX_set_session_ticket_cb()\fR. The
107 \&\fBdec_cb\fR callback is defined as type \fBSSL_CTX_decrypt_session_ticket_fn\fR.
108 .PP
109 \&\fBSSL_SESSION_set1_ticket_appdata()\fR sets the application data specified by
110 \&\fBdata\fR and \fBlen\fR into \fBss\fR which is then placed into any generated session
111 tickets. It can be called at any time before a session ticket is created to
112 update the data placed into the session ticket. However, given that sessions
113 and tickets are created by the handshake, the \fBgen_cb\fR is provided to notify
114 the application that a session ticket is about to be generated.
115 .PP
116 \&\fBSSL_SESSION_get0_ticket_appdata()\fR assigns \fBdata\fR to the session ticket
117 application data and assigns \fBlen\fR to the length of the session ticket
118 application data from \fBss\fR. The application data can be set via
119 \&\fBSSL_SESSION_set1_ticket_appdata()\fR or by a session ticket. NULL will be assigned
120 to \fBdata\fR and 0 will be assigned to \fBlen\fR if there is no session ticket
121 application data. \fBSSL_SESSION_get0_ticket_appdata()\fR can be called any time
122 after a session has been created. The \fBdec_cb\fR is provided to notify the
123 application that a session ticket has just been decrypted.
124 .SH NOTES
125 .IX Header "NOTES"
126 When the \fBdec_cb\fR callback is invoked, the SSL_SESSION \fBss\fR has not yet been
127 assigned to the SSL \fBs\fR. The \fBstatus\fR indicates the result of the ticket
128 decryption. The callback must check the \fBstatus\fR value before performing any
129 action, as it is called even if ticket decryption fails.
130 .PP
131 The \fBkeyname\fR and \fBkeyname_len\fR arguments to \fBdec_cb\fR may be used to identify
132 the key that was used to encrypt the session ticket.
133 .PP
134 The \fBstatus\fR argument can be any of these values:
135 .IP SSL_TICKET_EMPTY 4
136 .IX Item "SSL_TICKET_EMPTY"
137 Empty ticket present. No ticket data will be used and a new ticket should be
138 sent to the client. This only occurs in TLSv1.2 or below. In TLSv1.3 it is not
139 valid for a client to send an empty ticket.
140 .IP SSL_TICKET_NO_DECRYPT 4
141 .IX Item "SSL_TICKET_NO_DECRYPT"
142 The ticket couldn't be decrypted. No ticket data will be used and a new ticket
143 should be sent to the client.
144 .IP SSL_TICKET_SUCCESS 4
145 .IX Item "SSL_TICKET_SUCCESS"
146 A ticket was successfully decrypted, any session ticket application data should
147 be available. A new ticket should not be sent to the client.
148 .IP SSL_TICKET_SUCCESS_RENEW 4
149 .IX Item "SSL_TICKET_SUCCESS_RENEW"
150 Same as \fBSSL_TICKET_SUCCESS\fR, but a new ticket should be sent to the client.
151 .PP
152 The return value can be any of these values:
153 .IP SSL_TICKET_RETURN_ABORT 4
154 .IX Item "SSL_TICKET_RETURN_ABORT"
155 The handshake should be aborted, either because of an error or because of some
156 policy. Note that in TLSv1.3 a client may send more than one ticket in a single
157 handshake. Therefore, just because one ticket is unacceptable it does not mean
158 that all of them are. For this reason this option should be used with caution.
159 .IP SSL_TICKET_RETURN_IGNORE 4
160 .IX Item "SSL_TICKET_RETURN_IGNORE"
161 Do not use a ticket (if one was available). Do not send a renewed ticket to the
162 client.
163 .IP SSL_TICKET_RETURN_IGNORE_RENEW 4
164 .IX Item "SSL_TICKET_RETURN_IGNORE_RENEW"
165 Do not use a ticket (if one was available). Send a renewed ticket to the client.
166 .Sp
167 If the callback does not wish to change the default ticket behaviour then it
168 should return this value if \fBstatus\fR is \fBSSL_TICKET_EMPTY\fR or
169 \&\fBSSL_TICKET_NO_DECRYPT\fR.
170 .IP SSL_TICKET_RETURN_USE 4
171 .IX Item "SSL_TICKET_RETURN_USE"
172 Use the ticket. Do not send a renewed ticket to the client. It is an error for
173 the callback to return this value if \fBstatus\fR has a value other than
174 \&\fBSSL_TICKET_SUCCESS\fR or \fBSSL_TICKET_SUCCESS_RENEW\fR.
175 .Sp
176 If the callback does not wish to change the default ticket behaviour then it
177 should return this value if \fBstatus\fR is \fBSSL_TICKET_SUCCESS\fR.
178 .IP SSL_TICKET_RETURN_USE_RENEW 4
179 .IX Item "SSL_TICKET_RETURN_USE_RENEW"
180 Use the ticket. Send a renewed ticket to the client. It is an error for the
181 callback to return this value if \fBstatus\fR has a value other than
182 \&\fBSSL_TICKET_SUCCESS\fR or \fBSSL_TICKET_SUCCESS_RENEW\fR.
183 .Sp
184 If the callback does not wish to change the default ticket behaviour then it
185 should return this value if \fBstatus\fR is \fBSSL_TICKET_SUCCESS_RENEW\fR.
186 .PP
187 If \fBstatus\fR has the value \fBSSL_TICKET_EMPTY\fR or \fBSSL_TICKET_NO_DECRYPT\fR then
188 no session data will be available and the callback must not use the \fBss\fR
189 argument. If \fBstatus\fR has the value \fBSSL_TICKET_SUCCESS\fR or
190 \&\fBSSL_TICKET_SUCCESS_RENEW\fR then the application can call
191 \&\fBSSL_SESSION_get0_ticket_appdata()\fR using the session provided in the \fBss\fR
192 argument to retrieve the application data.
193 .PP
194 When the \fBgen_cb\fR callback is invoked, the \fBSSL_get_session()\fR function can be
195 used to retrieve the SSL_SESSION for \fBSSL_SESSION_set1_ticket_appdata()\fR.
196 .PP
197 By default, in TLSv1.2 and below, a new session ticket is not issued on a
198 successful resumption and therefore \fBgen_cb\fR will not be called. In TLSv1.3 the
199 default behaviour is to always issue a new ticket on resumption. In both cases
200 this behaviour can be changed if a ticket key callback is in use (see
201 \&\fBSSL_CTX_set_tlsext_ticket_key_cb\fR\|(3)).
202 .SH "RETURN VALUES"
203 .IX Header "RETURN VALUES"
204 The \fBSSL_CTX_set_session_ticket_cb()\fR, \fBSSL_SESSION_set1_ticket_appdata()\fR and
205 \&\fBSSL_SESSION_get0_ticket_appdata()\fR functions return 1 on success and 0 on
206 failure.
207 .PP
208 The \fBgen_cb\fR callback must return 1 to continue the connection. A return of 0
209 will terminate the connection with an INTERNAL_ERROR alert.
210 .PP
211 The \fBdec_cb\fR callback must return a value as described in "NOTES" above.
212 .SH "SEE ALSO"
213 .IX Header "SEE ALSO"
214 \&\fBssl\fR\|(7),
215 \&\fBSSL_get_session\fR\|(3)
216 .SH HISTORY
217 .IX Header "HISTORY"
218 The \fBSSL_CTX_set_session_ticket_cb()\fR, \fBSSL_SESSION_set1_ticket_appdata()\fR
219 and \fBSSL_SESSION_get_ticket_appdata()\fR functions were added in OpenSSL 1.1.1.
220 .SH COPYRIGHT
221 .IX Header "COPYRIGHT"
222 Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved.
223 .PP
224 Licensed under the Apache License 2.0 (the "License"). You may not use
225 this file except in compliance with the License. You can obtain a copy
226 in the file LICENSE in the source distribution or at
227 <https://www.openssl.org/source/license.html>.