Add documentation for the functions

Signed-off-by: Gabor Mezei <[email protected]>

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;

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 */

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,