From 7ba73e575618c8bb8f03b544b322768335db9de7 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 9 Feb 2021 15:35:29 +0100 Subject: [PATCH] Explain the usage of is_valid in pthread mutexes Document the usage inside the library, and relate it with how it's additionally used in the test code. Signed-off-by: Gilles Peskine --- include/mbedtls/threading.h | 3 +++ library/threading.c | 6 ++++++ tests/suites/helpers.function | 7 ++++++- 3 files changed, 15 insertions(+), 1 deletion(-) diff --git a/include/mbedtls/threading.h b/include/mbedtls/threading.h index a8183a6ef..45161ce46 100644 --- a/include/mbedtls/threading.h +++ b/include/mbedtls/threading.h @@ -73,6 +73,9 @@ extern "C" { typedef struct mbedtls_threading_mutex_t { pthread_mutex_t mutex; + /* is_valid is 0 after a failed init or a free, and nonzero after a + * successful init. This field is not considered part of the public + * API of Mbed TLS and may change without notice. */ char is_valid; } mbedtls_threading_mutex_t; #endif diff --git a/library/threading.c b/library/threading.c index f4f29cff5..0dc5488c1 100644 --- a/library/threading.c +++ b/library/threading.c @@ -98,6 +98,12 @@ static void threading_mutex_init_pthread( mbedtls_threading_mutex_t *mutex ) if( mutex == NULL ) return; + /* A nonzero value of is_valid indicates a successfully initialized + * mutex. This is a workaround for not being able to return an error + * code for this function. The lock/unlock functions return an error + * if is_valid is nonzero. The Mbed TLS unit test code uses this field + * to distinguish more states of the mutex; see helpers.function for + * details. */ mutex->is_valid = pthread_mutex_init( &mutex->mutex, NULL ) == 0; } diff --git a/tests/suites/helpers.function b/tests/suites/helpers.function index 1d48b2023..0bf81895a 100644 --- a/tests/suites/helpers.function +++ b/tests/suites/helpers.function @@ -834,8 +834,13 @@ int mbedtls_test_hexcmp( uint8_t * a, uint8_t * b, uint32_t a_len, uint32_t b_le * indicate the exact location of the problematic call. To locate the error, * use a debugger and set a breakpoint on mbedtls_test_mutex_usage_error(). */ -enum value_of_mutex_is_valid +enum value_of_mutex_is_valid_field { + /* Potential values for the is_valid field of mbedtls_threading_mutex_t. + * Note that MUTEX_FREED must be 0 and MUTEX_IDLE must be 1 for + * compatibility with threading_mutex_init_pthread() and + * threading_mutex_free_pthread(). MUTEX_LOCKED could be any nonzero + * value. */ MUTEX_FREED = 0, //!< Set by threading_mutex_free_pthread MUTEX_IDLE = 1, //!< Set by threading_mutex_init_pthread and by our unlock MUTEX_LOCKED = 2, //!< Set by our lock