1SSL_CTX_SET_SESSION_TICKET_CB(3)    OpenSSL   SSL_CTX_SET_SESSION_TICKET_CB(3)
2
3
4

NAME

6       SSL_CTX_set_session_ticket_cb, SSL_SESSION_get0_ticket_appdata,
7       SSL_SESSION_set1_ticket_appdata, SSL_CTX_generate_session_ticket_fn,
8       SSL_CTX_decrypt_session_ticket_fn - manage session ticket application
9       data
10

SYNOPSIS

12        #include <openssl/ssl.h>
13
14        typedef int (*SSL_CTX_generate_session_ticket_fn)(SSL *s, void *arg);
15        typedef SSL_TICKET_RETURN (*SSL_CTX_decrypt_session_ticket_fn)(SSL *s, SSL_SESSION *ss,
16                                                                       const unsigned char *keyname,
17                                                                       size_t keyname_len,
18                                                                       SSL_TICKET_STATUS status,
19                                                                       void *arg);
20        int SSL_CTX_set_session_ticket_cb(SSL_CTX *ctx,
21                                          SSL_CTX_generate_session_ticket_fn gen_cb,
22                                          SSL_CTX_decrypt_session_ticket_fn dec_cb,
23                                          void *arg);
24        int SSL_SESSION_set1_ticket_appdata(SSL_SESSION *ss, const void *data, size_t len);
25        int SSL_SESSION_get0_ticket_appdata(SSL_SESSION *ss, void **data, size_t *len);
26

DESCRIPTION

28       SSL_CTX_set_set_session_ticket_cb() sets the application callbacks
29       gen_cb and dec_cb that are used by a server to set and get application
30       data stored with a session, and placed into a session ticket. Either
31       callback function may be set to NULL. The value of arg is passed to the
32       callbacks.
33
34       gen_cb is the application defined callback invoked when a session
35       ticket is about to be created. The application can call
36       SSL_SESSION_set1_ticket_appdata() at this time to add application data
37       to the session ticket. The value of arg is the same as that given to
38       SSL_CTX_set_session_ticket_cb(). The gen_cb callback is defined as type
39       SSL_CTX_generate_session_ticket_fn.
40
41       dec_cb is the application defined callback invoked after session ticket
42       decryption has been attempted and any session ticket application data
43       is available. If ticket decryption was successful then the ss argument
44       contains the session data. The keyname and keyname_len arguments
45       identify the key used to decrypt the session ticket. The status
46       argument is the result of the ticket decryption. See the NOTES section
47       below for further details. The value of arg is the same as that given
48       to SSL_CTX_set_session_ticket_cb(). The dec_cb callback is defined as
49       type SSL_CTX_decrypt_session_ticket_fn.
50
51       SSL_SESSION_set1_ticket_appdata() sets the application data specified
52       by data and len into ss which is then placed into any generated session
53       tickets. It can be called at any time before a session ticket is
54       created to update the data placed into the session ticket. However,
55       given that sessions and tickets are created by the handshake, the
56       gen_cb is provided to notify the application that a session ticket is
57       about to be generated.
58
59       SSL_SESSION_get0_ticket_appdata() assigns data to the session ticket
60       application data and assigns len to the length of the session ticket
61       application data from ss. The application data can be set via
62       SSL_SESSION_set1_ticket_appdata() or by a session ticket. NULL will be
63       assigned to data and 0 will be assigned to len if there is no session
64       ticket application data. SSL_SESSION_get0_ticket_appdata() can be
65       called any time after a session has been created. The dec_cb is
66       provided to notify the application that a session ticket has just been
67       decrypted.
68

NOTES

