1 /** 2 * \file ssl_cache.h 3 * 4 * \brief SSL session cache 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_CACHE_H 23 #define MBEDTLS_SSL_CACHE_H 24 #include "mbedtls/private_access.h" 25 26 #include "mbedtls/build_info.h" 27 28 #include "mbedtls/ssl.h" 29 30 #if defined(MBEDTLS_THREADING_C) 31 #include "mbedtls/threading.h" 32 #endif 33 34 /** 35 * \name SECTION: Module settings 36 * 37 * The configuration options you can set for this module are in this section. 38 * Either change them in mbedtls_config.h or define them on the compiler command line. 39 * \{ 40 */ 41 42 #if !defined(MBEDTLS_SSL_CACHE_DEFAULT_TIMEOUT) 43 #define MBEDTLS_SSL_CACHE_DEFAULT_TIMEOUT 86400 /*!< 1 day */ 44 #endif 45 46 #if !defined(MBEDTLS_SSL_CACHE_DEFAULT_MAX_ENTRIES) 47 #define MBEDTLS_SSL_CACHE_DEFAULT_MAX_ENTRIES 50 /*!< Maximum entries in cache */ 48 #endif 49 50 /** \} name SECTION: Module settings */ 51 52 #ifdef __cplusplus 53 extern "C" { 54 #endif 55 56 typedef struct mbedtls_ssl_cache_context mbedtls_ssl_cache_context; 57 typedef struct mbedtls_ssl_cache_entry mbedtls_ssl_cache_entry; 58 59 /** 60 * \brief This structure is used for storing cache entries 61 */ 62 struct mbedtls_ssl_cache_entry { 63 #if defined(MBEDTLS_HAVE_TIME) 64 mbedtls_time_t MBEDTLS_PRIVATE(timestamp); /*!< entry timestamp */ 65 #endif 66 67 unsigned char MBEDTLS_PRIVATE(session_id)[32]; /*!< session ID */ 68 size_t MBEDTLS_PRIVATE(session_id_len); 69 70 unsigned char *MBEDTLS_PRIVATE(session); /*!< serialized session */ 71 size_t MBEDTLS_PRIVATE(session_len); 72 73 mbedtls_ssl_cache_entry *MBEDTLS_PRIVATE(next); /*!< chain pointer */ 74 }; 75 76 /** 77 * \brief Cache context 78 */ 79 struct mbedtls_ssl_cache_context { 80 mbedtls_ssl_cache_entry *MBEDTLS_PRIVATE(chain); /*!< start of the chain */ 81 int MBEDTLS_PRIVATE(timeout); /*!< cache entry timeout */ 82 int MBEDTLS_PRIVATE(max_entries); /*!< maximum entries */ 83 #if defined(MBEDTLS_THREADING_C) 84 mbedtls_threading_mutex_t MBEDTLS_PRIVATE(mutex); /*!< mutex */ 85 #endif 86 }; 87 88 /** 89 * \brief Initialize an SSL cache context 90 * 91 * \param cache SSL cache context 92 */ 93 void mbedtls_ssl_cache_init(mbedtls_ssl_cache_context *cache); 94 95 /** 96 * \brief Cache get callback implementation 97 * (Thread-safe if MBEDTLS_THREADING_C is enabled) 98 * 99 * \param data The SSL cache context to use. 100 * \param session_id The pointer to the buffer holding the session ID 101 * for the session to load. 102 * \param session_id_len The length of \p session_id in bytes. 103 * \param session The address at which to store the session 104 * associated with \p session_id, if present. 105 */ 106 int mbedtls_ssl_cache_get(void *data, 107 unsigned char const *session_id, 108 size_t session_id_len, 109 mbedtls_ssl_session *session); 110 111 /** 112 * \brief Cache set callback implementation 113 * (Thread-safe if MBEDTLS_THREADING_C is enabled) 114 * 115 * \param data The SSL cache context to use. 116 * \param session_id The pointer to the buffer holding the session ID 117 * associated to \p session. 118 * \param session_id_len The length of \p session_id in bytes. 119 * \param session The session to store. 120 */ 121 int mbedtls_ssl_cache_set(void *data, 122 unsigned char const *session_id, 123 size_t session_id_len, 124 const mbedtls_ssl_session *session); 125 126 /** 127 * \brief Remove the cache entry by the session ID 128 * (Thread-safe if MBEDTLS_THREADING_C is enabled) 129 * 130 * \param data The SSL cache context to use. 131 * \param session_id The pointer to the buffer holding the session ID 132 * associated to \p session. 133 * \param session_id_len The length of \p session_id in bytes. 134 * 135 * \return 0: The cache entry for session with provided ID 136 * is removed or does not exist. 137 * Otherwise: fail. 138 */ 139 int mbedtls_ssl_cache_remove(void *data, 140 unsigned char const *session_id, 141 size_t session_id_len); 142 143 #if defined(MBEDTLS_HAVE_TIME) 144 /** 145 * \brief Set the cache timeout 146 * (Default: MBEDTLS_SSL_CACHE_DEFAULT_TIMEOUT (1 day)) 147 * 148 * A timeout of 0 indicates no timeout. 149 * 150 * \param cache SSL cache context 151 * \param timeout cache entry timeout in seconds 152 */ 153 void mbedtls_ssl_cache_set_timeout(mbedtls_ssl_cache_context *cache, int timeout); 154 #endif /* MBEDTLS_HAVE_TIME */ 155 156 /** 157 * \brief Set the maximum number of cache entries 158 * (Default: MBEDTLS_SSL_CACHE_DEFAULT_MAX_ENTRIES (50)) 159 * 160 * \param cache SSL cache context 161 * \param max cache entry maximum 162 */ 163 void mbedtls_ssl_cache_set_max_entries(mbedtls_ssl_cache_context *cache, int max); 164 165 /** 166 * \brief Free referenced items in a cache context and clear memory 167 * 168 * \param cache SSL cache context 169 */ 170 void mbedtls_ssl_cache_free(mbedtls_ssl_cache_context *cache); 171 172 #ifdef __cplusplus 173 } 174 #endif 175 176 #endif /* ssl_cache.h */ 177