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