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