Add documentation for the functions

Signed-off-by: gabor-mezei-arm <[email protected]>

library/constant_time.c

@@ -62,11 +62,6 @@ int mbedtls_cf_memcmp( const void *a, const void *b, size_t n )
     return( (int)diff );
 }
 
-/** Turn zero-or-nonzero into zero-or-all-bits-one, without branches.
- *
- * \param value     The value to analyze.
- * \return          Zero if \p value is zero, otherwise all-bits-one.
- */
 unsigned mbedtls_cf_uint_mask( unsigned value )
 {
     /* MSVC has a warning about unary minus on unsigned, but this is
@@ -81,17 +76,6 @@ unsigned mbedtls_cf_uint_mask( unsigned value )
 #endif
 }
 
-/*
- * Turn a value into a mask:
- * - if value != 0, return the all-bits 1 mask, aka (size_t) -1
- * - if value == 0, return the all-bits 0 mask, aka 0
- *
- * This function can be used to write constant-time code by replacing branches
- * with bit operations using masks.
- *
- * This function is implemented without using comparison operators, as those
- * might be translated to branches by some compilers on some platforms.
- */
 size_t mbedtls_cf_size_mask( size_t value )
 {
     /* MSVC has a warning about unary minus on unsigned integer types,
@@ -123,18 +107,6 @@ mbedtls_mpi_uint mbedtls_cf_mpi_uint_mask( mbedtls_mpi_uint value )
 }
 
 #endif /* MBEDTLS_BIGNUM_C */
-
-/*
- * Constant-flow mask generation for "less than" comparison:
- * - if x < y,  return all bits 1, that is (size_t) -1
- * - otherwise, return all bits 0, that is 0
- *
- * This function can be used to write constant-time code by replacing branches
- * with bit operations using masks.
- *
- * This function is implemented without using comparison operators, as those
- * might be translated to branches by some compilers on some platforms.
- */
 size_t mbedtls_cf_size_mask_lt( size_t x, size_t y )
 {
     /* This has the most significant bit set if and only if x < y */
@@ -149,17 +121,6 @@ size_t mbedtls_cf_size_mask_lt( size_t x, size_t y )
     return( mask );
 }
 
-/*
- * Constant-flow mask generation for "greater or equal" comparison:
- * - if x >= y, return all bits 1, that is (size_t) -1
- * - otherwise, return all bits 0, that is 0
- *
- * This function can be used to write constant-time code by replacing branches
- * with bit operations using masks.
- *
- * This function is implemented without using comparison operators, as those
- * might be translated to branches by some compilers on some platforms.
- */
 size_t mbedtls_cf_size_mask_ge( size_t x, size_t y )
 {
     return( ~mbedtls_cf_size_mask_lt( x, y ) );
@@ -190,17 +151,6 @@ unsigned mbedtls_cf_uint_bool_eq( unsigned x, unsigned y )
     return( 1 ^ diff1 );
 }
 
-/*
- * Constant-flow boolean "equal" comparison:
- * return x == y
- *
- * This function can be used to write constant-time code by replacing branches
- * with bit operations - it can be used in conjunction with
- * mbedtls_cf_size_mask().
- *
- * This function is implemented without using comparison operators, as those
- * might be translated to branches by some compilers on some platforms.
- */
 unsigned mbedtls_cf_size_bool_eq( size_t x, size_t y )
 {
     /* diff = 0 if x == y, non-zero otherwise */
@@ -226,32 +176,14 @@ unsigned mbedtls_cf_size_bool_eq( size_t x, size_t y )
     return( 1 ^ diff1 );
 }
 
-/** Check whether a size is out of bounds, without branches.
- *
- * This is equivalent to `size > max`, but is likely to be compiled to
- * to code using bitwise operation rather than a branch.
- *
- * \param x         Size to check.
- * \param y         Maximum desired value for \p size.
- * \return          \c 0 if `size <= max`.
- * \return          \c 1 if `size > max`.
- */
 unsigned mbedtls_cf_size_gt( size_t x, size_t y )
 {
     /* Return the sign bit (1 for negative) of (max - x). */
     return( ( y - x ) >> ( sizeof( size_t ) * 8 - 1 ) );
 }
 
-
 #if defined(MBEDTLS_BIGNUM_C)
 
-/** Decide if an integer is less than the other, without branches.
- *
- * \param x         First integer.
- * \param y         Second integer.
- *
- * \return          1 if \p x is less than \p y, 0 otherwise
- */
 unsigned mbedtls_cf_mpi_uint_lt( const mbedtls_mpi_uint x,
                                  const mbedtls_mpi_uint y )
 {
@@ -282,17 +214,6 @@ unsigned mbedtls_cf_mpi_uint_lt( const mbedtls_mpi_uint x,
 
 #endif /* MBEDTLS_BIGNUM_C */
 
-/** Choose between two integer values, without branches.
- *
- * This is equivalent to `condition ? if1 : if0`, but is likely to be compiled
- * to code using bitwise operation rather than a branch.
- *
- * \param condition Condition to test.
- * \param if1       Value to use if \p condition is nonzero.
- * \param if0       Value to use if \p condition is zero.
- * \return          \c if1 if \p condition is nonzero, otherwise \c if0.
- */
-
 unsigned mbedtls_cf_uint_if( unsigned condition, unsigned if1, unsigned if0 )
 {
     unsigned mask = mbedtls_cf_uint_mask( condition );
@@ -355,9 +276,6 @@ void mbedtls_cf_uchar_cond_assign( unsigned char * dest,
     *dest = ( ( src ) & mask ) | ( ( *dest ) & ~mask );
 }
 
-/*
- * Constant flow conditional assignment to uint_32
- */
 void mbedtls_cf_uint32_cond_assign( uint32_t * dest,
                                     const uint32_t src,
                                     uint32_t condition )
@@ -383,12 +301,6 @@ void mbedtls_cf_uint32_cond_assign( uint32_t * dest,
 
 #if defined(MBEDTLS_BIGNUM_C)
 
-/*
- * Conditionally assign dest = src, without leaking information
- * about whether the assignment was made or not.
- * dest and src must be arrays of limbs of size n.
- * condition must be 0 or 1.
- */
 void mbedtls_cf_mpi_uint_cond_assign( size_t n,
                                       mbedtls_mpi_uint *dest,
                                       const mbedtls_mpi_uint *src,
@@ -416,9 +328,6 @@ void mbedtls_cf_mpi_uint_cond_assign( size_t n,
 
 #endif /* MBEDTLS_BIGNUM_C */
 
-/*
- * Constant flow lookup into table.
- */
 unsigned char mbedtls_cf_uchar_table_lookup( const unsigned char * const table,
                                              const size_t table_size,
                                              const size_t table_index )
@@ -436,23 +345,6 @@ unsigned char mbedtls_cf_uchar_table_lookup( const unsigned char * const table,
     return result;
 }
 
-/** Shift some data towards the left inside a buffer without leaking
- * the length of the data through side channels.
- *
- * `mbedtls_cf_mem_move_to_left(start, total, offset)` is functionally
- * equivalent to
- * ```
- * memmove(start, start + offset, total - offset);
- * memset(start + offset, 0, total - offset);
- * ```
- * but it strives to use a memory access pattern (and thus total timing)
- * that does not depend on \p offset. This timing independence comes at
- * the expense of performance.
- *
- * \param start     Pointer to the start of the buffer.
- * \param total     Total size of the buffer.
- * \param offset    Offset from which to copy \p total - \p offset bytes.
- */
 void mbedtls_cf_mem_move_to_left( void *start,
                                   size_t total,
                                   size_t offset )
@@ -477,15 +369,6 @@ void mbedtls_cf_mem_move_to_left( void *start,
     }
 }
 
-/*
- * Constant-flow conditional memcpy:
- *  - if c1 == c2, equivalent to memcpy(dst, src, len),
- *  - otherwise, a no-op,
- * but with execution flow independent of the values of c1 and c2.
- *
- * This function is implemented without using comparison operators, as those
- * might be translated to branches by some compilers on some platforms.
- */
 void mbedtls_cf_memcpy_if_eq( unsigned char *dest,
                               const unsigned char *src,
                               size_t len,
@@ -592,11 +475,6 @@ int mbedtls_ssl_cf_hmac( mbedtls_md_context_t *ctx,
     return( ret );
 }
 
-/*
- * Constant-flow memcpy from variable position in buffer.
- * - functionally equivalent to memcpy(dst, src + offset_secret, len)
- * - but with execution flow independent from the value of offset_secret.
- */
 void mbedtls_ssl_cf_memcpy_offset( unsigned char *dst,
                                    const unsigned char *src_base,
                                    size_t offset_secret,
@@ -653,12 +531,6 @@ int mbedtls_mpi_safe_cond_assign( mbedtls_mpi *X,
     return( ret );
 }
 
-/*
- * Conditionally swap X and Y, without leaking information
- * about whether the swap was made or not.
- * Here it is not ok to simply swap the pointers, which whould lead to
- * different memory access patterns when X and Y are used afterwards.
- */
 int mbedtls_mpi_safe_cond_swap( mbedtls_mpi *X,
                                 mbedtls_mpi *Y,
                                 unsigned char swap )
@@ -695,9 +567,6 @@ int mbedtls_mpi_safe_cond_swap( mbedtls_mpi *X,
     return( ret );
 }
 
-/*
- * Compare signed values in constant time
- */
 int mbedtls_mpi_lt_mpi_ct( const mbedtls_mpi *X,
                            const mbedtls_mpi *Y,
                            unsigned *ret )