From 37b06360b3685b5e136f1a44388faa1334dc9d0b Mon Sep 17 00:00:00 2001 From: Gabor Mezei Date: Tue, 2 Aug 2022 17:22:18 +0200 Subject: [PATCH] Add documentation for new bignum functions Signed-off-by: Gabor Mezei --- library/bignum_core.h | 69 ++++++++++++++++++++++++++++++++++++++++ library/bignum_mod.h | 42 ++++++++++++++++++++++-- library/bignum_mod_raw.h | 29 +++++++++++++++++ library/bignum_new.c | 19 ++++++----- 4 files changed, 146 insertions(+), 13 deletions(-) diff --git a/library/bignum_core.h b/library/bignum_core.h index 376a267de..98a8c97c2 100644 --- a/library/bignum_core.h +++ b/library/bignum_core.h @@ -42,28 +42,97 @@ #define BITS_TO_LIMBS(i) ( (i) / biL + ( (i) % biL != 0 ) ) #define CHARS_TO_LIMBS(i) ( (i) / ciL + ( (i) % ciL != 0 ) ) +/** Count leading zero bits in a given integer. + * + * \param x Integer to count leading zero bits. + * + * \return Tne munber of leading zero bits in \p x. + */ size_t mbedtls_mpi_core_clz( const mbedtls_mpi_uint x ); +/** Return the number of bits of an MPI. + * + * \param X The address of the MPI. + * \param nx The number of limbs of \p X. + * + * \return Tne number of bits in \p X. + */ size_t mbedtls_mpi_core_bitlen( const mbedtls_mpi_uint *X, size_t nx ); +/** Convert a big-endian byte array aligned to the size of mbedtls_mpi_uint + * into the storage form used by mbedtls_mpi. + * + * \param X The address of the MPI. + * \param limbs The number of limbs of \p X. + */ void mbedtls_mpi_core_bigendian_to_host( mbedtls_mpi_uint * const X, size_t limbs ); +/** Import X from unsigned binary data, little endian. + * + * This function is guaranteed to return an MPI with at least the necessary + * number of limbs (in particular, it does not skip 0s in the input). + * + * \param X The address of the MPI. + * \param nx The number of limbs of \p X. + * \param buf The input buffer to import from. + * \param buflen Tne length in bytes of \p buf. + * + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p X isn't + * large enough to hold the value in \p buf. + */ int mbedtls_mpi_core_read_le( mbedtls_mpi_uint *X, size_t nx, const unsigned char *buf, size_t buflen ); +/** Import X from unsigned binary data, big endian. + * + * This function is guaranteed to return an MPI with exactly the necessary + * number of limbs (in particular, it does not skip 0s in the input). + * + * \param X The address of the MPI. + * \param nx The number of limbs of \p X. + * \param buf The input buffer to import from. + * \param buflen Tne length in bytes of \p buf. + * + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p X isn't + * large enough to hold the value in \p buf. + */ int mbedtls_mpi_core_read_be( mbedtls_mpi_uint *X, size_t nx, const unsigned char *buf, size_t buflen ); +/** Export X into unsigned binary data, little endian. + * + * \param X The address of the MPI. + * \param nx The number of limbs of \p X. + * \param buf The output buffer to import. + * \param buflen Tne length in bytes of \p buf. + * + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p buf isn't + * large enough to hold the value of \p X. + */ int mbedtls_mpi_core_write_le( const mbedtls_mpi_uint *X, size_t nx, unsigned char *buf, size_t buflen ); +/** Export X into unsigned binary data, big endian. + * + * \param X The address of the MPI. + * \param nx The number of limbs of \p X. + * \param buf The output buffer to import. + * \param buflen Tne length in bytes of \p buf. + * + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p buf isn't + * large enough to hold the value of \p X. + */ int mbedtls_mpi_core_write_be( const mbedtls_mpi_uint *X, size_t nx, unsigned char *buf, diff --git a/library/bignum_mod.h b/library/bignum_mod.h index 97b3fc712..a4f024853 100644 --- a/library/bignum_mod.h +++ b/library/bignum_mod.h @@ -63,21 +63,57 @@ typedef enum MBEDTLS_MPI_MOD_EXT_REP_BE } mbedtls_mpi_mod_ext_rep; -void mbedtls_mpi_mod_residue_release( mbedtls_mpi_mod_residue *r ); +/** Setup a residue structure. + * + * \param r The address of residue to setup. The size is determined by \p m. + * \param m The address of a modulus related to \p r. + * \param p The address of the MPI used for \p r. + * \param pn The number of limbs of \p p. + * + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \p r, \p m or \p p is + * #NULL pointer or if \p p is less then \p m. + */ int mbedtls_mpi_mod_residue_setup( mbedtls_mpi_mod_residue *r, mbedtls_mpi_mod_modulus *m, mbedtls_mpi_uint *p, size_t pn ); +/** Unbind elements of a residue structure. + * + * \param r The address of residue to release. + */ +void mbedtls_mpi_mod_residue_release( mbedtls_mpi_mod_residue *r ); + +/** Initialize a modulus structure. + * + * \param m The address of a modulus. + */ void mbedtls_mpi_mod_modulus_init( mbedtls_mpi_mod_modulus *m ); -void mbedtls_mpi_mod_modulus_free( mbedtls_mpi_mod_modulus *m ); - +/** Setup a residue structure. + * + * \param m The address of a modulus. + * \param p The address of the MPI used for \p m. + * \param pn The number of limbs of \p p. + * \param ext_rep The external representation of \p m (eg. byte order). + * \param int_rep The selector which representation is used. + * + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \p m or \p p is + * #NULL pointer or if \p ext_rep or \p int_rep is invalid. + */ int mbedtls_mpi_mod_modulus_setup( mbedtls_mpi_mod_modulus *m, mbedtls_mpi_uint *p, size_t pn, int ext_rep, int int_rep ); +/** Unbind elements of a modulus structure. + * + * \param m The address of a modulus. + */ +void mbedtls_mpi_mod_modulus_free( mbedtls_mpi_mod_modulus *m ); + #endif /* MBEDTLS_BIGNUM_MOD_H */ diff --git a/library/bignum_mod_raw.h b/library/bignum_mod_raw.h index 21743e0d0..2d7fc8167 100644 --- a/library/bignum_mod_raw.h +++ b/library/bignum_mod_raw.h @@ -26,11 +26,40 @@ #include "mbedtls/bignum.h" #endif +/** Import X from unsigned binary data. + * + * This function is guaranteed to return an MPI with exactly the necessary + * number of limbs (in particular, it does not skip 0s in the input). + * + * \param X The address of the MPI. The size is determined by \p m. + * \param m The address of a modulus related to \p X. + * \param buf The input buffer to import from. + * \param buflen Tne length in bytes of \p buf. + * + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p X isn't + * large enough to hold the value in \p buf. + * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if the external reprezentation + * of \p m is invalid or \p X is less then \p m. + */ int mbedtls_mpi_mod_raw_read( mbedtls_mpi_uint *X, mbedtls_mpi_mod_modulus *m, unsigned char *buf, size_t buflen ); +/** Export X into unsigned binary data. + * + * \param X The address of the MPI. The size is determined by \p m. + * \param m The address of a modulus related to \p X. + * \param buf The output buffer to import. + * \param buflen Tne length in bytes of \p buf. + * + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p buf isn't + * large enough to hold the value of \p X. + * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if the external reprezentation + * of \p m is invalid. + */ int mbedtls_mpi_mod_raw_write( mbedtls_mpi_uint *X, mbedtls_mpi_mod_modulus *m, unsigned char *buf, diff --git a/library/bignum_new.c b/library/bignum_new.c index 51e141604..2245650ae 100644 --- a/library/bignum_new.c +++ b/library/bignum_new.c @@ -82,15 +82,6 @@ size_t mbedtls_mpi_core_bitlen( const mbedtls_mpi_uint *X, size_t nx ) #define GET_BYTE( X, i ) \ ( ( ( X )[( i ) / ciL] >> ( ( ( i ) % ciL ) * 8 ) ) & 0xff ) -void mbedtls_mpi_mod_residue_release( mbedtls_mpi_mod_residue *r ) -{ - if ( r == NULL ) - return; - - r->n = 0; - r->p = NULL; -} - int mbedtls_mpi_mod_residue_setup( mbedtls_mpi_mod_residue *r, mbedtls_mpi_mod_modulus *m, mbedtls_mpi_uint *p, @@ -108,6 +99,15 @@ int mbedtls_mpi_mod_residue_setup( mbedtls_mpi_mod_residue *r, return( 0 ); } +void mbedtls_mpi_mod_residue_release( mbedtls_mpi_mod_residue *r ) +{ + if ( r == NULL ) + return; + + r->n = 0; + r->p = NULL; +} + void mbedtls_mpi_mod_modulus_init( mbedtls_mpi_mod_modulus *m ) { if ( m == NULL ) @@ -206,7 +206,6 @@ static int mpi_core_clear( mbedtls_mpi_uint *X, /* Convert a big-endian byte array aligned to the size of mbedtls_mpi_uint * into the storage form used by mbedtls_mpi. */ - static mbedtls_mpi_uint mpi_bigendian_to_host_c( mbedtls_mpi_uint x ) { uint8_t i;