From 93cec45af3de71894700b7824fae563939f46ebc Mon Sep 17 00:00:00 2001 From: Dave Rodgman Date: Mon, 31 Jul 2023 12:30:26 +0100 Subject: [PATCH] Improve docs for mbedtls_ct_compiler_opaque Signed-off-by: Dave Rodgman --- library/constant_time_impl.h | 13 +++++++++++++ library/constant_time_internal.h | 5 +++-- 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/library/constant_time_impl.h b/library/constant_time_impl.h index 191769b192..b2ef73f700 100644 --- a/library/constant_time_impl.h +++ b/library/constant_time_impl.h @@ -68,6 +68,19 @@ extern volatile mbedtls_ct_uint_t mbedtls_ct_zero; #endif +/** + * \brief Ensure that a value cannot be known at compile time. + * + * \param x The value to hide from the compiler. + * \return The same value that was passed in, such that the compiler + * cannot prove its value (even for calls of the form + * x = mbedtls_ct_compiler_opaque(1), x will be unknown). + * + * \note This is mainly used in constructing mbedtls_ct_condition_t + * values and performing operations over them, to ensure that + * there is no way for the compiler to ever know anything about + * the value of an mbedtls_ct_condition_t. + */ static inline mbedtls_ct_uint_t mbedtls_ct_compiler_opaque(mbedtls_ct_uint_t x) { #if defined(MBEDTLS_CT_ASM) diff --git a/library/constant_time_internal.h b/library/constant_time_internal.h index 79927c1f15..c15eaeb4d7 100644 --- a/library/constant_time_internal.h +++ b/library/constant_time_internal.h @@ -53,8 +53,9 @@ * function. * example: if (x) memcpy(...) => mbedtls_ct_memcpy_if(x, ...) * - * mbedtls_ct_condition_t should be treated as opaque and only manipulated - * via the functions in this header. + * mbedtls_ct_condition_t must be treated as opaque and only created and + * manipulated via the functions in this header. The compiler should never + * be able to prove anything about its value at compile-time. * * mbedtls_ct_uint_t is an unsigned integer type over which constant time * operations may be performed via the functions in this header. It is as big