include/mbedtls/ssl_cookie.h

0001 /**
0002  * \file ssl_cookie.h
0003  *
0004  * \brief DTLS cookie callbacks 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_COOKIE_H
0011 #define MBEDTLS_SSL_COOKIE_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_USE_PSA_CRYPTO)
0019 #if defined(MBEDTLS_THREADING_C)
0020 #include "mbedtls/threading.h"
0021 #endif
0022 #endif /* !MBEDTLS_USE_PSA_CRYPTO */
0023
0024 /**
0025  * \name SECTION: Module settings
0026  *
0027  * The configuration options you can set for this module are in this section.
0028  * Either change them in mbedtls_config.h or define them on the compiler command line.
0029  * \{
0030  */
0031 #ifndef MBEDTLS_SSL_COOKIE_TIMEOUT
0032 #define MBEDTLS_SSL_COOKIE_TIMEOUT     60 /**< Default expiration delay of DTLS cookies, in seconds if HAVE_TIME, or in number of cookies issued */
0033 #endif
0034
0035 /** \} name SECTION: Module settings */
0036
0037 #ifdef __cplusplus
0038 extern "C" {
0039 #endif
0040
0041 /**
0042  * \brief          Context for the default cookie functions.
0043  */
0044 typedef struct mbedtls_ssl_cookie_ctx {
0045 #if defined(MBEDTLS_USE_PSA_CRYPTO)
0046     mbedtls_svc_key_id_t    MBEDTLS_PRIVATE(psa_hmac_key);  /*!< key id for the HMAC portion   */
0047     psa_algorithm_t         MBEDTLS_PRIVATE(psa_hmac_alg);  /*!< key algorithm for the HMAC portion   */
0048 #else
0049     mbedtls_md_context_t    MBEDTLS_PRIVATE(hmac_ctx);   /*!< context for the HMAC portion   */
0050 #endif /* MBEDTLS_USE_PSA_CRYPTO */
0051 #if !defined(MBEDTLS_HAVE_TIME)
0052     unsigned long   MBEDTLS_PRIVATE(serial);     /*!< serial number for expiration   */
0053 #endif
0054     unsigned long   MBEDTLS_PRIVATE(timeout);    /*!< timeout delay, in seconds if HAVE_TIME,
0055                                                     or in number of tickets issued */
0056
0057 #if !defined(MBEDTLS_USE_PSA_CRYPTO)
0058 #if defined(MBEDTLS_THREADING_C)
0059     mbedtls_threading_mutex_t MBEDTLS_PRIVATE(mutex);
0060 #endif
0061 #endif /* !MBEDTLS_USE_PSA_CRYPTO */
0062 } mbedtls_ssl_cookie_ctx;
0063
0064 /**
0065  * \brief          Initialize cookie context
0066  */
0067 void mbedtls_ssl_cookie_init(mbedtls_ssl_cookie_ctx *ctx);
0068
0069 /**
0070  * \brief          Setup cookie context (generate keys)
0071  */
0072 int mbedtls_ssl_cookie_setup(mbedtls_ssl_cookie_ctx *ctx,
0073                              int (*f_rng)(void *, unsigned char *, size_t),
0074                              void *p_rng);
0075
0076 /**
0077  * \brief          Set expiration delay for cookies
0078  *                 (Default MBEDTLS_SSL_COOKIE_TIMEOUT)
0079  *
0080  * \param ctx      Cookie context
0081  * \param delay    Delay, in seconds if HAVE_TIME, or in number of cookies
0082  *                 issued in the meantime.
0083  *                 0 to disable expiration (NOT recommended)
0084  */
0085 void mbedtls_ssl_cookie_set_timeout(mbedtls_ssl_cookie_ctx *ctx, unsigned long delay);
0086
0087 /**
0088  * \brief          Free cookie context
0089  */
0090 void mbedtls_ssl_cookie_free(mbedtls_ssl_cookie_ctx *ctx);
0091
0092 /**
0093  * \brief          Generate cookie, see \c mbedtls_ssl_cookie_write_t
0094  */
0095 mbedtls_ssl_cookie_write_t mbedtls_ssl_cookie_write;
0096
0097 /**
0098  * \brief          Verify cookie, see \c mbedtls_ssl_cookie_write_t
0099  */
0100 mbedtls_ssl_cookie_check_t mbedtls_ssl_cookie_check;
0101
0102 #ifdef __cplusplus
0103 }
0104 #endif
0105
0106 #endif /* ssl_cookie.h */