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 13 #if !defined(MBEDTLS_CONFIG_FILE) 14 #include "mbedtls/config.h" 15 #else 16 #include MBEDTLS_CONFIG_FILE 17 #endif 18 19 /* 20 * This implementation of the session ticket callbacks includes key 21 * management, rotating the keys periodically in order to preserve forward 22 * secrecy, when MBEDTLS_HAVE_TIME is defined. 23 */ 24 25 #include "mbedtls/ssl.h" 26 #include "mbedtls/cipher.h" 27 28 #if defined(MBEDTLS_THREADING_C) 29 #include "mbedtls/threading.h" 30 #endif 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 36 /** 37 * \brief Information for session ticket protection 38 */ 39 typedef struct mbedtls_ssl_ticket_key { 40 unsigned char name[4]; /*!< random key identifier */ 41 uint32_t generation_time; /*!< key generation timestamp (seconds) */ 42 mbedtls_cipher_context_t ctx; /*!< context for auth enc/decryption */ 43 } 44 mbedtls_ssl_ticket_key; 45 46 /** 47 * \brief Context for session ticket handling functions 48 */ 49 typedef struct mbedtls_ssl_ticket_context { 50 mbedtls_ssl_ticket_key keys[2]; /*!< ticket protection keys */ 51 unsigned char active; /*!< index of the currently active key */ 52 53 uint32_t ticket_lifetime; /*!< lifetime of tickets in seconds */ 54 55 /** Callback for getting (pseudo-)random numbers */ 56 int (*f_rng)(void *, unsigned char *, size_t); 57 void *p_rng; /*!< context for the RNG function */ 58 59 #if defined(MBEDTLS_THREADING_C) 60 mbedtls_threading_mutex_t mutex; 61 #endif 62 } 63 mbedtls_ssl_ticket_context; 64 65 /** 66 * \brief Initialize a ticket context. 67 * (Just make it ready for mbedtls_ssl_ticket_setup() 68 * or mbedtls_ssl_ticket_free().) 69 * 70 * \param ctx Context to be initialized 71 */ 72 void mbedtls_ssl_ticket_init(mbedtls_ssl_ticket_context *ctx); 73 74 /** 75 * \brief Prepare context to be actually used 76 * 77 * \param ctx Context to be set up 78 * \param f_rng RNG callback function 79 * \param p_rng RNG callback context 80 * \param cipher AEAD cipher to use for ticket protection. 81 * Recommended value: MBEDTLS_CIPHER_AES_256_GCM. 82 * \param lifetime Tickets lifetime in seconds 83 * Recommended value: 86400 (one day). 84 * 85 * \note It is highly recommended to select a cipher that is at 86 * least as strong as the strongest ciphersuite 87 * supported. Usually that means a 256-bit key. 88 * 89 * \note The lifetime of the keys is twice the lifetime of tickets. 90 * It is recommended to pick a reasonable lifetime so as not 91 * to negate the benefits of forward secrecy. 92 * 93 * \return 0 if successful, 94 * or a specific MBEDTLS_ERR_XXX error code 95 */ 96 int mbedtls_ssl_ticket_setup(mbedtls_ssl_ticket_context *ctx, 97 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng, 98 mbedtls_cipher_type_t cipher, 99 uint32_t lifetime); 100 101 /** 102 * \brief Implementation of the ticket write callback 103 * 104 * \note See \c mbedtls_ssl_ticket_write_t for description 105 */ 106 mbedtls_ssl_ticket_write_t mbedtls_ssl_ticket_write; 107 108 /** 109 * \brief Implementation of the ticket parse callback 110 * 111 * \note See \c mbedtls_ssl_ticket_parse_t for description 112 */ 113 mbedtls_ssl_ticket_parse_t mbedtls_ssl_ticket_parse; 114 115 /** 116 * \brief Free a context's content and zeroize it. 117 * 118 * \param ctx Context to be cleaned up 119 */ 120 void mbedtls_ssl_ticket_free(mbedtls_ssl_ticket_context *ctx); 121 122 #ifdef __cplusplus 123 } 124 #endif 125 126 #endif /* ssl_ticket.h */ 127