diff --git a/library/bignum_core.h b/library/bignum_core.h
index 3a789272c4..117c3c5f36 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 @@ void mbedtls_mpi_core_bigendian_to_host( mbedtls_mpi_uint * const X,
/** 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 @@ int mbedtls_mpi_core_read_le( mbedtls_mpi_uint *X,
/** 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.
@@ -91,6 +99,10 @@ int mbedtls_mpi_core_read_be( mbedtls_mpi_uint *X,
size_t buflen );
/** 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.
@@ -107,6 +119,10 @@ int mbedtls_mpi_core_write_le( const mbedtls_mpi_uint *X,
size_t buflen );
/** 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.
diff --git a/library/bignum_mod.h b/library/bignum_mod.h
index ee9982a58e..37aa9466f4 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 @@ typedef struct {
* 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_residue_release( mbedtls_mpi_mod_residue *r );
*/
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 a6c535b80a..e8c2a7d652 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 cd3ec10647..d2649ceaff 100644
--- a/library/constant_time.c
+++ b/library/constant_time.c
@@ -749,9 +749,10 @@ unsigned mbedtls_mpi_core_lt_ct( const mbedtls_mpi_uint *X,
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 7255b2a857..8915f8bcb6 100644
--- a/library/constant_time_internal.h
+++ b/library/constant_time_internal.h
@@ -130,13 +130,14 @@ unsigned mbedtls_ct_mpi_uint_lt( const mbedtls_mpi_uint x,
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 322e12e10b..6b0b2d4bce 100644
--- a/tests/suites/test_suite_mpi.data
+++ b/tests/suites/test_suite_mpi.data
@@ -341,31 +341,31 @@ mbedtls_mpi_mod_raw_io:"":1:1:MBEDTLS_MPI_MOD_EXT_REP_INVALID:MBEDTLS_ERR_MPI_BA
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