From 6318468183412193ebc08c01531f122daf1c5da3 Mon Sep 17 00:00:00 2001 From: Janos Follath Date: Thu, 11 Aug 2022 17:42:59 +0100 Subject: [PATCH] Improve bignum documentation Signed-off-by: Janos Follath --- library/bignum_core.h | 28 ++++++++++++++++++++++------ library/bignum_mod.h | 14 +++++++------- library/bignum_mod_raw.h | 11 ++++++++--- library/constant_time.c | 3 ++- library/constant_time_internal.h | 9 +++++---- tests/suites/test_suite_mpi.data | 18 +++++++++--------- 6 files changed, 53 insertions(+), 30 deletions(-) diff --git a/library/bignum_core.h b/library/bignum_core.h index 3a789272c..117c3c5f3 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 ee9982a58..37aa9466f 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 a6c535b80..e8c2a7d65 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 cd3ec1064..d2649ceaf 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 7255b2a85..8915f8bcb 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 322e12e10..6b0b2d4bc 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