From a09697527bb537aae8559dc80ffad57ca6eb15ab Mon Sep 17 00:00:00 2001
From: Gabor Mezei <gabor.mezei@arm.com>
Date: Wed, 24 Nov 2021 16:26:33 +0100
Subject: [PATCH] Add documentation for the functions

Signed-off-by: Gabor Mezei <gabor.mezei@arm.com>
---
 library/constant_time.c          | 15 ---------------
 library/constant_time_internal.h | 21 +++++++++++++++++++++
 library/constant_time_invasive.h | 11 +++++++++--
 3 files changed, 30 insertions(+), 17 deletions(-)

diff --git a/library/constant_time.c b/library/constant_time.c
index b032550f8..d8870ae7f 100644
--- a/library/constant_time.c
+++ b/library/constant_time.c
@@ -327,10 +327,6 @@ void mbedtls_ct_mpi_uint_cond_assign( size_t n,
 
 #if defined(MBEDTLS_BASE64_C)
 
-/* Given a value in the range 0..63, return the corresponding Base64 digit.
- * The implementation assumes that letters are consecutive (e.g. ASCII
- * but not EBCDIC).
- */
 unsigned char mbedtls_ct_base64_enc_char( unsigned char value )
 {
     unsigned char digit = 0;
@@ -345,17 +341,6 @@ unsigned char mbedtls_ct_base64_enc_char( unsigned char value )
     return( digit );
 }
 
-/* Given a Base64 digit, return its value.
- * If c is not a Base64 digit ('A'..'Z', 'a'..'z', '0'..'9', '+' or '/'),
- * return -1.
- *
- * The implementation assumes that letters are consecutive (e.g. ASCII
- * but not EBCDIC).
- *
- * The implementation is constant-flow (no branch or memory access depending
- * on the value of c) unless the compiler inlines and optimizes a specific
- * access.
- */
 signed char mbedtls_ct_base64_dec_value( unsigned char c )
 {
     unsigned char val = 0;
diff --git a/library/constant_time_internal.h b/library/constant_time_internal.h
index c6f6f0ab1..053cf123c 100644
--- a/library/constant_time_internal.h
+++ b/library/constant_time_internal.h
@@ -169,8 +169,29 @@ void mbedtls_ct_mpi_uint_cond_assign( size_t n,
 
 #if defined(MBEDTLS_BASE64_C)
 
+/** Given a value in the range 0..63, return the corresponding Base64 digit.
+ *
+ * The implementation assumes that letters are consecutive (e.g. ASCII
+ * but not EBCDIC).
+ *
+ * \param value     A value in the range 0..63.
+ *
+ * \return          A base64 digit converted from \p value.
+ */
 unsigned char mbedtls_ct_base64_enc_char( unsigned char value );
 
+/** Given a Base64 digit, return its value.
+ *
+ * If c is not a Base64 digit ('A'..'Z', 'a'..'z', '0'..'9', '+' or '/'),
+ * return -1.
+ *
+ * The implementation assumes that letters are consecutive (e.g. ASCII
+ * but not EBCDIC).
+ *
+ * \param c     A base64 digit.
+ *
+ * \return      The value of the base64 digit \p c.
+ */
 signed char mbedtls_ct_base64_dec_value( unsigned char c );
 
 #endif /* MBEDTLS_BASE64_C */
diff --git a/library/constant_time_invasive.h b/library/constant_time_invasive.h
index 9008f5d43..4620ca137 100644
--- a/library/constant_time_invasive.h
+++ b/library/constant_time_invasive.h
@@ -31,9 +31,16 @@
 
 #if defined(MBEDTLS_TEST_HOOKS)
 
-/* Return 0xff if low <= c <= high, 0 otherwise.
+/** Turn a value into a mask:
+ * - if \p low <= \p c <= \p high,
+ *   return the all-bits 1 mask, aka (unsigned) -1
+ * - otherwise, return the all-bits 0 mask, aka 0
  *
- * Constant flow with respect to c.
+ * \param low   The value to analyze.
+ * \param high  The value to analyze.
+ * \param c     The value to analyze.
+ *
+ * \return      All-bits-one if \p low <= \p c <= \p high, otherwise zero.
  */
 unsigned char mbedtls_ct_uchar_mask_of_range( unsigned char low,
                                               unsigned char high,