1 /** 2 * \file threading.h 3 * 4 * \brief Threading abstraction layer 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_THREADING_H 11 #define MBEDTLS_THREADING_H 12 #include "mbedtls/private_access.h" 13 14 #include "mbedtls/build_info.h" 15 16 #include <stdlib.h> 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 /** Bad input parameters to function. */ 23 #define MBEDTLS_ERR_THREADING_BAD_INPUT_DATA -0x001C 24 /** Locking / unlocking / free failed with error code. */ 25 #define MBEDTLS_ERR_THREADING_MUTEX_ERROR -0x001E 26 27 #if defined(MBEDTLS_THREADING_PTHREAD) 28 #include <pthread.h> 29 typedef struct mbedtls_threading_mutex_t { 30 pthread_mutex_t MBEDTLS_PRIVATE(mutex); 31 32 /* WARNING - state should only be accessed when holding the mutex lock in 33 * framework/tests/src/threading_helpers.c, otherwise corruption can occur. 34 * state will be 0 after a failed init or a free, and nonzero after a 35 * successful init. This field is for testing only and thus not considered 36 * part of the public API of Mbed TLS and may change without notice.*/ 37 char MBEDTLS_PRIVATE(state); 38 39 } mbedtls_threading_mutex_t; 40 #endif 41 42 #if defined(MBEDTLS_THREADING_ALT) 43 /* You should define the mbedtls_threading_mutex_t type in your header */ 44 #include "threading_alt.h" 45 46 /** 47 * \brief Set your alternate threading implementation function 48 * pointers and initialize global mutexes. If used, this 49 * function must be called once in the main thread before any 50 * other Mbed TLS function is called, and 51 * mbedtls_threading_free_alt() must be called once in the main 52 * thread after all other Mbed TLS functions. 53 * 54 * \warning \p mutex_init and \p mutex_free don't return a status code. 55 * If \p mutex_init fails, it should leave the mutex in 56 * a state such that \p mutex_lock will reliably return 57 * #MBEDTLS_ERR_THREADING_MUTEX_ERROR called on this mutex, 58 * and \p mutex_free will do nothing. 59 * 60 * \param mutex_init The init function implementation. <br> 61 * The behavior is undefined if the mutex is already 62 * initialized and has not been destroyed. 63 * On platforms where mutex initialization can fail, 64 * since this function does not return a status code, 65 * it must leave the mutex object in a safe state where 66 * subsequent function calls will not cause undefined 67 * behavior: after a call to \p mutex_init, the 68 * function \p mutex_lock must either succeed or 69 * fail with a nonzero status code, and the function 70 * \p mutex_free must free any resources associated 71 * with the mutex.. 72 * \param mutex_free The destroy function implementation. <br> 73 * This function must free any resources associated 74 * with the mutex object. <br> 75 * This function must work reliably if \p mutex_init 76 * has been called on the mutex and \p mutex_free 77 * has not yet been called. <br> 78 * The behavior is undefined if the mutex was not 79 * initialized, if it has already been destroyed, 80 * if it is currently locked, or if this function 81 * is called concurrently from multiple threads. 82 * \param mutex_lock The lock function implementation. <br> 83 * This function must work reliably on any mutex 84 * which is not currently locked and on which 85 * \p mutex_init has already been called but 86 * \p mutex_free has not been called yet. <br> 87 * The behavior is undefined if the mutex was not 88 * initialized, if it has already been destroyed, or if 89 * it is currently locked by the calling thread. 90 * \param mutex_unlock The unlock function implementation. <br> 91 * The behavior is undefined if the mutex is not 92 * currently locked by the calling thread. 93 */ 94 void mbedtls_threading_set_alt(void (*mutex_init)(mbedtls_threading_mutex_t *), 95 void (*mutex_free)(mbedtls_threading_mutex_t *), 96 int (*mutex_lock)(mbedtls_threading_mutex_t *), 97 int (*mutex_unlock)(mbedtls_threading_mutex_t *)); 98 99 /** 100 * \brief Free global mutexes. 101 */ 102 void mbedtls_threading_free_alt(void); 103 #endif /* MBEDTLS_THREADING_ALT */ 104 105 #if defined(MBEDTLS_THREADING_C) 106 /* 107 * The function pointers for mutex_init, mutex_free, mutex_ and mutex_unlock 108 * 109 * All these functions are expected to work or the result will be undefined. 110 */ 111 extern void (*mbedtls_mutex_init)(mbedtls_threading_mutex_t *mutex); 112 extern void (*mbedtls_mutex_free)(mbedtls_threading_mutex_t *mutex); 113 extern int (*mbedtls_mutex_lock)(mbedtls_threading_mutex_t *mutex); 114 extern int (*mbedtls_mutex_unlock)(mbedtls_threading_mutex_t *mutex); 115 116 /* 117 * Global mutexes 118 */ 119 #if defined(MBEDTLS_FS_IO) 120 extern mbedtls_threading_mutex_t mbedtls_threading_readdir_mutex; 121 #endif 122 123 #if defined(MBEDTLS_HAVE_TIME_DATE) && !defined(MBEDTLS_PLATFORM_GMTIME_R_ALT) 124 /* This mutex may or may not be used in the default definition of 125 * mbedtls_platform_gmtime_r(), but in order to determine that, 126 * we need to check POSIX features, hence modify _POSIX_C_SOURCE. 127 * With the current approach, this declaration is orphaned, lacking 128 * an accompanying definition, in case mbedtls_platform_gmtime_r() 129 * doesn't need it, but that's not a problem. */ 130 extern mbedtls_threading_mutex_t mbedtls_threading_gmtime_mutex; 131 #endif /* MBEDTLS_HAVE_TIME_DATE && !MBEDTLS_PLATFORM_GMTIME_R_ALT */ 132 133 #if defined(MBEDTLS_PSA_CRYPTO_C) 134 /* 135 * A mutex used to make the PSA subsystem thread safe. 136 * 137 * key_slot_mutex protects the registered_readers and 138 * state variable for all key slots in &global_data.key_slots. 139 * 140 * This mutex must be held when any read from or write to a state or 141 * registered_readers field is performed, i.e. when calling functions: 142 * psa_key_slot_state_transition(), psa_register_read(), psa_unregister_read(), 143 * psa_key_slot_has_readers() and psa_wipe_key_slot(). */ 144 extern mbedtls_threading_mutex_t mbedtls_threading_key_slot_mutex; 145 146 /* 147 * A mutex used to make the non-rng PSA global_data struct members thread safe. 148 * 149 * This mutex must be held when reading or writing to any of the PSA global_data 150 * structure members, other than the rng_state or rng struct. */ 151 extern mbedtls_threading_mutex_t mbedtls_threading_psa_globaldata_mutex; 152 153 /* 154 * A mutex used to make the PSA global_data rng data thread safe. 155 * 156 * This mutex must be held when reading or writing to the PSA 157 * global_data rng_state or rng struct members. */ 158 extern mbedtls_threading_mutex_t mbedtls_threading_psa_rngdata_mutex; 159 #endif 160 161 #endif /* MBEDTLS_THREADING_C */ 162 163 #ifdef __cplusplus 164 } 165 #endif 166 167 #endif /* threading.h */ 168