1 /** Mutex usage verification framework. */
2 
3 /*
4  *  Copyright The Mbed TLS Contributors
5  *  SPDX-License-Identifier: Apache-2.0
6  *
7  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
8  *  not use this file except in compliance with the License.
9  *  You may obtain a copy of the License at
10  *
11  *  http://www.apache.org/licenses/LICENSE-2.0
12  *
13  *  Unless required by applicable law or agreed to in writing, software
14  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
15  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  *  See the License for the specific language governing permissions and
17  *  limitations under the License.
18  */
19 
20 #include <test/helpers.h>
21 #include <test/macros.h>
22 
23 #if defined(MBEDTLS_TEST_MUTEX_USAGE)
24 
25 #include "mbedtls/threading.h"
26 
27 /** Mutex usage verification framework.
28  *
29  * The mutex usage verification code below aims to detect bad usage of
30  * Mbed TLS's mutex abstraction layer at runtime. Note that this is solely
31  * about the use of the mutex itself, not about checking whether the mutex
32  * correctly protects whatever it is supposed to protect.
33  *
34  * The normal usage of a mutex is:
35  * ```
36  * digraph mutex_states {
37  *   "UNINITIALIZED"; // the initial state
38  *   "IDLE";
39  *   "FREED";
40  *   "LOCKED";
41  *   "UNINITIALIZED" -> "IDLE" [label="init"];
42  *   "FREED" -> "IDLE" [label="init"];
43  *   "IDLE" -> "LOCKED" [label="lock"];
44  *   "LOCKED" -> "IDLE" [label="unlock"];
45  *   "IDLE" -> "FREED" [label="free"];
46  * }
47  * ```
48  *
49  * All bad transitions that can be unambiguously detected are reported.
50  * An attempt to use an uninitialized mutex cannot be detected in general
51  * since the memory content may happen to denote a valid state. For the same
52  * reason, a double init cannot be detected.
53  * All-bits-zero is the state of a freed mutex, which is distinct from an
54  * initialized mutex, so attempting to use zero-initialized memory as a mutex
55  * without calling the init function is detected.
56  *
57  * The framework attempts to detect missing calls to init and free by counting
58  * calls to init and free. If there are more calls to init than free, this
59  * means that a mutex is not being freed somewhere, which is a memory leak
60  * on platforms where a mutex consumes resources other than the
61  * mbedtls_threading_mutex_t object itself. If there are more calls to free
62  * than init, this indicates a missing init, which is likely to be detected
63  * by an attempt to lock the mutex as well. A limitation of this framework is
64  * that it cannot detect scenarios where there is exactly the same number of
65  * calls to init and free but the calls don't match. A bug like this is
66  * unlikely to happen uniformly throughout the whole test suite though.
67  *
68  * If an error is detected, this framework will report what happened and the
69  * test case will be marked as failed. Unfortunately, the error report cannot
70  * indicate the exact location of the problematic call. To locate the error,
71  * use a debugger and set a breakpoint on mbedtls_test_mutex_usage_error().
72  */
73 enum value_of_mutex_is_valid_field {
74     /* Potential values for the is_valid field of mbedtls_threading_mutex_t.
75      * Note that MUTEX_FREED must be 0 and MUTEX_IDLE must be 1 for
76      * compatibility with threading_mutex_init_pthread() and
77      * threading_mutex_free_pthread(). MUTEX_LOCKED could be any nonzero
78      * value. */
79     MUTEX_FREED = 0, //!< Set by threading_mutex_free_pthread
80     MUTEX_IDLE = 1, //!< Set by threading_mutex_init_pthread and by our unlock
81     MUTEX_LOCKED = 2, //!< Set by our lock
82 };
83 
84 typedef struct {
85     void (*init)(mbedtls_threading_mutex_t *);
86     void (*free)(mbedtls_threading_mutex_t *);
87     int (*lock)(mbedtls_threading_mutex_t *);
88     int (*unlock)(mbedtls_threading_mutex_t *);
89 } mutex_functions_t;
90 static mutex_functions_t mutex_functions;
91 
92 /** The total number of calls to mbedtls_mutex_init(), minus the total number
93  * of calls to mbedtls_mutex_free().
94  *
95  * Reset to 0 after each test case.
96  */
97 static int live_mutexes;
98 
mbedtls_test_mutex_usage_error(mbedtls_threading_mutex_t * mutex,const char * msg)99 static void mbedtls_test_mutex_usage_error(mbedtls_threading_mutex_t *mutex,
100                                            const char *msg)
101 {
102     (void) mutex;
103     if (mbedtls_test_info.mutex_usage_error == NULL) {
104         mbedtls_test_info.mutex_usage_error = msg;
105     }
106     mbedtls_fprintf(stdout, "[mutex: %s] ", msg);
107     /* Don't mark the test as failed yet. This way, if the test fails later
108      * for a functional reason, the test framework will report the message
109      * and location for this functional reason. If the test passes,
110      * mbedtls_test_mutex_usage_check() will mark it as failed. */
111 }
112 
mbedtls_test_wrap_mutex_init(mbedtls_threading_mutex_t * mutex)113 static void mbedtls_test_wrap_mutex_init(mbedtls_threading_mutex_t *mutex)
114 {
115     mutex_functions.init(mutex);
116     if (mutex->is_valid) {
117         ++live_mutexes;
118     }
119 }
120 
mbedtls_test_wrap_mutex_free(mbedtls_threading_mutex_t * mutex)121 static void mbedtls_test_wrap_mutex_free(mbedtls_threading_mutex_t *mutex)
122 {
123     switch (mutex->is_valid) {
124         case MUTEX_FREED:
125             mbedtls_test_mutex_usage_error(mutex, "free without init or double free");
126             break;
127         case MUTEX_IDLE:
128             /* Do nothing. The underlying free function will reset is_valid
129              * to 0. */
130             break;
131         case MUTEX_LOCKED:
132             mbedtls_test_mutex_usage_error(mutex, "free without unlock");
133             break;
134         default:
135             mbedtls_test_mutex_usage_error(mutex, "corrupted state");
136             break;
137     }
138     if (mutex->is_valid) {
139         --live_mutexes;
140     }
141     mutex_functions.free(mutex);
142 }
143 
mbedtls_test_wrap_mutex_lock(mbedtls_threading_mutex_t * mutex)144 static int mbedtls_test_wrap_mutex_lock(mbedtls_threading_mutex_t *mutex)
145 {
146     int ret = mutex_functions.lock(mutex);
147     switch (mutex->is_valid) {
148         case MUTEX_FREED:
149             mbedtls_test_mutex_usage_error(mutex, "lock without init");
150             break;
151         case MUTEX_IDLE:
152             if (ret == 0) {
153                 mutex->is_valid = 2;
154             }
155             break;
156         case MUTEX_LOCKED:
157             mbedtls_test_mutex_usage_error(mutex, "double lock");
158             break;
159         default:
160             mbedtls_test_mutex_usage_error(mutex, "corrupted state");
161             break;
162     }
163     return ret;
164 }
165 
mbedtls_test_wrap_mutex_unlock(mbedtls_threading_mutex_t * mutex)166 static int mbedtls_test_wrap_mutex_unlock(mbedtls_threading_mutex_t *mutex)
167 {
168     int ret = mutex_functions.unlock(mutex);
169     switch (mutex->is_valid) {
170         case MUTEX_FREED:
171             mbedtls_test_mutex_usage_error(mutex, "unlock without init");
172             break;
173         case MUTEX_IDLE:
174             mbedtls_test_mutex_usage_error(mutex, "unlock without lock");
175             break;
176         case MUTEX_LOCKED:
177             if (ret == 0) {
178                 mutex->is_valid = MUTEX_IDLE;
179             }
180             break;
181         default:
182             mbedtls_test_mutex_usage_error(mutex, "corrupted state");
183             break;
184     }
185     return ret;
186 }
187 
mbedtls_test_mutex_usage_init(void)188 void mbedtls_test_mutex_usage_init(void)
189 {
190     mutex_functions.init = mbedtls_mutex_init;
191     mutex_functions.free = mbedtls_mutex_free;
192     mutex_functions.lock = mbedtls_mutex_lock;
193     mutex_functions.unlock = mbedtls_mutex_unlock;
194     mbedtls_mutex_init = &mbedtls_test_wrap_mutex_init;
195     mbedtls_mutex_free = &mbedtls_test_wrap_mutex_free;
196     mbedtls_mutex_lock = &mbedtls_test_wrap_mutex_lock;
197     mbedtls_mutex_unlock = &mbedtls_test_wrap_mutex_unlock;
198 }
199 
mbedtls_test_mutex_usage_check(void)200 void mbedtls_test_mutex_usage_check(void)
201 {
202     if (live_mutexes != 0) {
203         /* A positive number (more init than free) means that a mutex resource
204          * is leaking (on platforms where a mutex consumes more than the
205          * mbedtls_threading_mutex_t object itself). The rare case of a
206          * negative number means a missing init somewhere. */
207         mbedtls_fprintf(stdout, "[mutex: %d leaked] ", live_mutexes);
208         live_mutexes = 0;
209         if (mbedtls_test_info.mutex_usage_error == NULL) {
210             mbedtls_test_info.mutex_usage_error = "missing free";
211         }
212     }
213     if (mbedtls_test_info.mutex_usage_error != NULL &&
214         mbedtls_test_info.result != MBEDTLS_TEST_RESULT_FAILED) {
215         /* Functionally, the test passed. But there was a mutex usage error,
216          * so mark the test as failed after all. */
217         mbedtls_test_fail("Mutex usage error", __LINE__, __FILE__);
218     }
219     mbedtls_test_info.mutex_usage_error = NULL;
220 }
221 
222 #endif /* MBEDTLS_TEST_MUTEX_USAGE */
223