70       When the dec_cb callback is invoked, the SSL_SESSION ss has not yet
71       been assigned to the SSL s. The status indicates the result of the
72       ticket decryption. The callback must check the status value before
73       performing any action, as it is called even if ticket decryption fails.
74
75       The keyname and keyname_len arguments to dec_cb may be used to identify
76       the key that was used to encrypt the session ticket.
77
78       The status argument can be any of these values:
79
80       SSL_TICKET_EMPTY
81           Empty ticket present. No ticket data will be used and a new ticket
82           should be sent to the client. This only occurs in TLSv1.2 or below.
83           In TLSv1.3 it is not valid for a client to send an empty ticket.
84
85       SSL_TICKET_NO_DECRYPT
86           The ticket couldn't be decrypted. No ticket data will be used and a
87           new ticket should be sent to the client.
88
89       SSL_TICKET_SUCCESS
90           A ticket was successfully decrypted, any session ticket application
91           data should be available. A new ticket should not be sent to the
92           client.
93
94       SSL_TICKET_SUCCESS_RENEW
95           Same as SSL_TICKET_SUCCESS, but a new ticket should be sent to the
96           client.
97
98       The return value can be any of these values:
99
100       SSL_TICKET_RETURN_ABORT
101           The handshake should be aborted, either because of an error or
102           because of some policy. Note that in TLSv1.3 a client may send more
103           than one ticket in a single handshake. Therefore just because one
104           ticket is unacceptable it does not mean that all of them are. For
105           this reason this option should be used with caution.
106
107       SSL_TICKET_RETURN_IGNORE
108           Do not use a ticket (if one was available). Do not send a renewed
109           ticket to the client.
110
111       SSL_TICKET_RETURN_IGNORE_RENEW
112           Do not use a ticket (if one was available). Send a renewed ticket
113           to the client.
114
115           If the callback does not wish to change the default ticket
116           behaviour then it should return this value if status is
117           SSL_TICKET_EMPTY or SSL_TICKET_NO_DECRYPT.
118
119       SSL_TICKET_RETURN_USE
120           Use the ticket. Do not send a renewed ticket to the client. It is
121           an error for the callback to return this value if status has a
122           value other than SSL_TICKET_SUCCESS or SSL_TICKET_SUCCESS_RENEW.
123
124           If the callback does not wish to change the default ticket
125           behaviour then it should return this value if status is
126           SSL_TICKET_SUCCESS.
127
128       SSL_TICKET_RETURN_USE_RENEW
129           Use the ticket. Send a renewed ticket to the client. It is an error
130           for the callback to return this value if status has a value other
131           than SSL_TICKET_SUCCESS or SSL_TICKET_SUCCESS_RENEW.
132
133           If the callback does not wish to change the default ticket
134           behaviour then it should return this value if status is
135           SSL_TICKET_SUCCESS_RENEW.
136
137       If status has the value SSL_TICKET_EMPTY or SSL_TICKET_NO_DECRYPT then
138       no session data will be available and the callback must not use the ss
139       argument. If status has the value SSL_TICKET_SUCCESS or
140       SSL_TICKET_SUCCESS_RENEW then the application can call
141       SSL_SESSION_get0_ticket_appdata() using the session provided in the ss
142       argument to retrieve the application data.
143
144       When the gen_cb callback is invoked, the SSL_get_session() function can
145       be used to retrieve the SSL_SESSION for
146       SSL_SESSION_set1_ticket_appdata().
147
148       By default, in TLSv1.2 and below, a new session ticket is not issued on
149       a successful resumption and therefore gen_cb will not be called. In
150       TLSv1.3 the default behaviour is to always issue a new ticket on
151       resumption. In both cases this behaviour can be changed if a ticket key
152       callback is in use (see SSL_CTX_set_tlsext_ticket_key_cb(3)).
153

RETURN VALUES

155       The SSL_CTX_set_session_ticket_cb(), SSL_SESSION_set1_ticket_appdata()
156       and SSL_SESSION_get0_ticket_appdata() functions return 1 on success and
157       0 on failure.
158
159       The gen_cb callback must return 1 to continue the connection. A return
160       of 0 will terminate the connection with an INTERNAL_ERROR alert.
161
162       The dec_cb callback must return a value as described in NOTES above.
163

SEE ALSO

165       ssl(7), SSL_get_session(3)
166

HISTORY

168       The SSL_CTX_set_session_ticket_cb(), SSSL_SESSION_set1_ticket_appdata()
169       and SSL_SESSION_get_ticket_appdata() functions were added in OpenSSL
170       1.1.1.
171
173       Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
174
175       Licensed under the OpenSSL license (the "License").  You may not use
176       this file except in compliance with the License.  You can obtain a copy
177       in the file LICENSE in the source distribution or at
178       <https://www.openssl.org/source/license.html>.
179
180
181
1821.1.1d                            2019-10-03  SSL_CTX_SET_SESSION_TICKET_CB(3)
Impressum