Document mutex invariant for CTR_DRBG
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/include/mbedtls/ctr_drbg.h b/include/mbedtls/ctr_drbg.h
index 24d9870..e1f2c71 100644
--- a/include/mbedtls/ctr_drbg.h
+++ b/include/mbedtls/ctr_drbg.h
@@ -190,6 +190,13 @@
void *p_entropy; /*!< The context for the entropy function. */
#if defined(MBEDTLS_THREADING_C)
+ /* Invariant: the mutex is initialized if and only if f_entropy != NULL.
+ * This means that the mutex is initialized during the initial seeding
+ * in mbedtls_ctr_drbg_seed() and freed in mbedtls_ctr_drbg_free().
+ *
+ * Note that this invariant may change without notice. Do not rely on it
+ * and do not access the mutex directly in application code.
+ */
mbedtls_threading_mutex_t mutex;
#endif
}
diff --git a/library/ctr_drbg.c b/library/ctr_drbg.c
index 64b536a..e275f1a 100644
--- a/library/ctr_drbg.c
+++ b/library/ctr_drbg.c
@@ -99,6 +99,7 @@
return;
#if defined(MBEDTLS_THREADING_C)
+ /* The mutex is initialized iff f_entropy is set. */
if( ctx->f_entropy != NULL )
mbedtls_mutex_free( &ctx->mutex );
#endif
@@ -376,6 +377,7 @@
memset( key, 0, MBEDTLS_CTR_DRBG_KEYSIZE );
+ /* The mutex is initialized iff f_entropy is set. */
#if defined(MBEDTLS_THREADING_C)
mbedtls_mutex_init( &ctx->mutex );
#endif