Merge pull request #6212 from tom-cosgrove-arm/explicit-warning-re-ct…

…-conditions-not-0-or-1-2.28

Backport 2.28: Be explicit about constant time bignum functions that must take a 0 or 1 condition value

include/mbedtls/bignum.h

@@ -280,7 +280,7 @@ void mbedtls_mpi_swap( mbedtls_mpi *X, mbedtls_mpi *Y );
  * \param Y The MPI to be assigned from. This must point to an
  * initialized MPI.
  * \param assign The condition deciding whether to perform the
- * assignment or not. Possible values:
+ * assignment or not. Must be either 0 or 1:
  * * \c 1: Perform the assignment `X = Y`.
  * * \c 0: Keep the original value of \p X.
  *
@@ -291,6 +291,10 @@ void mbedtls_mpi_swap( mbedtls_mpi *X, mbedtls_mpi *Y );
  * information through branch prediction and/or memory access
  * patterns analysis).
  *
+ * \warning If \p assign is neither 0 nor 1, the result of this function
+ * is indeterminate, and the resulting value in \p X might be
+ * neither its original value nor the value in \p Y.
+ *
  * \return \c 0 if successful.
  * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
  * \return Another negative error code on other kinds of failure.
@@ -303,24 +307,28 @@ int mbedtls_mpi_safe_cond_assign( mbedtls_mpi *X, const mbedtls_mpi *Y, unsigned
  *
  * \param X The first MPI. This must be initialized.
  * \param Y The second MPI. This must be initialized.
- * \param assign The condition deciding whether to perform
- * the swap or not. Possible values:
+ * \param swap  The condition deciding whether to perform
+ * the swap or not. Must be either 0 or 1:
  * * \c 1: Swap the values of \p X and \p Y.
  * * \c 0: Keep the original values of \p X and \p Y.
  *
  * \note This function is equivalent to
- * if( assign ) mbedtls_mpi_swap( X, Y );
+ * if( swap ) mbedtls_mpi_swap( X, Y );
  * except that it avoids leaking any information about whether
- * the assignment was done or not (the above code may leak
+ * the swap was done or not (the above code may leak
  * information through branch prediction and/or memory access
  * patterns analysis).
  *
+ * \warning If \p swap is neither 0 nor 1, the result of this function
+ * is indeterminate, and both \p X and \p Y might end up with
+ * values different to either of the original ones.
+ *
  * \return \c 0 if successful.
  * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
  * \return Another negative error code on other kinds of failure.
  *
  */
-int mbedtls_mpi_safe_cond_swap( mbedtls_mpi *X, mbedtls_mpi *Y, unsigned char assign );
+int mbedtls_mpi_safe_cond_swap( mbedtls_mpi *X, mbedtls_mpi *Y, unsigned char swap );
 
 /**
  * \brief Store integer value in MPI.

library/constant_time.c

@@ -272,7 +272,7 @@ unsigned mbedtls_ct_uint_if( unsigned condition,
  * \note if1 and if0 must be either 1 or -1, otherwise the result
  * is undefined.
  *
- * \param condition Condition to test.
+ * \param condition Condition to test; must be either 0 or 1.
  * \param if1 The first sign; must be either +1 or -1.
  * \param if0 The second sign; must be either +1 or -1.
  *