OpenBSD manual page server

Manual Page Search Parameters
SSL_CTX_SET_TLSEXT_TICKET_KEY_CB(3) Library Functions Manual SSL_CTX_SET_TLSEXT_TICKET_KEY_CB(3)

SSL_CTX_set_tlsext_ticket_key_cb — set a callback for session ticket processing

#include <openssl/tls1.h>

long
SSL_CTX_set_tlsext_ticket_key_cb(SSL_CTX sslctx, int (*cb)(SSL *s, unsigned char key_name[16], unsigned char iv[EVP_MAX_IV_LENGTH], EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc));

() sets a callback function cb for handling session tickets for the ssl context sslctx. Session tickets, defined in RFC 5077, provide an enhanced session resumption capability where the server implementation is not required to maintain per session state.

The callback function cb will be called for every client instigated TLS session when session ticket extension is presented in the TLS hello message. It is the responsibility of this function to create or retrieve the cryptographic parameters and to maintain their state.

The OpenSSL library uses the callback function to help implement a common TLS ticket construction state according to RFC 5077 Section 4 such that per session state is unnecessary and a small set of cryptographic variables needs to be maintained by the callback function implementation.

In order to reuse a session, a TLS client must send a session ticket extension to the server. The client can only send exactly one session ticket. The server, through the callback function, either agrees to reuse the session ticket information or it starts a full TLS handshake to create a new session ticket.

The callback is called with ctx and hctx which were newly allocated with EVP_CIPHER_CTX_new(3) and HMAC_CTX_new(3), respectively.

For new sessions tickets, when the client doesn't present a session ticket, or an attempted retrieval of the ticket failed, or a renew option was indicated, the callback function will be called with enc equal to 1. The OpenSSL library expects that the function will set an arbitrary key_name, initialize iv, and set the cipher context ctx and the hash context hctx.

The key_name is 16 characters long and is used as a key identifier.

The iv length is the length of the IV of the corresponding cipher. The maximum IV length is EVP_MAX_IV_LENGTH bytes defined in <openssl/evp.h>.

The initialization vector iv should be a random value. The cipher context ctx should use the initialisation vector iv. The cipher context can be set using EVP_EncryptInit_ex(3). The hmac context can be set using HMAC_Init_ex(3).

When the client presents a session ticket, the callback function with be called with enc set to 0 indicating that the cb function should retrieve a set of parameters. In this case key_name and iv have already been parsed out of the session ticket. The OpenSSL library expects that the will be used to retrieve a cryptographic parameters and that the cryptographic context ctx will be set with the retrieved parameters and the initialization vector iv using a function like EVP_DecryptInit_ex(3). The hctx needs to be set using HMAC_Init_ex(3).

If the key_name is still valid but a renewal of the ticket is required, the callback function should return 2. The library will call the callback again with an argument of enc equal to 1 to set the new ticket.

The return value of the cb function is used by OpenSSL to determine what further processing will occur. The following return values have meaning:

2
This indicates that the ctx and hctx have been set and the session can continue on those parameters. Additionally it indicates that the session ticket is in a renewal period and should be replaced. The OpenSSL library will call cb again with an enc argument of 1 to set the new ticket (see RFC 5077 3.3 paragraph 2).
1
This indicates that the ctx and hctx have been set and the session can continue on those parameters.
0
This indicates that it was not possible to set/retrieve a session ticket and the SSL/TLS session will continue by negotiating a set of cryptographic parameters or using the alternate SSL/TLS resumption mechanism, session ids.

If called with enc equal to 0, the library will call the cb again to get a new set of parameters.

less than 0
This indicates an error.

Session resumption shortcuts the TLS so that the client certificate negotiation don't occur. It makes up for this by storing client certificate and all other negotiated state information encrypted within the ticket. In a resumed session the applications will have all this state information available exactly as if a full negotiation had occurred.

If an attacker can obtain the key used to encrypt a session ticket, they can obtain the master secret for any ticket using that key and decrypt any traffic using that session: even if the ciphersuite supports forward secrecy. As a result applications may wish to use multiple keys and avoid using long term keys stored in files.

Applications can use longer keys to maintain a consistent level of security. For example if a ciphersuite uses 256 bit ciphers but only a 128 bit ticket key the overall security is only 128 bits because breaking the ticket key will enable an attacker to obtain the session keys.

This function returns 0 to indicate that the callback function was set.

Reference Implementation:

SSL_CTX_set_tlsext_ticket_key_cb(SSL, ssl_tlsext_ticket_key_cb);
....
static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16],
    unsigned char *iv, EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc)
{
	if (enc) { /* create new session */
		if (RAND_bytes(iv, EVP_MAX_IV_LENGTH))
			return -1; /* insufficient random */

		key = currentkey(); /* something you need to implement */
		if (!key) {
			/* current key doesn't exist or isn't valid */
			key = createkey();
			    /* something that you need to implement.
			     * createkey needs to initialise a name,
			     * an aes_key, a hmac_key, and optionally
			     * an expire time. */
			if (!key) /* key couldn't be created */
				return 0;
		}
		memcpy(key_name, key->name, 16);

		EVP_EncryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL,
		    key->aes_key, iv);
		HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL);

		return 1;

	} else { /* retrieve session */
		key = findkey(name);

		if  (!key || key->expire < now())
			return 0;

		HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL);
		EVP_DecryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL,
		    key->aes_key, iv );

		if (key->expire < (now() - RENEW_TIME))
		    /* this session will get a new ticket
		     * even though the current is still valid */
		    return 2;

		return 1;
	}
}

ssl(3), SSL_CTX_add_session(3), SSL_CTX_callback_ctrl(3), SSL_CTX_sess_number(3), SSL_CTX_sess_set_get_cb(3), SSL_CTX_set_session_id_context(3), SSL_session_reused(3), SSL_set_session(3)

SSL_CTX_set_tlsext_ticket_key_cb() first appeared in OpenSSL 0.9.8h and has been available since OpenBSD 4.5.

January 25, 2022 OpenBSD-7.6