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