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