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 * \param cipher AEAD cipher to use for ticket protection. 103 * Recommended value: MBEDTLS_CIPHER_AES_256_GCM. 104 * \param lifetime Tickets lifetime in seconds 105 * Recommended value: 86400 (one day). 106 * 107 * \note It is highly recommended to select a cipher that is at 108 * least as strong as the strongest ciphersuite 109 * supported. Usually that means a 256-bit key. 110 * 111 * \note It is recommended to pick a reasonable lifetime so as not 112 * to negate the benefits of forward secrecy. 113 * 114 * \note The TLS 1.3 specification states that ticket lifetime must 115 * be smaller than seven days. If ticket lifetime has been 116 * set to a value greater than seven days in this module then 117 * if the TLS 1.3 is configured to send tickets after the 118 * handshake it will fail the connection when trying to send 119 * the first ticket. 120 * 121 * \return 0 if successful, 122 * or a specific MBEDTLS_ERR_XXX error code 123 */ 124 int mbedtls_ssl_ticket_setup(mbedtls_ssl_ticket_context *ctx, 125 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng, 126 mbedtls_cipher_type_t cipher, 127 uint32_t lifetime); 128 129 /** 130 * \brief Rotate session ticket encryption key to new specified key. 131 * Provides for external control of session ticket encryption 132 * key rotation, e.g. for synchronization between different 133 * machines. If this function is not used, or if not called 134 * before ticket lifetime expires, then a new session ticket 135 * encryption key is generated internally in order to avoid 136 * unbounded session ticket encryption key lifetimes. 137 * 138 * \param ctx Context to be set up 139 * \param name Session ticket encryption key name 140 * \param nlength Session ticket encryption key name length in bytes 141 * \param k Session ticket encryption key 142 * \param klength Session ticket encryption key length in bytes 143 * \param lifetime Tickets lifetime in seconds 144 * Recommended value: 86400 (one day). 145 * 146 * \note \c name and \c k are recommended to be cryptographically 147 * random data. 148 * 149 * \note \c nlength must match sizeof( ctx->name ) 150 * 151 * \note \c klength must be sufficient for use by cipher specified 152 * to \c mbedtls_ssl_ticket_setup 153 * 154 * \note It is recommended to pick a reasonable lifetime so as not 155 * to negate the benefits of forward secrecy. 156 * 157 * \note The TLS 1.3 specification states that ticket lifetime must 158 * be smaller than seven days. If ticket lifetime has been 159 * set to a value greater than seven days in this module then 160 * if the TLS 1.3 is configured to send tickets after the 161 * handshake it will fail the connection when trying to send 162 * the first ticket. 163 * 164 * \return 0 if successful, 165 * or a specific MBEDTLS_ERR_XXX error code 166 */ 167 int mbedtls_ssl_ticket_rotate(mbedtls_ssl_ticket_context *ctx, 168 const unsigned char *name, size_t nlength, 169 const unsigned char *k, size_t klength, 170 uint32_t lifetime); 171 172 /** 173 * \brief Implementation of the ticket write callback 174 * 175 * \note See \c mbedtls_ssl_ticket_write_t for description 176 */ 177 mbedtls_ssl_ticket_write_t mbedtls_ssl_ticket_write; 178 179 /** 180 * \brief Implementation of the ticket parse callback 181 * 182 * \note See \c mbedtls_ssl_ticket_parse_t for description 183 */ 184 mbedtls_ssl_ticket_parse_t mbedtls_ssl_ticket_parse; 185 186 /** 187 * \brief Free a context's content and zeroize it. 188 * 189 * \param ctx Context to be cleaned up 190 */ 191 void mbedtls_ssl_ticket_free(mbedtls_ssl_ticket_context *ctx); 192 193 #ifdef __cplusplus 194 } 195 #endif 196 197 #endif /* ssl_ticket.h */ 198
