Be explicit about constant time bignum functions that must take a 0 or 1 condition value
Signed-off-by: Tom Cosgrove <tom.cosgrove@arm.com>
diff --git a/include/mbedtls/bignum.h b/include/mbedtls/bignum.h
index dd594c5..f209490 100644
--- a/include/mbedtls/bignum.h
+++ b/include/mbedtls/bignum.h
@@ -280,7 +280,7 @@
* \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 @@
* 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 @@
*
* \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.