| /** |
| * \file ssl_ticket.h |
| * |
| * \brief TLS server ticket callbacks implementation |
| */ |
| /* |
| * Copyright The Mbed TLS Contributors |
| * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later |
| */ |
| #ifndef MBEDTLS_SSL_TICKET_H |
| #define MBEDTLS_SSL_TICKET_H |
| #include "mbedtls/private_access.h" |
| |
| #include "mbedtls/build_info.h" |
| |
| /* |
| * This implementation of the session ticket callbacks includes key |
| * management, rotating the keys periodically in order to preserve forward |
| * secrecy, when MBEDTLS_HAVE_TIME is defined. |
| */ |
| |
| #include "mbedtls/ssl.h" |
| #include "mbedtls/cipher.h" |
| |
| #if defined(MBEDTLS_HAVE_TIME) |
| #include "mbedtls/platform_time.h" |
| #endif |
| |
| #if defined(MBEDTLS_USE_PSA_CRYPTO) |
| #include "psa/crypto.h" |
| #endif |
| |
| #if defined(MBEDTLS_THREADING_C) |
| #include "mbedtls/threading.h" |
| #endif |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| #define MBEDTLS_SSL_TICKET_MAX_KEY_BYTES 32 /*!< Max supported key length in bytes */ |
| #define MBEDTLS_SSL_TICKET_KEY_NAME_BYTES 4 /*!< key name length in bytes */ |
| |
| /** |
| * \brief Information for session ticket protection |
| */ |
| typedef struct mbedtls_ssl_ticket_key { |
| unsigned char MBEDTLS_PRIVATE(name)[MBEDTLS_SSL_TICKET_KEY_NAME_BYTES]; |
| /*!< random key identifier */ |
| #if defined(MBEDTLS_HAVE_TIME) |
| mbedtls_time_t MBEDTLS_PRIVATE(generation_time); /*!< key generation timestamp (seconds) */ |
| #endif |
| /*! Lifetime of the key in seconds. This is also the lifetime of the |
| * tickets created under that key. |
| */ |
| uint32_t MBEDTLS_PRIVATE(lifetime); |
| #if !defined(MBEDTLS_USE_PSA_CRYPTO) |
| mbedtls_cipher_context_t MBEDTLS_PRIVATE(ctx); /*!< context for auth enc/decryption */ |
| #else |
| mbedtls_svc_key_id_t MBEDTLS_PRIVATE(key); /*!< key used for auth enc/decryption */ |
| psa_algorithm_t MBEDTLS_PRIVATE(alg); /*!< algorithm of auth enc/decryption */ |
| psa_key_type_t MBEDTLS_PRIVATE(key_type); /*!< key type */ |
| size_t MBEDTLS_PRIVATE(key_bits); /*!< key length in bits */ |
| #endif |
| } |
| mbedtls_ssl_ticket_key; |
| |
| /** |
| * \brief Context for session ticket handling functions |
| */ |
| typedef struct mbedtls_ssl_ticket_context { |
| mbedtls_ssl_ticket_key MBEDTLS_PRIVATE(keys)[2]; /*!< ticket protection keys */ |
| unsigned char MBEDTLS_PRIVATE(active); /*!< index of the currently active key */ |
| |
| uint32_t MBEDTLS_PRIVATE(ticket_lifetime); /*!< lifetime of tickets in seconds */ |
| |
| /** Callback for getting (pseudo-)random numbers */ |
| int(*MBEDTLS_PRIVATE(f_rng))(void *, unsigned char *, size_t); |
| void *MBEDTLS_PRIVATE(p_rng); /*!< context for the RNG function */ |
| |
| #if defined(MBEDTLS_THREADING_C) |
| mbedtls_threading_mutex_t MBEDTLS_PRIVATE(mutex); |
| #endif |
| } |
| mbedtls_ssl_ticket_context; |
| |
| /** |
| * \brief Initialize a ticket context. |
| * (Just make it ready for mbedtls_ssl_ticket_setup() |
| * or mbedtls_ssl_ticket_free().) |
| * |
| * \param ctx Context to be initialized |
| */ |
| void mbedtls_ssl_ticket_init(mbedtls_ssl_ticket_context *ctx); |
| |
| /** |
| * \brief Prepare context to be actually used |
| * |
| * \param ctx Context to be set up |
| * \param f_rng RNG callback function (mandatory) |
| * \param p_rng RNG callback context |
| * \param cipher AEAD cipher to use for ticket protection. |
| * Recommended value: MBEDTLS_CIPHER_AES_256_GCM. |
| * \param lifetime Tickets lifetime in seconds |
| * Recommended value: 86400 (one day). |
| * |
| * \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. |
| * |
| * \return 0 if successful, |
| * or a specific MBEDTLS_ERR_XXX error code |
| */ |
| 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); |
| |
| /** |
| * \brief 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. |
| * |
| * \param ctx Context to be set up |
| * \param name Session ticket encryption key name |
| * \param nlength Session ticket encryption key name length in bytes |
| * \param k Session ticket encryption key |
| * \param klength Session ticket encryption key length in bytes |
| * \param lifetime Tickets lifetime in seconds |
| * Recommended value: 86400 (one day). |
| * |
| * \note \c name and \c k are recommended to be cryptographically |
| * random data. |
| * |
| * \note \c nlength must match sizeof( ctx->name ) |
| * |
| * \note \c klength must be sufficient for use by cipher specified |
| * to \c 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. |
| * |
| * \return 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); |
| |
| /** |
| * \brief Implementation of the ticket write callback |
| * |
| * \note See \c mbedtls_ssl_ticket_write_t for description |
| */ |
| mbedtls_ssl_ticket_write_t mbedtls_ssl_ticket_write; |
| |
| /** |
| * \brief Implementation of the ticket parse callback |
| * |
| * \note See \c mbedtls_ssl_ticket_parse_t for description |
| */ |
| mbedtls_ssl_ticket_parse_t mbedtls_ssl_ticket_parse; |
| |
| /** |
| * \brief Free a context's content and zeroize it. |
| * |
| * \param ctx Context to be cleaned up |
| */ |
| void mbedtls_ssl_ticket_free(mbedtls_ssl_ticket_context *ctx); |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| #endif /* ssl_ticket.h */ |