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 #if !defined(MBEDTLS_USE_PSA_CRYPTO) 54 mbedtls_cipher_context_t MBEDTLS_PRIVATE(ctx); /*!< context for auth enc/decryption */ 55 #else 56 mbedtls_svc_key_id_t MBEDTLS_PRIVATE(key); /*!< key used for auth enc/decryption */ 57 psa_algorithm_t MBEDTLS_PRIVATE(alg); /*!< algorithm of auth enc/decryption */ 58 psa_key_type_t MBEDTLS_PRIVATE(key_type); /*!< key type */ 59 size_t MBEDTLS_PRIVATE(key_bits); /*!< key length in bits */ 60 #endif 61 } 62 mbedtls_ssl_ticket_key; 63 64 /** 65 * \brief Context for session ticket handling functions 66 */ 67 typedef struct mbedtls_ssl_ticket_context { 68 mbedtls_ssl_ticket_key MBEDTLS_PRIVATE(keys)[2]; /*!< ticket protection keys */ 69 unsigned char MBEDTLS_PRIVATE(active); /*!< index of the currently active key */ 70 71 uint32_t MBEDTLS_PRIVATE(ticket_lifetime); /*!< lifetime of tickets in seconds */ 72 73 /** Callback for getting (pseudo-)random numbers */ 74 int(*MBEDTLS_PRIVATE(f_rng))(void *, unsigned char *, size_t); 75 void *MBEDTLS_PRIVATE(p_rng); /*!< context for the RNG function */ 76 77 #if defined(MBEDTLS_THREADING_C) 78 mbedtls_threading_mutex_t MBEDTLS_PRIVATE(mutex); 79 #endif 80 } 81 mbedtls_ssl_ticket_context; 82 83 /** 84 * \brief Initialize a ticket context. 85 * (Just make it ready for mbedtls_ssl_ticket_setup() 86 * or mbedtls_ssl_ticket_free().) 87 * 88 * \param ctx Context to be initialized 89 */ 90 void mbedtls_ssl_ticket_init(mbedtls_ssl_ticket_context *ctx); 91 92 /** 93 * \brief Prepare context to be actually used 94 * 95 * \param ctx Context to be set up 96 * \param f_rng RNG callback function (mandatory) 97 * \param p_rng RNG callback context 98 * \param cipher AEAD cipher to use for ticket protection. 99 * Recommended value: MBEDTLS_CIPHER_AES_256_GCM. 100 * \param lifetime Tickets lifetime in seconds 101 * Recommended value: 86400 (one day). 102 * 103 * \note It is highly recommended to select a cipher that is at 104 * least as strong as the strongest ciphersuite 105 * supported. Usually that means a 256-bit key. 106 * 107 * \note The lifetime of the keys is twice the lifetime of tickets. 108 * It is recommended to pick a reasonable lifetime so as not 109 * to negate the benefits of forward secrecy. 110 * 111 * \return 0 if successful, 112 * or a specific MBEDTLS_ERR_XXX error code 113 */ 114 int mbedtls_ssl_ticket_setup(mbedtls_ssl_ticket_context *ctx, 115 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng, 116 mbedtls_cipher_type_t cipher, 117 uint32_t lifetime); 118 119 /** 120 * \brief Rotate session ticket encryption key to new specified key. 121 * Provides for external control of session ticket encryption 122 * key rotation, e.g. for synchronization between different 123 * machines. If this function is not used, or if not called 124 * before ticket lifetime expires, then a new session ticket 125 * encryption key is generated internally in order to avoid 126 * unbounded session ticket encryption key lifetimes. 127 * 128 * \param ctx Context to be set up 129 * \param name Session ticket encryption key name 130 * \param nlength Session ticket encryption key name length in bytes 131 * \param k Session ticket encryption key 132 * \param klength Session ticket encryption key length in bytes 133 * \param lifetime Tickets lifetime in seconds 134 * Recommended value: 86400 (one day). 135 * 136 * \note \c name and \c k are recommended to be cryptographically 137 * random data. 138 * 139 * \note \c nlength must match sizeof( ctx->name ) 140 * 141 * \note \c klength must be sufficient for use by cipher specified 142 * to \c mbedtls_ssl_ticket_setup 143 * 144 * \note The lifetime of the keys is twice the lifetime of tickets. 145 * It is recommended to pick a reasonable lifetime so as not 146 * to negate the benefits of forward secrecy. 147 * 148 * \return 0 if successful, 149 * or a specific MBEDTLS_ERR_XXX error code 150 */ 151 int mbedtls_ssl_ticket_rotate(mbedtls_ssl_ticket_context *ctx, 152 const unsigned char *name, size_t nlength, 153 const unsigned char *k, size_t klength, 154 uint32_t lifetime); 155 156 /** 157 * \brief Implementation of the ticket write callback 158 * 159 * \note See \c mbedtls_ssl_ticket_write_t for description 160 */ 161 mbedtls_ssl_ticket_write_t mbedtls_ssl_ticket_write; 162 163 /** 164 * \brief Implementation of the ticket parse callback 165 * 166 * \note See \c mbedtls_ssl_ticket_parse_t for description 167 */ 168 mbedtls_ssl_ticket_parse_t mbedtls_ssl_ticket_parse; 169 170 /** 171 * \brief Free a context's content and zeroize it. 172 * 173 * \param ctx Context to be cleaned up 174 */ 175 void mbedtls_ssl_ticket_free(mbedtls_ssl_ticket_context *ctx); 176 177 #ifdef __cplusplus 178 } 179 #endif 180 181 #endif /* ssl_ticket.h */ 182
