File ssl_ticket.h

TLS server ticket callbacks implementation.

Defines

MBEDTLS_SSL_TICKET_MAX_KEY_BYTES

Max supported key length in bytes

MBEDTLS_SSL_TICKET_KEY_NAME_BYTES

key name length in bytes

Typedefs

typedef struct mbedtls_ssl_ticket_key mbedtls_ssl_ticket_key

Information for session ticket protection.

typedef struct mbedtls_ssl_ticket_context mbedtls_ssl_ticket_context

Context for session ticket handling functions.

Functions

void mbedtls_ssl_ticket_init(mbedtls_ssl_ticket_context *ctx)

Initialize a ticket context. (Just make it ready for mbedtls_ssl_ticket_setup() or mbedtls_ssl_ticket_free().)

Parameters

ctx – Context to be initialized

int mbedtls_ssl_ticket_setup(mbedtls_ssl_ticket_context *ctx, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, mbedtls_cipher_type_t cipher, uint32_t lifetime)

Prepare context to be actually used.

Note

It is highly recommended to select a cipher that is at least as strong as the strongest ciphersuite supported. Usually that means a 256-bit key.

Note

It is recommended to pick a reasonable lifetime so as not to negate the benefits of forward secrecy.

Note

The TLS 1.3 specification states that ticket lifetime must be smaller than seven days. If ticket lifetime has been set to a value greater than seven days in this module then if the TLS 1.3 is configured to send tickets after the handshake it will fail the connection when trying to send the first ticket.

Parameters

  • ctx – Context to be set up

  • f_rng – RNG callback function (mandatory)

  • p_rng – RNG callback context

  • cipher – AEAD cipher to use for ticket protection. Recommended value: MBEDTLS_CIPHER_AES_256_GCM.

  • lifetime – Tickets lifetime in seconds Recommended value: 86400 (one day).

Returns

0 if successful, or a specific MBEDTLS_ERR_XXX error code

int mbedtls_ssl_ticket_rotate(mbedtls_ssl_ticket_context *ctx, const unsigned char *name, size_t nlength, const unsigned char *k, size_t klength, uint32_t lifetime)

Rotate session ticket encryption key to new specified key. Provides for external control of session ticket encryption key rotation, e.g. for synchronization between different machines. If this function is not used, or if not called before ticket lifetime expires, then a new session ticket encryption key is generated internally in order to avoid unbounded session ticket encryption key lifetimes.

Note

name and k are recommended to be cryptographically random data.

Note

nlength must match sizeof( ctx->name )

Note

klength must be sufficient for use by cipher specified to mbedtls_ssl_ticket_setup

Note

It is recommended to pick a reasonable lifetime so as not to negate the benefits of forward secrecy.

Note

The TLS 1.3 specification states that ticket lifetime must be smaller than seven days. If ticket lifetime has been set to a value greater than seven days in this module then if the TLS 1.3 is configured to send tickets after the handshake it will fail the connection when trying to send the first ticket.

Parameters

  • ctx – Context to be set up

  • name – Session ticket encryption key name

  • nlength – Session ticket encryption key name length in bytes

  • k – Session ticket encryption key

  • klength – Session ticket encryption key length in bytes

  • lifetime – Tickets lifetime in seconds Recommended value: 86400 (one day).

Returns

0 if successful, or a specific MBEDTLS_ERR_XXX error code

void mbedtls_ssl_ticket_free(mbedtls_ssl_ticket_context *ctx)

Free a context’s content and zeroize it.

Parameters

ctx – Context to be cleaned up

Variables

mbedtls_ssl_ticket_write_t mbedtls_ssl_ticket_write

Implementation of the ticket write callback.

Note

See mbedtls_ssl_ticket_write_t for description

mbedtls_ssl_ticket_parse_t mbedtls_ssl_ticket_parse

Implementation of the ticket parse callback.

Note

See mbedtls_ssl_ticket_parse_t for description

struct mbedtls_ssl_ticket_key
#include <ssl_ticket.h>

Information for session ticket protection.

Public Members

unsigned char private_name[MBEDTLS_SSL_TICKET_KEY_NAME_BYTES]

random key identifier

mbedtls_time_t private_generation_time

key generation timestamp (seconds)

uint32_t private_lifetime

Lifetime of the key in seconds. This is also the lifetime of the tickets created under that key.

mbedtls_svc_key_id_t private_key

key used for auth enc/decryption

psa_algorithm_t private_alg

algorithm of auth enc/decryption

psa_key_type_t private_key_type

key type

size_t private_key_bits

key length in bits

struct mbedtls_ssl_ticket_context
#include <ssl_ticket.h>

Context for session ticket handling functions.

Public Members

mbedtls_ssl_ticket_key private_keys[2]

ticket protection keys

unsigned char private_active

index of the currently active key

uint32_t private_ticket_lifetime

lifetime of tickets in seconds

int (*private_f_rng)(void*, unsigned char*, size_t)

Callback for getting (pseudo-)random numbers

void *private_p_rng

context for the RNG function

mbedtls_threading_mutex_t private_mutex