1=pod 2 3=head1 NAME 4 5SSL_CTX_set_session_ticket_cb, 6SSL_SESSION_get0_ticket_appdata, 7SSL_SESSION_set1_ticket_appdata, 8SSL_CTX_generate_session_ticket_fn, 9SSL_CTX_decrypt_session_ticket_fn - manage session ticket application data 10 11=head1 SYNOPSIS 12 13 #include <openssl/ssl.h> 14 15 typedef int (*SSL_CTX_generate_session_ticket_fn)(SSL *s, void *arg); 16 typedef SSL_TICKET_RETURN (*SSL_CTX_decrypt_session_ticket_fn)(SSL *s, SSL_SESSION *ss, 17 const unsigned char *keyname, 18 size_t keyname_len, 19 SSL_TICKET_STATUS status, 20 void *arg); 21 int SSL_CTX_set_session_ticket_cb(SSL_CTX *ctx, 22 SSL_CTX_generate_session_ticket_fn gen_cb, 23 SSL_CTX_decrypt_session_ticket_fn dec_cb, 24 void *arg); 25 int SSL_SESSION_set1_ticket_appdata(SSL_SESSION *ss, const void *data, size_t len); 26 int SSL_SESSION_get0_ticket_appdata(SSL_SESSION *ss, void **data, size_t *len); 27 28=head1 DESCRIPTION 29 30SSL_CTX_set_set_session_ticket_cb() sets the application callbacks B<gen_cb> 31and B<dec_cb> that are used by a server to set and get application data stored 32with a session, and placed into a session ticket. Either callback function may 33be set to NULL. The value of B<arg> is passed to the callbacks. 34 35B<gen_cb> is the application defined callback invoked when a session ticket is 36about to be created. The application can call SSL_SESSION_set1_ticket_appdata() 37at this time to add application data to the session ticket. The value of B<arg> 38is the same as that given to SSL_CTX_set_session_ticket_cb(). The B<gen_cb> 39callback is defined as type B<SSL_CTX_generate_session_ticket_fn>. 40 41B<dec_cb> is the application defined callback invoked after session ticket 42decryption has been attempted and any session ticket application data is 43available. If ticket decryption was successful then the B<ss> argument contains 44the session data. The B<keyname> and B<keyname_len> arguments identify the key 45used to decrypt the session ticket. The B<status> argument is the result of the 46ticket decryption. See the L<NOTES> section below for further details. The value 47of B<arg> is the same as that given to SSL_CTX_set_session_ticket_cb(). The 48B<dec_cb> callback is defined as type B<SSL_CTX_decrypt_session_ticket_fn>. 49 50SSL_SESSION_set1_ticket_appdata() sets the application data specified by 51B<data> and B<len> into B<ss> which is then placed into any generated session 52tickets. It can be called at any time before a session ticket is created to 53update the data placed into the session ticket. However, given that sessions 54and tickets are created by the handshake, the B<gen_cb> is provided to notify 55the application that a session ticket is about to be generated. 56 57SSL_SESSION_get0_ticket_appdata() assigns B<data> to the session ticket 58application data and assigns B<len> to the length of the session ticket 59application data from B<ss>. The application data can be set via 60SSL_SESSION_set1_ticket_appdata() or by a session ticket. NULL will be assigned 61to B<data> and 0 will be assigned to B<len> if there is no session ticket 62application data. SSL_SESSION_get0_ticket_appdata() can be called any time 63after a session has been created. The B<dec_cb> is provided to notify the 64application that a session ticket has just been decrypted. 65 66=head1 NOTES 67 68When the B<dec_cb> callback is invoked, the SSL_SESSION B<ss> has not yet been 69assigned to the SSL B<s>. The B<status> indicates the result of the ticket 70decryption. The callback must check the B<status> value before performing any 71action, as it is called even if ticket decryption fails. 72 73The B<keyname> and B<keyname_len> arguments to B<dec_cb> may be used to identify 74the key that was used to encrypt the session ticket. 75 76The B<status> argument can be any of these values: 77 78=over 4 79 80=item SSL_TICKET_EMPTY 81 82Empty ticket present. No ticket data will be used and a new ticket should be 83sent to the client. This only occurs in TLSv1.2 or below. In TLSv1.3 it is not 84valid for a client to send an empty ticket. 85 86=item SSL_TICKET_NO_DECRYPT 87 88The ticket couldn't be decrypted. No ticket data will be used and a new ticket 89should be sent to the client. 90 91=item SSL_TICKET_SUCCESS 92 93A ticket was successfully decrypted, any session ticket application data should 94be available. A new ticket should not be sent to the client. 95 96=item SSL_TICKET_SUCCESS_RENEW 97 98Same as B<SSL_TICKET_SUCCESS>, but a new ticket should be sent to the client. 99 100=back 101 102The return value can be any of these values: 103 104=over 4 105 106=item SSL_TICKET_RETURN_ABORT 107 108The handshake should be aborted, either because of an error or because of some 109policy. Note that in TLSv1.3 a client may send more than one ticket in a single 110handshake. Therefore, just because one ticket is unacceptable it does not mean 111that all of them are. For this reason this option should be used with caution. 112 113=item SSL_TICKET_RETURN_IGNORE 114 115Do not use a ticket (if one was available). Do not send a renewed ticket to the 116client. 117 118=item SSL_TICKET_RETURN_IGNORE_RENEW 119 120Do not use a ticket (if one was available). Send a renewed ticket to the client. 121 122If the callback does not wish to change the default ticket behaviour then it 123should return this value if B<status> is B<SSL_TICKET_EMPTY> or 124B<SSL_TICKET_NO_DECRYPT>. 125 126=item SSL_TICKET_RETURN_USE 127 128Use the ticket. Do not send a renewed ticket to the client. It is an error for 129the callback to return this value if B<status> has a value other than 130B<SSL_TICKET_SUCCESS> or B<SSL_TICKET_SUCCESS_RENEW>. 131 132If the callback does not wish to change the default ticket behaviour then it 133should return this value if B<status> is B<SSL_TICKET_SUCCESS>. 134 135=item SSL_TICKET_RETURN_USE_RENEW 136 137Use the ticket. Send a renewed ticket to the client. It is an error for the 138callback to return this value if B<status> has a value other than 139B<SSL_TICKET_SUCCESS> or B<SSL_TICKET_SUCCESS_RENEW>. 140 141If the callback does not wish to change the default ticket behaviour then it 142should return this value if B<status> is B<SSL_TICKET_SUCCESS_RENEW>. 143 144=back 145 146If B<status> has the value B<SSL_TICKET_EMPTY> or B<SSL_TICKET_NO_DECRYPT> then 147no session data will be available and the callback must not use the B<ss> 148argument. If B<status> has the value B<SSL_TICKET_SUCCESS> or 149B<SSL_TICKET_SUCCESS_RENEW> then the application can call 150SSL_SESSION_get0_ticket_appdata() using the session provided in the B<ss> 151argument to retrieve the application data. 152 153When the B<gen_cb> callback is invoked, the SSL_get_session() function can be 154used to retrieve the SSL_SESSION for SSL_SESSION_set1_ticket_appdata(). 155 156By default, in TLSv1.2 and below, a new session ticket is not issued on a 157successful resumption and therefore B<gen_cb> will not be called. In TLSv1.3 the 158default behaviour is to always issue a new ticket on resumption. In both cases 159this behaviour can be changed if a ticket key callback is in use (see 160L<SSL_CTX_set_tlsext_ticket_key_cb(3)>). 161 162=head1 RETURN VALUES 163 164The SSL_CTX_set_session_ticket_cb(), SSL_SESSION_set1_ticket_appdata() and 165SSL_SESSION_get0_ticket_appdata() functions return 1 on success and 0 on 166failure. 167 168The B<gen_cb> callback must return 1 to continue the connection. A return of 0 169will terminate the connection with an INTERNAL_ERROR alert. 170 171The B<dec_cb> callback must return a value as described in L<NOTES> above. 172 173=head1 SEE ALSO 174 175L<ssl(7)>, 176L<SSL_get_session(3)> 177 178=head1 HISTORY 179 180The SSL_CTX_set_session_ticket_cb(), SSL_SESSION_set1_ticket_appdata() 181and SSL_SESSION_get_ticket_appdata() functions were added in OpenSSL 1.1.1. 182 183=head1 COPYRIGHT 184 185Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved. 186 187Licensed under the OpenSSL license (the "License"). You may not use 188this file except in compliance with the License. You can obtain a copy 189in the file LICENSE in the source distribution or at 190L<https://www.openssl.org/source/license.html>. 191 192=cut 193