1 /** 2 * \file ssl_ticket.h 3 * 4 * \brief TLS server ticket callbacks implementation 5 */ 6 /* 7 * Copyright The Mbed TLS Contributors 8 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 9 */ 10 #ifndef MBEDTLS_SSL_TICKET_H 11 #define MBEDTLS_SSL_TICKET_H 12 #include "mbedtls/private_access.h" 13 14 #include "mbedtls/build_info.h" 15 16 /* 17 * This implementation of the session ticket callbacks includes key 18 * management, rotating the keys periodically in order to preserve forward 19 * secrecy, when MBEDTLS_HAVE_TIME is defined. 20 */ 21 22 #include "mbedtls/ssl.h" 23 #include "mbedtls/cipher.h" 24 25 #if defined(MBEDTLS_HAVE_TIME) 26 #include "mbedtls/platform_time.h" 27 #endif 28 29 #if defined(MBEDTLS_USE_PSA_CRYPTO) 30 #include "psa/crypto.h" 31 #endif 32 33 #if defined(MBEDTLS_THREADING_C) 34 #include "mbedtls/threading.h" 35 #endif 36 37 #ifdef __cplusplus 38 extern "C" { 39 #endif 40 41 #define MBEDTLS_SSL_TICKET_MAX_KEY_BYTES 32 /*!< Max supported key length in bytes */ 42 #define MBEDTLS_SSL_TICKET_KEY_NAME_BYTES 4 /*!< key name length in bytes */ 43 44 /** 45 * \brief Information for session ticket protection 46 */ 47 typedef struct mbedtls_ssl_ticket_key { 48 unsigned char MBEDTLS_PRIVATE(name)[MBEDTLS_SSL_TICKET_KEY_NAME_BYTES]; 49 /*!< random key identifier */ 50 #if defined(MBEDTLS_HAVE_TIME) 51 mbedtls_time_t MBEDTLS_PRIVATE(generation_time); /*!< key generation timestamp (seconds) */ 52 #endif 53 /*! Lifetime of the key in seconds. This is also the lifetime of the 54 * tickets created under that key. 55 */ 56 uint32_t MBEDTLS_PRIVATE(lifetime); 57 #if !defined(MBEDTLS_USE_PSA_CRYPTO) 58 mbedtls_cipher_context_t MBEDTLS_PRIVATE(ctx); /*!< context for auth enc/decryption */ 59 #else 60 mbedtls_svc_key_id_t MBEDTLS_PRIVATE(key); /*!< key used for auth enc/decryption */ 61 psa_algorithm_t MBEDTLS_PRIVATE(alg); /*!< algorithm of auth enc/decryption */ 62 psa_key_type_t MBEDTLS_PRIVATE(key_type); /*!< key type */ 63 size_t MBEDTLS_PRIVATE(key_bits); /*!< key length in bits */ 64 #endif 65 } 66 mbedtls_ssl_ticket_key; 67 68 /** 69 * \brief Context for session ticket handling functions 70 */ 71 typedef struct mbedtls_ssl_ticket_context { 72 mbedtls_ssl_ticket_key MBEDTLS_PRIVATE(keys)[2]; /*!< ticket protection keys */ 73 unsigned char MBEDTLS_PRIVATE(active); /*!< index of the currently active key */ 74 75 uint32_t MBEDTLS_PRIVATE(ticket_lifetime); /*!< lifetime of tickets in seconds */ 76 77 /** Callback for getting (pseudo-)random numbers */ 78 int(*MBEDTLS_PRIVATE(f_rng))(void *, unsigned char *, size_t); 79 void *MBEDTLS_PRIVATE(p_rng); /*!< context for the RNG function */ 80 81 #if defined(MBEDTLS_THREADING_C) 82 mbedtls_threading_mutex_t MBEDTLS_PRIVATE(mutex); 83 #endif 84 } 85 mbedtls_ssl_ticket_context; 86 87 /** 88 * \brief Initialize a ticket context. 89 * (Just make it ready for mbedtls_ssl_ticket_setup() 90 * or mbedtls_ssl_ticket_free().) 91 * 92 * \param ctx Context to be initialized 93 */ 94 void mbedtls_ssl_ticket_init(mbedtls_ssl_ticket_context *ctx); 95 96 /** 97 * \brief Prepare context to be actually used 98 * 99 * \param ctx Context to be set up 100 * \param f_rng RNG callback function (mandatory) 101 * \param p_rng RNG callback context. 102 * Note that the RNG callback must remain valid 103 * until the ticket context is freed. 104 * \param cipher AEAD cipher to use for ticket protection. 105 * Recommended value: MBEDTLS_CIPHER_AES_256_GCM. 106 * \param lifetime Tickets lifetime in seconds 107 * Recommended value: 86400 (one day). 108 * 109 * \note It is highly recommended to select a cipher that is at 110 * least as strong as the strongest ciphersuite 111 * supported. Usually that means a 256-bit key. 112 * 113 * \note It is recommended to pick a reasonable lifetime so as not 114 * to negate the benefits of forward secrecy. 115 * 116 * \note The TLS 1.3 specification states that ticket lifetime must 117 * be smaller than seven days. If ticket lifetime has been 118 * set to a value greater than seven days in this module then 119 * if the TLS 1.3 is configured to send tickets after the 120 * handshake it will fail the connection when trying to send 121 * the first ticket. 122 * 123 * \return 0 if successful, 124 * or a specific MBEDTLS_ERR_XXX error code 125 */ 126 int mbedtls_ssl_ticket_setup(mbedtls_ssl_ticket_context *ctx, 127 mbedtls_f_rng_t *f_rng, void *p_rng, 128 mbedtls_cipher_type_t cipher, 129 uint32_t lifetime); 130 131 /** 132 * \brief Rotate session ticket encryption key to new specified key. 133 * Provides for external control of session ticket encryption 134 * key rotation, e.g. for synchronization between different 135 * machines. If this function is not used, or if not called 136 * before ticket lifetime expires, then a new session ticket 137 * encryption key is generated internally in order to avoid 138 * unbounded session ticket encryption key lifetimes. 139 * 140 * \param ctx Context to be set up 141 * \param name Session ticket encryption key name 142 * \param nlength Session ticket encryption key name length in bytes 143 * \param k Session ticket encryption key 144 * \param klength Session ticket encryption key length in bytes 145 * \param lifetime Tickets lifetime in seconds 146 * Recommended value: 86400 (one day). 147 * 148 * \note \c name and \c k are recommended to be cryptographically 149 * random data. 150 * 151 * \note \c nlength must match sizeof( ctx->name ) 152 * 153 * \note \c klength must be sufficient for use by cipher specified 154 * to \c mbedtls_ssl_ticket_setup 155 * 156 * \note It is recommended to pick a reasonable lifetime so as not 157 * to negate the benefits of forward secrecy. 158 * 159 * \note The TLS 1.3 specification states that ticket lifetime must 160 * be smaller than seven days. If ticket lifetime has been 161 * set to a value greater than seven days in this module then 162 * if the TLS 1.3 is configured to send tickets after the 163 * handshake it will fail the connection when trying to send 164 * the first ticket. 165 * 166 * \return 0 if successful, 167 * or a specific MBEDTLS_ERR_XXX error code 168 */ 169 int mbedtls_ssl_ticket_rotate(mbedtls_ssl_ticket_context *ctx, 170 const unsigned char *name, size_t nlength, 171 const unsigned char *k, size_t klength, 172 uint32_t lifetime); 173 174 /** 175 * \brief Implementation of the ticket write callback 176 * 177 * \note See \c mbedtls_ssl_ticket_write_t for description 178 */ 179 mbedtls_ssl_ticket_write_t mbedtls_ssl_ticket_write; 180 181 /** 182 * \brief Implementation of the ticket parse callback 183 * 184 * \note See \c mbedtls_ssl_ticket_parse_t for description 185 */ 186 mbedtls_ssl_ticket_parse_t mbedtls_ssl_ticket_parse; 187 188 /** 189 * \brief Free a context's content and zeroize it. 190 * 191 * \param ctx Context to be cleaned up 192 */ 193 void mbedtls_ssl_ticket_free(mbedtls_ssl_ticket_context *ctx); 194 195 #ifdef __cplusplus 196 } 197 #endif 198 199 #endif /* ssl_ticket.h */ 200