Improve bignum documentation
Signed-off-by: Janos Follath <janos.follath@arm.com>
diff --git a/library/bignum_core.h b/library/bignum_core.h
index 3a78927..117c3c5 100644
--- a/library/bignum_core.h
+++ b/library/bignum_core.h
@@ -1,5 +1,10 @@
/**
- * Internal bignum functions
+ * Core bignum functions
+ *
+ * This interface only should be used by the legacy bignum module (bignum.h)
+ * and the modular bignum modules (bignum_mod.c, bignum_mod_raw.c). All other
+ * modules should use the high level modular bignum interface (bignum_mod.h)
+ * or the legacy bignum interface (bignum.h).
*
* Copyright The Mbed TLS Contributors
* SPDX-License-Identifier: Apache-2.0
@@ -34,7 +39,10 @@
*/
size_t mbedtls_mpi_core_clz( const mbedtls_mpi_uint x );
-/** Return the number of bits of an MPI.
+/** Return the the minimum number of bits required to represent the value held
+ * in the MPI.
+ *
+ * \note This function returns 0 if all the limbs of \p X are 0.
*
* \param X The address of the MPI.
* \param nx The number of limbs of \p X.
@@ -54,8 +62,8 @@
/** Import X from unsigned binary data, little endian.
*
- * The MPI needs to have enough limbs to store the full value (in particular,
- * this function does not skip 0s in the input).
+ * The MPI needs to have enough limbs to store the full value (including any
+ * most significant zero bytes in the input).
*
* \param X The address of the MPI.
* \param nx The number of limbs of \p X.
@@ -73,8 +81,8 @@
/** Import X from unsigned binary data, big endian.
*
- * The MPI needs to have enough limbs to store the full value (in particular,
- * this function does not skip 0s in the input).
+ * The MPI needs to have enough limbs to store the full value (including any
+ * most significant zero bytes in the input).
*
* \param X The address of the MPI.
* \param nx The number of limbs of \p X.
@@ -92,6 +100,10 @@
/** Export X into unsigned binary data, little endian.
*
+ * \note If \p buf is shorter than \p X the export is still successful if the
+ * value held in \p X fits in the buffer (that is, if enough of the most
+ * significant bytes of \p X are 0).
+ *
* \param X The address of the MPI.
* \param nx The number of limbs of \p X.
* \param buf The output buffer to export to.
@@ -108,6 +120,10 @@
/** Export X into unsigned binary data, big endian.
*
+ * \note If \p buf is shorter than \p X the export is still successful if the
+ * value held in \p X fits in the buffer (that is, if enough of the most
+ * significant bytes of \p X are 0).
+ *
* \param X The address of the MPI.
* \param nx The number of limbs of \p X.
* \param buf The output buffer to export to.
diff --git a/library/bignum_mod.h b/library/bignum_mod.h
index ee9982a..37aa946 100644
--- a/library/bignum_mod.h
+++ b/library/bignum_mod.h
@@ -1,5 +1,5 @@
/**
- * Internal bignum functions
+ * Modular bignum functions
*
* Copyright The Mbed TLS Contributors
* SPDX-License-Identifier: Apache-2.0
@@ -72,8 +72,8 @@
* modulus \p m.)
* \param m The address of the modulus related to \p r.
* \param p The address of the limb array storing the value of \p r. The
- * memory pointed by \p p will be used by \p r and must not be
- * freed or written until after mbedtls_mpi_mod_residue_release()
+ * memory pointed to by \p p will be used by \p r and must not be
+ * modified in any way until after mbedtls_mpi_mod_residue_release()
* is called.
* \param pn The number of limbs of \p p.
*
@@ -104,12 +104,12 @@
*/
void mbedtls_mpi_mod_modulus_init( mbedtls_mpi_mod_modulus *m );
-/** Setup a residue structure.
+/** Setup a modulus structure.
*
- * \param m The address of a modulus.
+ * \param m The address of the modulus structure to populate.
* \param p The address of the limb array storing the value of \p m. The
- * memory pointed by \p p will be used by \p r and must not be
- * freed or written until after
+ * memory pointed to by \p p will be used by \p m and must not
+ * be modified in any way until after
* mbedtls_mpi_mod_modulus_free() is called.
* \param pn The number of limbs of \p p.
* \param ext_rep The external representation to be used for residues
diff --git a/library/bignum_mod_raw.h b/library/bignum_mod_raw.h
index a6c535b..e8c2a7d 100644
--- a/library/bignum_mod_raw.h
+++ b/library/bignum_mod_raw.h
@@ -1,5 +1,10 @@
/**
- * Internal bignum functions
+ * Low level modular bignum functions
+ *
+ * This interface only should be used by the higher level modular bignum
+ * module (bignum_mod.c) and the ECP module (ecp.c, ecp_curves.c). All other
+ * modules should use the high level modular bignum interface (bignum_mod.h)
+ * or the legacy bignum interface (bignum.h).
*
* Copyright The Mbed TLS Contributors
* SPDX-License-Identifier: Apache-2.0
@@ -30,8 +35,8 @@
/** Import X from unsigned binary data.
*
- * The MPI needs to have enough limbs to store the full value (in particular,
- * this function does not skip 0s in the input).
+ * The MPI needs to have enough limbs to store the full value (including any
+ * most significant zero bytes in the input).
*
* \param X The address of the MPI. The size is determined by \p m. (In
* particular, it must have at least as many limbs as the modulus
diff --git a/library/constant_time.c b/library/constant_time.c
index cd3ec10..d2649ce 100644
--- a/library/constant_time.c
+++ b/library/constant_time.c
@@ -749,9 +749,10 @@
size_t len )
{
size_t i;
- /* The value of any of these variables is either 0 or 1 at all times. */
unsigned ret, cond, done;
+ /* The value of any of these variables is either 0 or 1 for the rest of
+ * their scope. */
ret = cond = done = 0;
for( i = len; i > 0; i-- )
diff --git a/library/constant_time_internal.h b/library/constant_time_internal.h
index 7255b2a..8915f8b 100644
--- a/library/constant_time_internal.h
+++ b/library/constant_time_internal.h
@@ -130,13 +130,14 @@
const mbedtls_mpi_uint y );
/**
- * \brief Check if an MPI is less than the other in constant time.
+ * \brief Check if one unsigned MPI is less than another in constant
+ * time.
*
* \param X The left-hand MPI. This must point to an array of limbs
- * with the same allocated length as Y.
+ * with the same allocated length as \p Y.
* \param Y The right-hand MPI. This must point to an array of limbs
- * with the same allocated length as X.
- * \param len The number of limbs in X and Y.
+ * with the same allocated length as \p X.
+ * \param len The number of limbs in \p X and \p Y.
*
* \return The result of the comparison:
* \c 1 if \p X is less than \p Y.
diff --git a/tests/suites/test_suite_mpi.data b/tests/suites/test_suite_mpi.data
index 322e12e..6b0b2d4 100644
--- a/tests/suites/test_suite_mpi.data
+++ b/tests/suites/test_suite_mpi.data
@@ -341,31 +341,31 @@
Test mbedtls_mpi_mod_raw_io #20 (writing with invalid endianness)
mbedtls_mpi_mod_raw_io:"":1:1:MBEDTLS_MPI_MOD_EXT_REP_INVALID:0:MBEDTLS_ERR_MPI_BAD_INPUT_DATA
-Test mbedtls_mpi_mod_raw_io #1 (Both representations invalid)
+Test mbedtls_mpi_mod_setup #1 (Both representations invalid)
mbedtls_mpi_mod_setup:MBEDTLS_MPI_MOD_EXT_REP_INVALID:MBEDTLS_MPI_MOD_REP_INVALID:MBEDTLS_ERR_MPI_BAD_INPUT_DATA
-Test mbedtls_mpi_mod_raw_io #2 (Internal representation invalid)
+Test mbedtls_mpi_mod_setup #2 (Internal representation invalid)
mbedtls_mpi_mod_setup:MBEDTLS_MPI_MOD_EXT_REP_LE:MBEDTLS_MPI_MOD_REP_INVALID:MBEDTLS_ERR_MPI_BAD_INPUT_DATA
-Test mbedtls_mpi_mod_raw_io #3 (Internal representation invalid)
+Test mbedtls_mpi_mod_setup #3 (Internal representation invalid)
mbedtls_mpi_mod_setup:MBEDTLS_MPI_MOD_EXT_REP_BE:MBEDTLS_MPI_MOD_REP_INVALID:MBEDTLS_ERR_MPI_BAD_INPUT_DATA
-Test mbedtls_mpi_mod_raw_io #4 (External representation invalid)
+Test mbedtls_mpi_mod_setup #4 (External representation invalid)
mbedtls_mpi_mod_setup:MBEDTLS_MPI_MOD_EXT_REP_INVALID:MBEDTLS_MPI_MOD_REP_MONTGOMERY:MBEDTLS_ERR_MPI_BAD_INPUT_DATA
-Test mbedtls_mpi_mod_raw_io #5 (External representation invalid)
+Test mbedtls_mpi_mod_setup #5 (External representation invalid)
mbedtls_mpi_mod_setup:MBEDTLS_MPI_MOD_EXT_REP_INVALID:MBEDTLS_MPI_MOD_REP_OPT_RED:MBEDTLS_ERR_MPI_BAD_INPUT_DATA
-Test mbedtls_mpi_mod_raw_io #6 (Both representations valid)
+Test mbedtls_mpi_mod_setup #6 (Both representations valid)
mbedtls_mpi_mod_setup:MBEDTLS_MPI_MOD_EXT_REP_BE:MBEDTLS_MPI_MOD_REP_OPT_RED:0
-Test mbedtls_mpi_mod_raw_io #7 (Both representations valid)
+Test mbedtls_mpi_mod_setup #7 (Both representations valid)
mbedtls_mpi_mod_setup:MBEDTLS_MPI_MOD_EXT_REP_BE:MBEDTLS_MPI_MOD_REP_MONTGOMERY:0
-Test mbedtls_mpi_mod_raw_io #8 (Both representations valid)
+Test mbedtls_mpi_mod_setup #8 (Both representations valid)
mbedtls_mpi_mod_setup:MBEDTLS_MPI_MOD_EXT_REP_LE:MBEDTLS_MPI_MOD_REP_OPT_RED:0
-Test mbedtls_mpi_mod_raw_io #9 (Both representations valid)
+Test mbedtls_mpi_mod_setup #9 (Both representations valid)
mbedtls_mpi_mod_setup:MBEDTLS_MPI_MOD_EXT_REP_LE:MBEDTLS_MPI_MOD_REP_MONTGOMERY:0
Base test mbedtls_mpi_read_binary #1