blob: 0ffffbfd54ff295ea3cfc028e6e4aec36c5610eb [file] [log] [blame]
Gilles Peskine1061ec62021-01-29 21:17:11 +01001/** Mutex usage verification framework. */
2
3/*
4 * Copyright The Mbed TLS Contributors
Dave Rodgman16799db2023-11-02 19:47:20 +00005 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
Gilles Peskine1061ec62021-01-29 21:17:11 +01006 */
7
8#include <test/helpers.h>
9#include <test/macros.h>
10
11#if defined(MBEDTLS_TEST_MUTEX_USAGE)
12
13#include "mbedtls/threading.h"
14
Gilles Peskine2a4c5982021-01-29 21:18:09 +010015/** Mutex usage verification framework.
16 *
17 * The mutex usage verification code below aims to detect bad usage of
18 * Mbed TLS's mutex abstraction layer at runtime. Note that this is solely
19 * about the use of the mutex itself, not about checking whether the mutex
20 * correctly protects whatever it is supposed to protect.
21 *
22 * The normal usage of a mutex is:
23 * ```
24 * digraph mutex_states {
25 * "UNINITIALIZED"; // the initial state
26 * "IDLE";
27 * "FREED";
28 * "LOCKED";
29 * "UNINITIALIZED" -> "IDLE" [label="init"];
30 * "FREED" -> "IDLE" [label="init"];
31 * "IDLE" -> "LOCKED" [label="lock"];
32 * "LOCKED" -> "IDLE" [label="unlock"];
33 * "IDLE" -> "FREED" [label="free"];
34 * }
35 * ```
36 *
37 * All bad transitions that can be unambiguously detected are reported.
38 * An attempt to use an uninitialized mutex cannot be detected in general
39 * since the memory content may happen to denote a valid state. For the same
40 * reason, a double init cannot be detected.
41 * All-bits-zero is the state of a freed mutex, which is distinct from an
42 * initialized mutex, so attempting to use zero-initialized memory as a mutex
43 * without calling the init function is detected.
44 *
Gilles Peskinef96d3d82021-01-29 22:20:32 +010045 * The framework attempts to detect missing calls to init and free by counting
46 * calls to init and free. If there are more calls to init than free, this
47 * means that a mutex is not being freed somewhere, which is a memory leak
48 * on platforms where a mutex consumes resources other than the
49 * mbedtls_threading_mutex_t object itself. If there are more calls to free
50 * than init, this indicates a missing init, which is likely to be detected
51 * by an attempt to lock the mutex as well. A limitation of this framework is
52 * that it cannot detect scenarios where there is exactly the same number of
53 * calls to init and free but the calls don't match. A bug like this is
54 * unlikely to happen uniformly throughout the whole test suite though.
55 *
Gilles Peskine2a4c5982021-01-29 21:18:09 +010056 * If an error is detected, this framework will report what happened and the
57 * test case will be marked as failed. Unfortunately, the error report cannot
58 * indicate the exact location of the problematic call. To locate the error,
59 * use a debugger and set a breakpoint on mbedtls_test_mutex_usage_error().
60 */
Gilles Peskine449bd832023-01-11 14:50:10 +010061enum value_of_mutex_is_valid_field {
Gilles Peskine39a1a262021-02-09 15:35:29 +010062 /* Potential values for the is_valid field of mbedtls_threading_mutex_t.
63 * Note that MUTEX_FREED must be 0 and MUTEX_IDLE must be 1 for
64 * compatibility with threading_mutex_init_pthread() and
65 * threading_mutex_free_pthread(). MUTEX_LOCKED could be any nonzero
66 * value. */
Paul Elliott5fa986c2023-11-10 14:05:09 +000067 MUTEX_FREED = 0, //! < Set by mbedtls_test_wrap_mutex_free
68 MUTEX_IDLE = 1, //! < Set by mbedtls_test_wrap_mutex_init and by mbedtls_test_wrap_mutex_unlock
69 MUTEX_LOCKED = 2, //! < Set by mbedtls_test_wrap_mutex_lock
Gilles Peskine2a4c5982021-01-29 21:18:09 +010070};
71
Gilles Peskine449bd832023-01-11 14:50:10 +010072typedef struct {
73 void (*init)(mbedtls_threading_mutex_t *);
74 void (*free)(mbedtls_threading_mutex_t *);
75 int (*lock)(mbedtls_threading_mutex_t *);
76 int (*unlock)(mbedtls_threading_mutex_t *);
Gilles Peskine1061ec62021-01-29 21:17:11 +010077} mutex_functions_t;
78static mutex_functions_t mutex_functions;
79
Paul Elliott37746372023-11-12 19:05:57 +000080mbedtls_threading_mutex_t mbedtls_test_mutex_mutex;
81
Gilles Peskinef96d3d82021-01-29 22:20:32 +010082/** The total number of calls to mbedtls_mutex_init(), minus the total number
83 * of calls to mbedtls_mutex_free().
84 *
85 * Reset to 0 after each test case.
86 */
87static int live_mutexes;
88
Gilles Peskine449bd832023-01-11 14:50:10 +010089static void mbedtls_test_mutex_usage_error(mbedtls_threading_mutex_t *mutex,
90 const char *msg)
Gilles Peskine2a4c5982021-01-29 21:18:09 +010091{
92 (void) mutex;
Paul Elliott37746372023-11-12 19:05:57 +000093
Gilles Peskine449bd832023-01-11 14:50:10 +010094 if (mbedtls_test_info.mutex_usage_error == NULL) {
Gilles Peskine2a4c5982021-01-29 21:18:09 +010095 mbedtls_test_info.mutex_usage_error = msg;
Gilles Peskine449bd832023-01-11 14:50:10 +010096 }
97 mbedtls_fprintf(stdout, "[mutex: %s] ", msg);
Gilles Peskine2a4c5982021-01-29 21:18:09 +010098 /* Don't mark the test as failed yet. This way, if the test fails later
99 * for a functional reason, the test framework will report the message
100 * and location for this functional reason. If the test passes,
101 * mbedtls_test_mutex_usage_check() will mark it as failed. */
102}
103
Gilles Peskine449bd832023-01-11 14:50:10 +0100104static void mbedtls_test_wrap_mutex_init(mbedtls_threading_mutex_t *mutex)
Gilles Peskine1061ec62021-01-29 21:17:11 +0100105{
Gilles Peskine449bd832023-01-11 14:50:10 +0100106 mutex_functions.init(mutex);
Paul Elliott5fa986c2023-11-10 14:05:09 +0000107
108 if (mutex_functions.lock(&mbedtls_test_mutex_mutex) == 0) {
109 mutex->state = MUTEX_IDLE;
Gilles Peskinef96d3d82021-01-29 22:20:32 +0100110 ++live_mutexes;
Paul Elliott5fa986c2023-11-10 14:05:09 +0000111
112 mutex_functions.unlock(&mbedtls_test_mutex_mutex);
Gilles Peskine449bd832023-01-11 14:50:10 +0100113 }
Gilles Peskine1061ec62021-01-29 21:17:11 +0100114}
115
Gilles Peskine449bd832023-01-11 14:50:10 +0100116static void mbedtls_test_wrap_mutex_free(mbedtls_threading_mutex_t *mutex)
Gilles Peskine1061ec62021-01-29 21:17:11 +0100117{
Paul Elliott37746372023-11-12 19:05:57 +0000118 if (mutex_functions.lock(&mbedtls_test_mutex_mutex) == 0) {
Paul Elliott5fa986c2023-11-10 14:05:09 +0000119
Paul Elliott37746372023-11-12 19:05:57 +0000120 switch (mutex->is_valid) {
121 case MUTEX_FREED:
122 mbedtls_test_mutex_usage_error(mutex, "free without init or double free");
123 break;
124 case MUTEX_IDLE:
125 mutex->is_valid = MUTEX_FREED;
126 --live_mutexes;
127 break;
128 case MUTEX_LOCKED:
129 mbedtls_test_mutex_usage_error(mutex, "free without unlock");
130 break;
131 default:
132 mbedtls_test_mutex_usage_error(mutex, "corrupted state");
133 break;
134 }
135
136 mutex_functions.unlock(&mbedtls_test_mutex_mutex);
Gilles Peskine449bd832023-01-11 14:50:10 +0100137 }
138 mutex_functions.free(mutex);
Gilles Peskine1061ec62021-01-29 21:17:11 +0100139}
140
Gilles Peskine449bd832023-01-11 14:50:10 +0100141static int mbedtls_test_wrap_mutex_lock(mbedtls_threading_mutex_t *mutex)
Gilles Peskine1061ec62021-01-29 21:17:11 +0100142{
Paul Elliott37746372023-11-12 19:05:57 +0000143 /* Lock the passed in mutex first, so that the only way to change the state
144 * is to hold the passed in and internal mutex - otherwise we create a race
145 * condition. */
Gilles Peskine449bd832023-01-11 14:50:10 +0100146 int ret = mutex_functions.lock(mutex);
Paul Elliott37746372023-11-12 19:05:57 +0000147 if (mutex_functions.lock(&mbedtls_test_mutex_mutex) == 0) {
148 switch (mutex->is_valid) {
149 case MUTEX_FREED:
150 mbedtls_test_mutex_usage_error(mutex, "lock without init");
151 break;
152 case MUTEX_IDLE:
153 if (ret == 0) {
154 mutex->is_valid = MUTEX_LOCKED;
155 }
156 break;
157 case MUTEX_LOCKED:
158 mbedtls_test_mutex_usage_error(mutex, "double lock");
159 break;
160 default:
161 mbedtls_test_mutex_usage_error(mutex, "corrupted state");
162 break;
163 }
164
165 mutex_functions.unlock(&mbedtls_test_mutex_mutex);
Gilles Peskine2a4c5982021-01-29 21:18:09 +0100166 }
Gilles Peskine449bd832023-01-11 14:50:10 +0100167 return ret;
Gilles Peskine1061ec62021-01-29 21:17:11 +0100168}
169
Gilles Peskine449bd832023-01-11 14:50:10 +0100170static int mbedtls_test_wrap_mutex_unlock(mbedtls_threading_mutex_t *mutex)
Gilles Peskine1061ec62021-01-29 21:17:11 +0100171{
Paul Elliott37746372023-11-12 19:05:57 +0000172 /* Lock the internal mutex first and change state, so that the only way to
173 * change the state is to hold the passed in and internal mutex - otherwise
174 * we create a race condition. */
175 if (mutex_functions.lock(&mbedtls_test_mutex_mutex) == 0) {
176 switch (mutex->is_valid) {
177 case MUTEX_FREED:
178 mbedtls_test_mutex_usage_error(mutex, "unlock without init");
179 break;
180 case MUTEX_IDLE:
181 mbedtls_test_mutex_usage_error(mutex, "unlock without lock");
182 break;
183 case MUTEX_LOCKED:
Gilles Peskine2a4c5982021-01-29 21:18:09 +0100184 mutex->is_valid = MUTEX_IDLE;
Paul Elliott37746372023-11-12 19:05:57 +0000185 break;
186 default:
187 mbedtls_test_mutex_usage_error(mutex, "corrupted state");
188 break;
189 }
190 mutex_functions.unlock(&mbedtls_test_mutex_mutex);
Gilles Peskine2a4c5982021-01-29 21:18:09 +0100191 }
Paul Elliott37746372023-11-12 19:05:57 +0000192 return mutex_functions.unlock(mutex);
Gilles Peskine1061ec62021-01-29 21:17:11 +0100193}
194
Gilles Peskine449bd832023-01-11 14:50:10 +0100195void mbedtls_test_mutex_usage_init(void)
Gilles Peskine1061ec62021-01-29 21:17:11 +0100196{
197 mutex_functions.init = mbedtls_mutex_init;
198 mutex_functions.free = mbedtls_mutex_free;
199 mutex_functions.lock = mbedtls_mutex_lock;
200 mutex_functions.unlock = mbedtls_mutex_unlock;
201 mbedtls_mutex_init = &mbedtls_test_wrap_mutex_init;
202 mbedtls_mutex_free = &mbedtls_test_wrap_mutex_free;
203 mbedtls_mutex_lock = &mbedtls_test_wrap_mutex_lock;
204 mbedtls_mutex_unlock = &mbedtls_test_wrap_mutex_unlock;
Paul Elliott37746372023-11-12 19:05:57 +0000205
206 mutex_functions.init(&mbedtls_test_mutex_mutex);
Gilles Peskine1061ec62021-01-29 21:17:11 +0100207}
208
Gilles Peskine449bd832023-01-11 14:50:10 +0100209void mbedtls_test_mutex_usage_check(void)
Gilles Peskine2a4c5982021-01-29 21:18:09 +0100210{
Gilles Peskine449bd832023-01-11 14:50:10 +0100211 if (live_mutexes != 0) {
Gilles Peskinef96d3d82021-01-29 22:20:32 +0100212 /* A positive number (more init than free) means that a mutex resource
213 * is leaking (on platforms where a mutex consumes more than the
214 * mbedtls_threading_mutex_t object itself). The rare case of a
215 * negative number means a missing init somewhere. */
Gilles Peskine449bd832023-01-11 14:50:10 +0100216 mbedtls_fprintf(stdout, "[mutex: %d leaked] ", live_mutexes);
Gilles Peskinef96d3d82021-01-29 22:20:32 +0100217 live_mutexes = 0;
Gilles Peskine449bd832023-01-11 14:50:10 +0100218 if (mbedtls_test_info.mutex_usage_error == NULL) {
Gilles Peskinef96d3d82021-01-29 22:20:32 +0100219 mbedtls_test_info.mutex_usage_error = "missing free";
Gilles Peskine449bd832023-01-11 14:50:10 +0100220 }
Gilles Peskinef96d3d82021-01-29 22:20:32 +0100221 }
Gilles Peskine449bd832023-01-11 14:50:10 +0100222 if (mbedtls_test_info.mutex_usage_error != NULL &&
223 mbedtls_test_info.result != MBEDTLS_TEST_RESULT_FAILED) {
Gilles Peskine2a4c5982021-01-29 21:18:09 +0100224 /* Functionally, the test passed. But there was a mutex usage error,
225 * so mark the test as failed after all. */
Gilles Peskine449bd832023-01-11 14:50:10 +0100226 mbedtls_test_fail("Mutex usage error", __LINE__, __FILE__);
Gilles Peskine2a4c5982021-01-29 21:18:09 +0100227 }
228 mbedtls_test_info.mutex_usage_error = NULL;
229}
230
Gilles Peskine1061ec62021-01-29 21:17:11 +0100231#endif /* MBEDTLS_TEST_MUTEX_USAGE */