include/mbedtls/ssl_cache.h

0001 /**
0002  * \file ssl_cache.h
0003  *
0004  * \brief SSL session cache implementation
0005  */
0006 /*
0007  *  Copyright The Mbed TLS Contributors
0008  *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
0009  */
0010 #ifndef MBEDTLS_SSL_CACHE_H
0011 #define MBEDTLS_SSL_CACHE_H
0012 #include "mbedtls/private_access.h"
0013
0014 #include "mbedtls/build_info.h"
0015
0016 #include "mbedtls/ssl.h"
0017
0018 #if defined(MBEDTLS_THREADING_C)
0019 #include "mbedtls/threading.h"
0020 #endif
0021
0022 /**
0023  * \name SECTION: Module settings
0024  *
0025  * The configuration options you can set for this module are in this section.
0026  * Either change them in mbedtls_config.h or define them on the compiler command line.
0027  * \{
0028  */
0029
0030 #if !defined(MBEDTLS_SSL_CACHE_DEFAULT_TIMEOUT)
0031 #define MBEDTLS_SSL_CACHE_DEFAULT_TIMEOUT       86400   /*!< 1 day  */
0032 #endif
0033
0034 #if !defined(MBEDTLS_SSL_CACHE_DEFAULT_MAX_ENTRIES)
0035 #define MBEDTLS_SSL_CACHE_DEFAULT_MAX_ENTRIES      50   /*!< Maximum entries in cache */
0036 #endif
0037
0038 /** \} name SECTION: Module settings */
0039
0040 #ifdef __cplusplus
0041 extern "C" {
0042 #endif
0043
0044 typedef struct mbedtls_ssl_cache_context mbedtls_ssl_cache_context;
0045 typedef struct mbedtls_ssl_cache_entry mbedtls_ssl_cache_entry;
0046
0047 /**
0048  * \brief   This structure is used for storing cache entries
0049  */
0050 struct mbedtls_ssl_cache_entry {
0051 #if defined(MBEDTLS_HAVE_TIME)
0052     mbedtls_time_t MBEDTLS_PRIVATE(timestamp);           /*!< entry timestamp    */
0053 #endif
0054
0055     unsigned char MBEDTLS_PRIVATE(session_id)[32];       /*!< session ID         */
0056     size_t MBEDTLS_PRIVATE(session_id_len);
0057
0058     unsigned char *MBEDTLS_PRIVATE(session);             /*!< serialized session */
0059     size_t MBEDTLS_PRIVATE(session_len);
0060
0061     mbedtls_ssl_cache_entry *MBEDTLS_PRIVATE(next);      /*!< chain pointer      */
0062 };
0063
0064 /**
0065  * \brief Cache context
0066  */
0067 struct mbedtls_ssl_cache_context {
0068     mbedtls_ssl_cache_entry *MBEDTLS_PRIVATE(chain);     /*!< start of the chain     */
0069     int MBEDTLS_PRIVATE(timeout);                /*!< cache entry timeout    */
0070     int MBEDTLS_PRIVATE(max_entries);            /*!< maximum entries        */
0071 #if defined(MBEDTLS_THREADING_C)
0072     mbedtls_threading_mutex_t MBEDTLS_PRIVATE(mutex);    /*!< mutex                  */
0073 #endif
0074 };
0075
0076 /**
0077  * \brief          Initialize an SSL cache context
0078  *
0079  * \param cache    SSL cache context
0080  */
0081 void mbedtls_ssl_cache_init(mbedtls_ssl_cache_context *cache);
0082
0083 /**
0084  * \brief          Cache get callback implementation
0085  *                 (Thread-safe if MBEDTLS_THREADING_C is enabled)
0086  *
0087  * \param data            The SSL cache context to use.
0088  * \param session_id      The pointer to the buffer holding the session ID
0089  *                        for the session to load.
0090  * \param session_id_len  The length of \p session_id in bytes.
0091  * \param session         The address at which to store the session
0092  *                        associated with \p session_id, if present.
0093  *
0094  * \return                \c 0 on success.
0095  * \return                #MBEDTLS_ERR_SSL_CACHE_ENTRY_NOT_FOUND if there is
0096  *                        no cache entry with specified session ID found, or
0097  *                        any other negative error code for other failures.
0098  */
0099 int mbedtls_ssl_cache_get(void *data,
0100                           unsigned char const *session_id,
0101                           size_t session_id_len,
0102                           mbedtls_ssl_session *session);
0103
0104 /**
0105  * \brief          Cache set callback implementation
0106  *                 (Thread-safe if MBEDTLS_THREADING_C is enabled)
0107  *
0108  * \param data            The SSL cache context to use.
0109  * \param session_id      The pointer to the buffer holding the session ID
0110  *                        associated to \p session.
0111  * \param session_id_len  The length of \p session_id in bytes.
0112  * \param session         The session to store.
0113  *
0114  * \return                \c 0 on success.
0115  * \return                A negative error code on failure.
0116  */
0117 int mbedtls_ssl_cache_set(void *data,
0118                           unsigned char const *session_id,
0119                           size_t session_id_len,
0120                           const mbedtls_ssl_session *session);
0121
0122 /**
0123  * \brief          Remove the cache entry by the session ID
0124  *                 (Thread-safe if MBEDTLS_THREADING_C is enabled)
0125  *
0126  * \param data            The SSL cache context to use.
0127  * \param session_id      The pointer to the buffer holding the session ID
0128  *                        associated to session.
0129  * \param session_id_len  The length of \p session_id in bytes.
0130  *
0131  * \return                \c 0 on success. This indicates the cache entry for
0132  *                        the session with provided ID is removed or does not
0133  *                        exist.
0134  * \return                A negative error code on failure.
0135  */
0136 int mbedtls_ssl_cache_remove(void *data,
0137                              unsigned char const *session_id,
0138                              size_t session_id_len);
0139
0140 #if defined(MBEDTLS_HAVE_TIME)
0141 /**
0142  * \brief          Set the cache timeout
0143  *                 (Default: MBEDTLS_SSL_CACHE_DEFAULT_TIMEOUT (1 day))
0144  *
0145  *                 A timeout of 0 indicates no timeout.
0146  *
0147  * \param cache    SSL cache context
0148  * \param timeout  cache entry timeout in seconds
0149  */
0150 void mbedtls_ssl_cache_set_timeout(mbedtls_ssl_cache_context *cache, int timeout);
0151
0152 /**
0153  * \brief          Get the cache timeout
0154  *
0155  *                 A timeout of 0 indicates no timeout.
0156  *
0157  * \param cache    SSL cache context
0158  *
0159  * \return         cache entry timeout in seconds
0160  */
0161 static inline int mbedtls_ssl_cache_get_timeout(mbedtls_ssl_cache_context *cache)
0162 {
0163     return cache->MBEDTLS_PRIVATE(timeout);
0164 }
0165 #endif /* MBEDTLS_HAVE_TIME */
0166
0167 /**
0168  * \brief          Set the maximum number of cache entries
0169  *                 (Default: MBEDTLS_SSL_CACHE_DEFAULT_MAX_ENTRIES (50))
0170  *
0171  * \param cache    SSL cache context
0172  * \param max      cache entry maximum
0173  */
0174 void mbedtls_ssl_cache_set_max_entries(mbedtls_ssl_cache_context *cache, int max);
0175
0176 /**
0177  * \brief          Free referenced items in a cache context and clear memory
0178  *
0179  * \param cache    SSL cache context
0180  */
0181 void mbedtls_ssl_cache_free(mbedtls_ssl_cache_context *cache);
0182
0183 #ifdef __cplusplus
0184 }
0185 #endif
0186
0187 #endif /* ssl_cache.h */