1=pod 2 3=head1 NAME 4 5SSL_CTX_set_tlsext_ticket_key_evp_cb, 6SSL_CTX_set_tlsext_ticket_key_cb 7- set a callback for session ticket processing 8 9=head1 SYNOPSIS 10 11 #include <openssl/tls1.h> 12 13 int SSL_CTX_set_tlsext_ticket_key_evp_cb(SSL_CTX sslctx, 14 int (*cb)(SSL *s, unsigned char key_name[16], 15 unsigned char iv[EVP_MAX_IV_LENGTH], 16 EVP_CIPHER_CTX *ctx, EVP_MAC_CTX *hctx, int enc)); 17 18The following function has been deprecated since OpenSSL 3.0, and can be 19hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, 20see L<openssl_user_macros(7)>: 21 22 int SSL_CTX_set_tlsext_ticket_key_cb(SSL_CTX sslctx, 23 int (*cb)(SSL *s, unsigned char key_name[16], 24 unsigned char iv[EVP_MAX_IV_LENGTH], 25 EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc)); 26 27=head1 DESCRIPTION 28 29SSL_CTX_set_tlsext_ticket_key_evp_cb() sets a callback function I<cb> for handling 30session tickets for the ssl context I<sslctx>. Session tickets, defined in 31RFC5077 provide an enhanced session resumption capability where the server 32implementation is not required to maintain per session state. It only applies 33to TLS and there is no SSLv3 implementation. 34 35The callback function I<cb> will be called for every client instigated TLS 36session when session ticket extension is presented in the TLS hello 37message. It is the responsibility of this function to create or retrieve the 38cryptographic parameters and to maintain their state. 39 40The OpenSSL library uses your callback function to help implement a common TLS 41ticket construction state according to RFC5077 Section 4 such that per session 42state is unnecessary and a small set of cryptographic variables needs to be 43maintained by the callback function implementation. 44 45In order to reuse a session, a TLS client must send the a session ticket 46extension to the server. The client can only send exactly one session ticket. 47The server, through the callback function, either agrees to reuse the session 48ticket information or it starts a full TLS handshake to create a new session 49ticket. 50 51Before the callback function is started I<ctx> and I<hctx> have been 52initialised with L<EVP_CIPHER_CTX_reset(3)> and L<EVP_MAC_CTX_new(3)> 53respectively. 54 55For new sessions tickets, when the client doesn't present a session ticket, or 56an attempted retrieval of the ticket failed, or a renew option was indicated, 57the callback function will be called with I<enc> equal to 1. The OpenSSL 58library expects that the function will set an arbitrary I<name>, initialize 59I<iv>, and set the cipher context I<ctx> and the hash context I<hctx>. 60 61The I<name> is 16 characters long and is used as a key identifier. 62 63The I<iv> length is the length of the IV of the corresponding cipher. The 64maximum IV length is B<EVP_MAX_IV_LENGTH> bytes defined in F<< <openssl/evp.h> >>. 65 66The initialization vector I<iv> should be a random value. The cipher context 67I<ctx> should use the initialisation vector I<iv>. The cipher context can be 68set using L<EVP_EncryptInit_ex(3)>. The hmac context and digest can be set using 69L<EVP_MAC_CTX_set_params(3)> with the B<OSSL_MAC_PARAM_KEY> and 70B<OSSL_MAC_PARAM_DIGEST> parameters respectively. 71 72When the client presents a session ticket, the callback function with be called 73with I<enc> set to 0 indicating that the I<cb> function should retrieve a set 74of parameters. In this case I<name> and I<iv> have already been parsed out of 75the session ticket. The OpenSSL library expects that the I<name> will be used 76to retrieve a cryptographic parameters and that the cryptographic context 77I<ctx> will be set with the retrieved parameters and the initialization vector 78I<iv>. using a function like L<EVP_DecryptInit_ex(3)>. The key material and 79digest for I<hctx> need to be set using L<EVP_MAC_CTX_set_params(3)> with the 80B<OSSL_MAC_PARAM_KEY> and B<OSSL_MAC_PARAM_DIGEST> parameters respectively. 81 82If the I<name> is still valid but a renewal of the ticket is required the 83callback function should return 2. The library will call the callback again 84with an argument of enc equal to 1 to set the new ticket. 85 86The return value of the I<cb> function is used by OpenSSL to determine what 87further processing will occur. The following return values have meaning: 88 89=over 4 90 91=item Z<>2 92 93This indicates that the I<ctx> and I<hctx> have been set and the session can 94continue on those parameters. Additionally it indicates that the session 95ticket is in a renewal period and should be replaced. The OpenSSL library will 96call I<cb> again with an enc argument of 1 to set the new ticket (see RFC5077 973.3 paragraph 2). 98 99=item Z<>1 100 101This indicates that the I<ctx> and I<hctx> have been set and the session can 102continue on those parameters. 103 104=item Z<>0 105 106This indicates that it was not possible to set/retrieve a session ticket and 107the SSL/TLS session will continue by negotiating a set of cryptographic 108parameters or using the alternate SSL/TLS resumption mechanism, session ids. 109 110If called with enc equal to 0 the library will call the I<cb> again to get 111a new set of parameters. 112 113=item less than 0 114 115This indicates an error. 116 117=back 118 119The SSL_CTX_set_tlsext_ticket_key_cb() function is identical to 120SSL_CTX_set_tlsext_ticket_key_evp_cb() except that it takes a deprecated 121HMAC_CTX pointer instead of an EVP_MAC_CTX one. 122Before this callback function is started I<hctx> will have been 123initialised with L<EVP_MAC_CTX_new(3)> and the digest set with 124L<EVP_MAC_CTX_set_params(3)>. 125The I<hctx> key material can be set using L<HMAC_Init_ex(3)>. 126 127=head1 NOTES 128 129Session resumption shortcuts the TLS so that the client certificate 130negotiation don't occur. It makes up for this by storing client certificate 131an all other negotiated state information encrypted within the ticket. In a 132resumed session the applications will have all this state information available 133exactly as if a full negotiation had occurred. 134 135If an attacker can obtain the key used to encrypt a session ticket, they can 136obtain the master secret for any ticket using that key and decrypt any traffic 137using that session: even if the cipher suite supports forward secrecy. As 138a result applications may wish to use multiple keys and avoid using long term 139keys stored in files. 140 141Applications can use longer keys to maintain a consistent level of security. 142For example if a cipher suite uses 256 bit ciphers but only a 128 bit ticket key 143the overall security is only 128 bits because breaking the ticket key will 144enable an attacker to obtain the session keys. 145 146=head1 RETURN VALUES 147 148Returns 1 to indicate the callback function was set and 0 otherwise. 149 150=head1 EXAMPLES 151 152Reference Implementation: 153 154 SSL_CTX_set_tlsext_ticket_key_evp_cb(SSL, ssl_tlsext_ticket_key_cb); 155 ... 156 157 static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16], 158 unsigned char *iv, EVP_CIPHER_CTX *ctx, 159 EVP_MAC_CTX *hctx, int enc) 160 { 161 OSSL_PARAM params[3]; 162 your_type_t *key; /* something that you need to implement */ 163 164 if (enc) { /* create new session */ 165 if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) <= 0) 166 return -1; /* insufficient random */ 167 168 key = currentkey(); /* something that you need to implement */ 169 if (key == NULL) { 170 /* current key doesn't exist or isn't valid */ 171 key = createkey(); /* 172 * Something that you need to implement. 173 * createkey needs to initialise a name, 174 * an aes_key, a hmac_key and optionally 175 * an expire time. 176 */ 177 if (key == NULL) /* key couldn't be created */ 178 return 0; 179 } 180 memcpy(key_name, key->name, 16); 181 182 if (EVP_EncryptInit_ex(&ctx, EVP_aes_256_cbc(), NULL, key->aes_key, 183 iv) == 0) 184 return -1; /* error in cipher initialisation */ 185 186 params[0] = OSSL_PARAM_construct_octet_string(OSSL_MAC_PARAM_KEY, 187 key->hmac_key, 32); 188 params[1] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST, 189 "sha256", 0); 190 params[2] = OSSL_PARAM_construct_end(); 191 if (EVP_MAC_CTX_set_params(hctx, params) == 0) 192 return -1; /* error in mac initialisation */ 193 194 return 1; 195 196 } else { /* retrieve session */ 197 time_t t = time(NULL); 198 key = findkey(key_name); /* something that you need to implement */ 199 200 if (key == NULL || key->expire < t) 201 return 0; 202 203 params[0] = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, 204 key->hmac_key, 32); 205 params[1] = OSSL_PARAM_construct_utf8_string(OSSL_MAC_PARAM_DIGEST, 206 "sha256", 0); 207 params[2] = OSSL_PARAM_construct_end(); 208 if (EVP_MAC_CTX_set_params(hctx, params) == 0) 209 return -1; /* error in mac initialisation */ 210 211 if (EVP_DecryptInit_ex(&ctx, EVP_aes_256_cbc(), NULL, key->aes_key, 212 iv) == 0) 213 return -1; /* error in cipher initialisation */ 214 215 if (key->expire < t - RENEW_TIME) { /* RENEW_TIME: implement */ 216 /* 217 * return 2 - This session will get a new ticket even though the 218 * current one is still valid. 219 */ 220 return 2; 221 } 222 return 1; 223 } 224 } 225 226=head1 SEE ALSO 227 228L<ssl(7)>, L<SSL_set_session(3)>, 229L<SSL_session_reused(3)>, 230L<SSL_CTX_add_session(3)>, 231L<SSL_CTX_sess_number(3)>, 232L<SSL_CTX_sess_set_get_cb(3)>, 233L<SSL_CTX_set_session_id_context(3)>, 234 235=head1 HISTORY 236 237The SSL_CTX_set_tlsext_ticket_key_cb() function was deprecated in OpenSSL 3.0. 238 239The SSL_CTX_set_tlsext_ticket_key_evp_cb() function was introduced in 240OpenSSL 3.0. 241 242=head1 COPYRIGHT 243 244Copyright 2014-2021 The OpenSSL Project Authors. All Rights Reserved. 245 246Licensed under the Apache License 2.0 (the "License"). You may not use 247this file except in compliance with the License. You can obtain a copy 248in the file LICENSE in the source distribution or at 249L<https://www.openssl.org/source/license.html>. 250 251=cut 252