EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2025-08-27 09:37:34
0001 /** 0002 * \file ssl_ticket.h 0003 * 0004 * \brief TLS server ticket callbacks implementation 0005 */ 0006 /* 0007 * Copyright The Mbed TLS Contributors 0008 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 0009 */ 0010 #ifndef MBEDTLS_SSL_TICKET_H 0011 #define MBEDTLS_SSL_TICKET_H 0012 #include "mbedtls/private_access.h" 0013 0014 #include "mbedtls/build_info.h" 0015 0016 /* 0017 * This implementation of the session ticket callbacks includes key 0018 * management, rotating the keys periodically in order to preserve forward 0019 * secrecy, when MBEDTLS_HAVE_TIME is defined. 0020 */ 0021 0022 #include "mbedtls/ssl.h" 0023 #include "mbedtls/cipher.h" 0024 0025 #if defined(MBEDTLS_HAVE_TIME) 0026 #include "mbedtls/platform_time.h" 0027 #endif 0028 0029 #if defined(MBEDTLS_USE_PSA_CRYPTO) 0030 #include "psa/crypto.h" 0031 #endif 0032 0033 #if defined(MBEDTLS_THREADING_C) 0034 #include "mbedtls/threading.h" 0035 #endif 0036 0037 #ifdef __cplusplus 0038 extern "C" { 0039 #endif 0040 0041 #define MBEDTLS_SSL_TICKET_MAX_KEY_BYTES 32 /*!< Max supported key length in bytes */ 0042 #define MBEDTLS_SSL_TICKET_KEY_NAME_BYTES 4 /*!< key name length in bytes */ 0043 0044 /** 0045 * \brief Information for session ticket protection 0046 */ 0047 typedef struct mbedtls_ssl_ticket_key { 0048 unsigned char MBEDTLS_PRIVATE(name)[MBEDTLS_SSL_TICKET_KEY_NAME_BYTES]; 0049 /*!< random key identifier */ 0050 #if defined(MBEDTLS_HAVE_TIME) 0051 mbedtls_time_t MBEDTLS_PRIVATE(generation_time); /*!< key generation timestamp (seconds) */ 0052 #endif 0053 /*! Lifetime of the key in seconds. This is also the lifetime of the 0054 * tickets created under that key. 0055 */ 0056 uint32_t MBEDTLS_PRIVATE(lifetime); 0057 #if !defined(MBEDTLS_USE_PSA_CRYPTO) 0058 mbedtls_cipher_context_t MBEDTLS_PRIVATE(ctx); /*!< context for auth enc/decryption */ 0059 #else 0060 mbedtls_svc_key_id_t MBEDTLS_PRIVATE(key); /*!< key used for auth enc/decryption */ 0061 psa_algorithm_t MBEDTLS_PRIVATE(alg); /*!< algorithm of auth enc/decryption */ 0062 psa_key_type_t MBEDTLS_PRIVATE(key_type); /*!< key type */ 0063 size_t MBEDTLS_PRIVATE(key_bits); /*!< key length in bits */ 0064 #endif 0065 } 0066 mbedtls_ssl_ticket_key; 0067 0068 /** 0069 * \brief Context for session ticket handling functions 0070 */ 0071 typedef struct mbedtls_ssl_ticket_context { 0072 mbedtls_ssl_ticket_key MBEDTLS_PRIVATE(keys)[2]; /*!< ticket protection keys */ 0073 unsigned char MBEDTLS_PRIVATE(active); /*!< index of the currently active key */ 0074 0075 uint32_t MBEDTLS_PRIVATE(ticket_lifetime); /*!< lifetime of tickets in seconds */ 0076 0077 /** Callback for getting (pseudo-)random numbers */ 0078 int(*MBEDTLS_PRIVATE(f_rng))(void *, unsigned char *, size_t); 0079 void *MBEDTLS_PRIVATE(p_rng); /*!< context for the RNG function */ 0080 0081 #if defined(MBEDTLS_THREADING_C) 0082 mbedtls_threading_mutex_t MBEDTLS_PRIVATE(mutex); 0083 #endif 0084 } 0085 mbedtls_ssl_ticket_context; 0086 0087 /** 0088 * \brief Initialize a ticket context. 0089 * (Just make it ready for mbedtls_ssl_ticket_setup() 0090 * or mbedtls_ssl_ticket_free().) 0091 * 0092 * \param ctx Context to be initialized 0093 */ 0094 void mbedtls_ssl_ticket_init(mbedtls_ssl_ticket_context *ctx); 0095 0096 /** 0097 * \brief Prepare context to be actually used 0098 * 0099 * \param ctx Context to be set up 0100 * \param f_rng RNG callback function (mandatory) 0101 * \param p_rng RNG callback context 0102 * \param cipher AEAD cipher to use for ticket protection. 0103 * Recommended value: MBEDTLS_CIPHER_AES_256_GCM. 0104 * \param lifetime Tickets lifetime in seconds 0105 * Recommended value: 86400 (one day). 0106 * 0107 * \note It is highly recommended to select a cipher that is at 0108 * least as strong as the strongest ciphersuite 0109 * supported. Usually that means a 256-bit key. 0110 * 0111 * \note It is recommended to pick a reasonable lifetime so as not 0112 * to negate the benefits of forward secrecy. 0113 * 0114 * \note The TLS 1.3 specification states that ticket lifetime must 0115 * be smaller than seven days. If ticket lifetime has been 0116 * set to a value greater than seven days in this module then 0117 * if the TLS 1.3 is configured to send tickets after the 0118 * handshake it will fail the connection when trying to send 0119 * the first ticket. 0120 * 0121 * \return 0 if successful, 0122 * or a specific MBEDTLS_ERR_XXX error code 0123 */ 0124 int mbedtls_ssl_ticket_setup(mbedtls_ssl_ticket_context *ctx, 0125 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng, 0126 mbedtls_cipher_type_t cipher, 0127 uint32_t lifetime); 0128 0129 /** 0130 * \brief Rotate session ticket encryption key to new specified key. 0131 * Provides for external control of session ticket encryption 0132 * key rotation, e.g. for synchronization between different 0133 * machines. If this function is not used, or if not called 0134 * before ticket lifetime expires, then a new session ticket 0135 * encryption key is generated internally in order to avoid 0136 * unbounded session ticket encryption key lifetimes. 0137 * 0138 * \param ctx Context to be set up 0139 * \param name Session ticket encryption key name 0140 * \param nlength Session ticket encryption key name length in bytes 0141 * \param k Session ticket encryption key 0142 * \param klength Session ticket encryption key length in bytes 0143 * \param lifetime Tickets lifetime in seconds 0144 * Recommended value: 86400 (one day). 0145 * 0146 * \note \c name and \c k are recommended to be cryptographically 0147 * random data. 0148 * 0149 * \note \c nlength must match sizeof( ctx->name ) 0150 * 0151 * \note \c klength must be sufficient for use by cipher specified 0152 * to \c mbedtls_ssl_ticket_setup 0153 * 0154 * \note It is recommended to pick a reasonable lifetime so as not 0155 * to negate the benefits of forward secrecy. 0156 * 0157 * \note The TLS 1.3 specification states that ticket lifetime must 0158 * be smaller than seven days. If ticket lifetime has been 0159 * set to a value greater than seven days in this module then 0160 * if the TLS 1.3 is configured to send tickets after the 0161 * handshake it will fail the connection when trying to send 0162 * the first ticket. 0163 * 0164 * \return 0 if successful, 0165 * or a specific MBEDTLS_ERR_XXX error code 0166 */ 0167 int mbedtls_ssl_ticket_rotate(mbedtls_ssl_ticket_context *ctx, 0168 const unsigned char *name, size_t nlength, 0169 const unsigned char *k, size_t klength, 0170 uint32_t lifetime); 0171 0172 /** 0173 * \brief Implementation of the ticket write callback 0174 * 0175 * \note See \c mbedtls_ssl_ticket_write_t for description 0176 */ 0177 mbedtls_ssl_ticket_write_t mbedtls_ssl_ticket_write; 0178 0179 /** 0180 * \brief Implementation of the ticket parse callback 0181 * 0182 * \note See \c mbedtls_ssl_ticket_parse_t for description 0183 */ 0184 mbedtls_ssl_ticket_parse_t mbedtls_ssl_ticket_parse; 0185 0186 /** 0187 * \brief Free a context's content and zeroize it. 0188 * 0189 * \param ctx Context to be cleaned up 0190 */ 0191 void mbedtls_ssl_ticket_free(mbedtls_ssl_ticket_context *ctx); 0192 0193 #ifdef __cplusplus 0194 } 0195 #endif 0196 0197 #endif /* ssl_ticket.h */
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|