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