1.\" $OpenBSD: SSL_CTX_set_tlsext_ticket_key_cb.3,v 1.8 2022/01/25 18:01:20 tb Exp $ 2.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 3.\" 4.\" This file was written by Rich Salz <rsalz@akamai.com> 5.\" Copyright (c) 2014, 2015, 2016 The OpenSSL Project. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in 16.\" the documentation and/or other materials provided with the 17.\" distribution. 18.\" 19.\" 3. All advertising materials mentioning features or use of this 20.\" software must display the following acknowledgment: 21.\" "This product includes software developed by the OpenSSL Project 22.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 23.\" 24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 25.\" endorse or promote products derived from this software without 26.\" prior written permission. For written permission, please contact 27.\" openssl-core@openssl.org. 28.\" 29.\" 5. Products derived from this software may not be called "OpenSSL" 30.\" nor may "OpenSSL" appear in their names without prior written 31.\" permission of the OpenSSL Project. 32.\" 33.\" 6. Redistributions of any form whatsoever must retain the following 34.\" acknowledgment: 35.\" "This product includes software developed by the OpenSSL Project 36.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 37.\" 38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 41.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 49.\" OF THE POSSIBILITY OF SUCH DAMAGE. 50.\" 51.Dd $Mdocdate: January 25 2022 $ 52.Dt SSL_CTX_SET_TLSEXT_TICKET_KEY_CB 3 53.Os 54.Sh NAME 55.Nm SSL_CTX_set_tlsext_ticket_key_cb 56.Nd set a callback for session ticket processing 57.Sh SYNOPSIS 58.In openssl/tls1.h 59.Ft long 60.Fo SSL_CTX_set_tlsext_ticket_key_cb 61.Fa "SSL_CTX sslctx" 62.Fa "int (*cb)(SSL *s, unsigned char key_name[16],\ 63 unsigned char iv[EVP_MAX_IV_LENGTH],\ 64 EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc)" 65.Fc 66.Sh DESCRIPTION 67.Fn SSL_CTX_set_tlsext_ticket_key_cb 68sets a callback function 69.Fa cb 70for handling session tickets for the ssl context 71.Fa sslctx . 72Session tickets, defined in RFC 5077, provide an enhanced session 73resumption capability where the server implementation is not required to 74maintain per session state. 75.Pp 76The callback function 77.Fa cb 78will be called for every client instigated TLS session when session 79ticket extension is presented in the TLS hello message. 80It is the responsibility of this function to create or retrieve the 81cryptographic parameters and to maintain their state. 82.Pp 83The OpenSSL library uses the callback function to help implement a 84common TLS ticket construction state according to RFC 5077 Section 4 such 85that per session state is unnecessary and a small set of cryptographic 86variables needs to be maintained by the callback function 87implementation. 88.Pp 89In order to reuse a session, a TLS client must send a session ticket 90extension to the server. 91The client can only send exactly one session ticket. 92The server, through the callback function, either agrees to reuse the 93session ticket information or it starts a full TLS handshake to create a 94new session ticket. 95.Pp 96The callback is called with 97.Fa ctx 98and 99.Fa hctx 100which were newly allocated with 101.Xr EVP_CIPHER_CTX_new 3 102and 103.Xr HMAC_CTX_new 3 , 104respectively. 105.Pp 106For new sessions tickets, when the client doesn't present a session 107ticket, or an attempted retrieval of the ticket failed, or a renew 108option was indicated, the callback function will be called with 109.Fa enc 110equal to 1. 111The OpenSSL library expects that the function will set an arbitrary 112.Fa key_name , 113initialize 114.Fa iv , 115and set the cipher context 116.Fa ctx 117and the hash context 118.Fa hctx . 119.Pp 120The 121.Fa key_name 122is 16 characters long and is used as a key identifier. 123.Pp 124The 125.Fa iv 126length is the length of the IV of the corresponding cipher. 127The maximum IV length is 128.Dv EVP_MAX_IV_LENGTH 129bytes defined in 130.In openssl/evp.h . 131.Pp 132The initialization vector 133.Fa iv 134should be a random value. 135The cipher context 136.Fa ctx 137should use the initialisation vector 138.Fa iv . 139The cipher context can be set using 140.Xr EVP_EncryptInit_ex 3 . 141The hmac context can be set using 142.Xr HMAC_Init_ex 3 . 143.Pp 144When the client presents a session ticket, the callback function 145with be called with 146.Fa enc 147set to 0 indicating that the 148.Fa cb 149function should retrieve a set of parameters. 150In this case 151.Fa key_name 152and 153.Fa iv 154have already been parsed out of the session ticket. 155The OpenSSL library expects that the 156.Em key_name 157will be used to retrieve a cryptographic parameters and that the 158cryptographic context 159.Fa ctx 160will be set with the retrieved parameters and the initialization vector 161.Fa iv 162using a function like 163.Xr EVP_DecryptInit_ex 3 . 164The 165.Fa hctx 166needs to be set using 167.Xr HMAC_Init_ex 3 . 168.Pp 169If the 170.Fa key_name 171is still valid but a renewal of the ticket is required, the callback 172function should return 2. 173The library will call the callback again with an argument of 174.Fa enc 175equal to 1 to set the new ticket. 176.Pp 177The return value of the 178.Fa cb 179function is used by OpenSSL to determine what further processing will 180occur. 181The following return values have meaning: 182.Bl -tag -width Ds 183.It 2 184This indicates that the 185.Fa ctx 186and 187.Fa hctx 188have been set and the session can continue on those parameters. 189Additionally it indicates that the session ticket is in a renewal period 190and should be replaced. 191The OpenSSL library will call 192.Fa cb 193again with an 194.Fa enc 195argument of 1 to set the new ticket (see RFC 5077 3.3 paragraph 2). 196.It 1 197This indicates that the 198.Fa ctx 199and 200.Fa hctx 201have been set and the session can continue on those parameters. 202.It 0 203This indicates that it was not possible to set/retrieve a session ticket 204and the SSL/TLS session will continue by negotiating a set of 205cryptographic parameters or using the alternate SSL/TLS resumption 206mechanism, session ids. 207.Pp 208If called with 209.Fa enc 210equal to 0, the library will call the 211.Fa cb 212again to get a new set of parameters. 213.It less than 0 214This indicates an error. 215.El 216.Pp 217Session resumption shortcuts the TLS so that the client certificate 218negotiation don't occur. 219It makes up for this by storing client certificate and all other 220negotiated state information encrypted within the ticket. 221In a resumed session the applications will have all this state 222information available exactly as if a full negotiation had occurred. 223.Pp 224If an attacker can obtain the key used to encrypt a session ticket, they 225can obtain the master secret for any ticket using that key and decrypt 226any traffic using that session: even if the ciphersuite supports forward 227secrecy. 228As a result applications may wish to use multiple keys and avoid using 229long term keys stored in files. 230.Pp 231Applications can use longer keys to maintain a consistent level of 232security. 233For example if a ciphersuite uses 256 bit ciphers but only a 128 bit 234ticket key the overall security is only 128 bits because breaking the 235ticket key will enable an attacker to obtain the session keys. 236.Sh RETURN VALUES 237This function returns 0 to indicate that the callback function was set. 238.Sh EXAMPLES 239Reference Implementation: 240.Bd -literal 241SSL_CTX_set_tlsext_ticket_key_cb(SSL, ssl_tlsext_ticket_key_cb); 242\&.... 243static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16], 244 unsigned char *iv, EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc) 245{ 246 if (enc) { /* create new session */ 247 if (RAND_bytes(iv, EVP_MAX_IV_LENGTH)) 248 return -1; /* insufficient random */ 249 250 key = currentkey(); /* something you need to implement */ 251 if (!key) { 252 /* current key doesn't exist or isn't valid */ 253 key = createkey(); 254 /* something that you need to implement. 255 * createkey needs to initialise a name, 256 * an aes_key, a hmac_key, and optionally 257 * an expire time. */ 258 if (!key) /* key couldn't be created */ 259 return 0; 260 } 261 memcpy(key_name, key->name, 16); 262 263 EVP_EncryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, 264 key->aes_key, iv); 265 HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL); 266 267 return 1; 268 269 } else { /* retrieve session */ 270 key = findkey(name); 271 272 if (!key || key->expire < now()) 273 return 0; 274 275 HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL); 276 EVP_DecryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, 277 key->aes_key, iv ); 278 279 if (key->expire < (now() - RENEW_TIME)) 280 /* this session will get a new ticket 281 * even though the current is still valid */ 282 return 2; 283 284 return 1; 285 } 286} 287.Ed 288.Sh SEE ALSO 289.Xr ssl 3 , 290.Xr SSL_CTX_add_session 3 , 291.Xr SSL_CTX_callback_ctrl 3 , 292.Xr SSL_CTX_sess_number 3 , 293.Xr SSL_CTX_sess_set_get_cb 3 , 294.Xr SSL_CTX_set_session_id_context 3 , 295.Xr SSL_session_reused 3 , 296.Xr SSL_set_session 3 297.Sh HISTORY 298.Fn SSL_CTX_set_tlsext_ticket_key_cb 299first appeared in OpenSSL 0.9.8h and has been available since 300.Ox 4.5 . 301