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 {
75     /* Potential values for the is_valid field of mbedtls_threading_mutex_t.
76      * Note that MUTEX_FREED must be 0 and MUTEX_IDLE must be 1 for
77      * compatibility with threading_mutex_init_pthread() and
78      * threading_mutex_free_pthread(). MUTEX_LOCKED could be any nonzero
79      * value. */
80     MUTEX_FREED = 0, //!< Set by threading_mutex_free_pthread
81     MUTEX_IDLE = 1, //!< Set by threading_mutex_init_pthread and by our unlock
82     MUTEX_LOCKED = 2, //!< Set by our lock
83 };
84 
85 typedef struct
86 {
87     void (*init)( mbedtls_threading_mutex_t * );
88     void (*free)( mbedtls_threading_mutex_t * );
89     int (*lock)( mbedtls_threading_mutex_t * );
90     int (*unlock)( mbedtls_threading_mutex_t * );
91 } mutex_functions_t;
92 static mutex_functions_t mutex_functions;
93 
94 /** The total number of calls to mbedtls_mutex_init(), minus the total number
95  * of calls to mbedtls_mutex_free().
96  *
97  * Reset to 0 after each test case.
98  */
99 static int live_mutexes;
100 
mbedtls_test_mutex_usage_error(mbedtls_threading_mutex_t * mutex,const char * msg)101 static void mbedtls_test_mutex_usage_error( mbedtls_threading_mutex_t *mutex,
102                                             const char *msg )
103 {
104     (void) mutex;
105     if( mbedtls_test_info.mutex_usage_error == NULL )
106         mbedtls_test_info.mutex_usage_error = msg;
107     mbedtls_fprintf( stdout, "[mutex: %s] ", msg );
108     /* Don't mark the test as failed yet. This way, if the test fails later
109      * for a functional reason, the test framework will report the message
110      * and location for this functional reason. If the test passes,
111      * mbedtls_test_mutex_usage_check() will mark it as failed. */
112 }
113 
mbedtls_test_wrap_mutex_init(mbedtls_threading_mutex_t * mutex)114 static void mbedtls_test_wrap_mutex_init( mbedtls_threading_mutex_t *mutex )
115 {
116     mutex_functions.init( mutex );
117     if( mutex->is_valid )
118         ++live_mutexes;
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     {
125         case MUTEX_FREED:
126             mbedtls_test_mutex_usage_error( mutex, "free without init or double free" );
127             break;
128         case MUTEX_IDLE:
129             /* Do nothing. The underlying free function will reset is_valid
130              * to 0. */
131             break;
132         case MUTEX_LOCKED:
133             mbedtls_test_mutex_usage_error( mutex, "free without unlock" );
134             break;
135         default:
136             mbedtls_test_mutex_usage_error( mutex, "corrupted state" );
137             break;
138     }
139     if( mutex->is_valid )
140         --live_mutexes;
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     {
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 = 2;
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     {
171         case MUTEX_FREED:
172             mbedtls_test_mutex_usage_error( mutex, "unlock without init" );
173             break;
174         case MUTEX_IDLE:
175             mbedtls_test_mutex_usage_error( mutex, "unlock without lock" );
176             break;
177         case MUTEX_LOCKED:
178             if( ret == 0 )
179                 mutex->is_valid = MUTEX_IDLE;
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     {
204         /* A positive number (more init than free) means that a mutex resource
205          * is leaking (on platforms where a mutex consumes more than the
206          * mbedtls_threading_mutex_t object itself). The rare case of a
207          * negative number means a missing init somewhere. */
208         mbedtls_fprintf( stdout, "[mutex: %d leaked] ", live_mutexes );
209         live_mutexes = 0;
210         if( mbedtls_test_info.mutex_usage_error == NULL )
211             mbedtls_test_info.mutex_usage_error = "missing free";
212     }
213     if( mbedtls_test_info.mutex_usage_error != NULL &&
214         mbedtls_test_info.result != MBEDTLS_TEST_RESULT_FAILED )
215     {
216         /* Functionally, the test passed. But there was a mutex usage error,
217          * so mark the test as failed after all. */
218         mbedtls_test_fail( "Mutex usage error", __LINE__, __FILE__ );
219     }
220     mbedtls_test_info.mutex_usage_error = NULL;
221 }
222 
223 #endif /* MBEDTLS_TEST_MUTEX_USAGE */
224