yuzu-emu/mbedtls
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Improve bignum documentation

Browse source 
Signed-off-by: Janos Follath <janos.follath@arm.com>
This commit is contained in:
Janos Follath 2022-08-11 17:42:59 +01:00
parent a30b4e5692
commit 6318468183
6 changed files with 53 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
library/bignum_core.h
View file

@ -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.

14
library/bignum_mod.h
View file

@ -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

11
library/bignum_mod_raw.h
View file

@ -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

3
library/constant_time.c
View file

@ -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-- )

9
library/constant_time_internal.h
View file

@ -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.

18
tests/suites/test_suite_mpi.data
View file

@ -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