1SSL_CTX_SET_SESSION_TICKET_CB(3) OpenSSL SSL_CTX_SET_SESSION_TICKET_CB(3)
2
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
12 #include <openssl/ssl.h>
13 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
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 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 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 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 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
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 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 The status argument can be any of these values:
79 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 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 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 SSL_TICKET_SUCCESS_RENEW
95 Same as SSL_TICKET_SUCCESS, but a new ticket should be sent to the
96 client.
97 The return value can be any of these values:
99 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 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 SSL_TICKET_RETURN_IGNORE_RENEW
112 Do not use a ticket (if one was available). Send a renewed ticket
113 to the client.
114 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 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 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 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 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 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 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 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
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 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 The dec_cb callback must return a value as described in NOTES above.
163
165 ssl(7), SSL_get_session(3)
166
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 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>.
1791.1.1g 2020-04-23 SSL_CTX_SET_SESSION_TICKET_CB(3)