Detect and report mutex usage errors
If the mutex usage verification framework is enabled and it detects a
mutex usage error, report this error and mark the test as failed.
This detects most usage errors, but not all cases of using
uninitialized memory (which is impossible in full generality) and not
leaks due to missing free (which will be handled in a subsequent commit).
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/tests/include/test/helpers.h b/tests/include/test/helpers.h
index aa03701..c3a844b 100644
--- a/tests/include/test/helpers.h
+++ b/tests/include/test/helpers.h
@@ -31,6 +31,11 @@
#include MBEDTLS_CONFIG_FILE
#endif
+#if defined(MBEDTLS_THREADING_C) && defined(MBEDTLS_THREADING_PTHREAD) && \
+ defined(MBEDTLS_TEST_HOOKS)
+#define MBEDTLS_TEST_MUTEX_USAGE
+#endif
+
#if defined(MBEDTLS_PLATFORM_C)
#include "mbedtls/platform.h"
#else
@@ -63,6 +68,9 @@
const char *filename;
int line_no;
unsigned long step;
+#if defined(MBEDTLS_TEST_MUTEX_USAGE)
+ const char *mutex_usage_error;
+#endif
}
mbedtls_test_info_t;
extern mbedtls_test_info_t mbedtls_test_info;
@@ -260,13 +268,14 @@
#include "test/fake_external_rng_for_test.h"
#endif
-#if defined(MBEDTLS_THREADING_C) && defined(MBEDTLS_THREADING_PTHREAD) && \
- defined(MBEDTLS_TEST_HOOKS)
-#define MBEDTLS_TEST_MUTEX_USAGE
-
+#if defined(MBEDTLS_TEST_MUTEX_USAGE)
/** Permanently activate the mutex usage verification framework. See
* threading_helpers.c for information. */
void mbedtls_test_mutex_usage_init( void );
+
+/** Call this function after executing a test case to check for mutex usage
+ * errors. */
+void mbedtls_test_mutex_usage_check( void );
#endif /* MBEDTLS_TEST_MUTEX_USAGE */
#endif /* TEST_HELPERS_H */
diff --git a/tests/src/threading_helpers.c b/tests/src/threading_helpers.c
index d1ac542..3a58bc7 100644
--- a/tests/src/threading_helpers.c
+++ b/tests/src/threading_helpers.c
@@ -24,6 +24,48 @@
#include "mbedtls/threading.h"
+/** Mutex usage verification framework.
+ *
+ * The mutex usage verification code below aims to detect bad usage of
+ * Mbed TLS's mutex abstraction layer at runtime. Note that this is solely
+ * about the use of the mutex itself, not about checking whether the mutex
+ * correctly protects whatever it is supposed to protect.
+ *
+ * The normal usage of a mutex is:
+ * ```
+ * digraph mutex_states {
+ * "UNINITIALIZED"; // the initial state
+ * "IDLE";
+ * "FREED";
+ * "LOCKED";
+ * "UNINITIALIZED" -> "IDLE" [label="init"];
+ * "FREED" -> "IDLE" [label="init"];
+ * "IDLE" -> "LOCKED" [label="lock"];
+ * "LOCKED" -> "IDLE" [label="unlock"];
+ * "IDLE" -> "FREED" [label="free"];
+ * }
+ * ```
+ *
+ * All bad transitions that can be unambiguously detected are reported.
+ * An attempt to use an uninitialized mutex cannot be detected in general
+ * since the memory content may happen to denote a valid state. For the same
+ * reason, a double init cannot be detected.
+ * All-bits-zero is the state of a freed mutex, which is distinct from an
+ * initialized mutex, so attempting to use zero-initialized memory as a mutex
+ * without calling the init function is detected.
+ *
+ * If an error is detected, this framework will report what happened and the
+ * test case will be marked as failed. Unfortunately, the error report cannot
+ * 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
+{
+ 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
+};
+
typedef struct
{
void (*init)( mbedtls_threading_mutex_t * );
@@ -33,6 +75,19 @@
} mutex_functions_t;
static mutex_functions_t mutex_functions;
+static void mbedtls_test_mutex_usage_error( mbedtls_threading_mutex_t *mutex,
+ const char *msg )
+{
+ (void) mutex;
+ if( mbedtls_test_info.mutex_usage_error == NULL )
+ mbedtls_test_info.mutex_usage_error = msg;
+ mbedtls_fprintf( stdout, "[mutex: %s] ", msg );
+ /* Don't mark the test as failed yet. This way, if the test fails later
+ * for a functional reason, the test framework will report the message
+ * and location for this functional reason. If the test passes,
+ * mbedtls_test_mutex_usage_check() will mark it as failed. */
+}
+
static void mbedtls_test_wrap_mutex_init( mbedtls_threading_mutex_t *mutex )
{
mutex_functions.init( mutex );
@@ -40,18 +95,67 @@
static void mbedtls_test_wrap_mutex_free( mbedtls_threading_mutex_t *mutex )
{
+ switch( mutex->is_valid )
+ {
+ case MUTEX_FREED:
+ mbedtls_test_mutex_usage_error( mutex, "free without init or double free" );
+ break;
+ case MUTEX_IDLE:
+ /* Do nothing. The underlying free function will reset is_valid
+ * to 0. */
+ break;
+ case MUTEX_LOCKED:
+ mbedtls_test_mutex_usage_error( mutex, "free without unlock" );
+ break;
+ default:
+ mbedtls_test_mutex_usage_error( mutex, "corrupted state" );
+ break;
+ }
mutex_functions.free( mutex );
}
static int mbedtls_test_wrap_mutex_lock( mbedtls_threading_mutex_t *mutex )
{
int ret = mutex_functions.lock( mutex );
+ switch( mutex->is_valid )
+ {
+ case MUTEX_FREED:
+ mbedtls_test_mutex_usage_error( mutex, "lock without init" );
+ break;
+ case MUTEX_IDLE:
+ if( ret == 0 )
+ mutex->is_valid = 2;
+ break;
+ case MUTEX_LOCKED:
+ mbedtls_test_mutex_usage_error( mutex, "double lock" );
+ break;
+ default:
+ mbedtls_test_mutex_usage_error( mutex, "corrupted state" );
+ break;
+ }
return( ret );
}
static int mbedtls_test_wrap_mutex_unlock( mbedtls_threading_mutex_t *mutex )
{
- return( mutex_functions.unlock( mutex ) );
+ int ret = mutex_functions.unlock( mutex );
+ switch( mutex->is_valid )
+ {
+ case MUTEX_FREED:
+ mbedtls_test_mutex_usage_error( mutex, "unlock without init" );
+ break;
+ case MUTEX_IDLE:
+ mbedtls_test_mutex_usage_error( mutex, "unlock without lock" );
+ break;
+ case MUTEX_LOCKED:
+ if( ret == 0 )
+ mutex->is_valid = MUTEX_IDLE;
+ break;
+ default:
+ mbedtls_test_mutex_usage_error( mutex, "corrupted state" );
+ break;
+ }
+ return( ret );
}
void mbedtls_test_mutex_usage_init( void )
@@ -66,4 +170,16 @@
mbedtls_mutex_unlock = &mbedtls_test_wrap_mutex_unlock;
}
+void mbedtls_test_mutex_usage_check( void )
+{
+ if( mbedtls_test_info.mutex_usage_error != NULL &&
+ mbedtls_test_info.result != MBEDTLS_TEST_RESULT_FAILED )
+ {
+ /* Functionally, the test passed. But there was a mutex usage error,
+ * so mark the test as failed after all. */
+ mbedtls_test_fail( "Mutex usage error", __LINE__, __FILE__ );
+ }
+ mbedtls_test_info.mutex_usage_error = NULL;
+}
+
#endif /* MBEDTLS_TEST_MUTEX_USAGE */
diff --git a/tests/suites/main_test.function b/tests/suites/main_test.function
index 57395ae..aa408ea 100644
--- a/tests/suites/main_test.function
+++ b/tests/suites/main_test.function
@@ -188,6 +188,10 @@
#else
fp( params );
#endif
+
+#if defined(MBEDTLS_TEST_MUTEX_USAGE)
+ mbedtls_test_mutex_usage_check( );
+#endif /* MBEDTLS_TEST_MUTEX_USAGE */
}
/**
