diff --git a/library/bignum_core.h b/library/bignum_core.h index 622f0188f4..2141640cfd 100644 --- a/library/bignum_core.h +++ b/library/bignum_core.h @@ -54,8 +54,8 @@ void mbedtls_mpi_core_bigendian_to_host( mbedtls_mpi_uint * const X, /** 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). + * The MPI needs to have enough limbs to store the full value (in particular, + * this function does not skip 0s in the input). * * \param X The address of the MPI. * \param nx The number of limbs of \p X. @@ -73,8 +73,8 @@ int mbedtls_mpi_core_read_le( mbedtls_mpi_uint *X, /** 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). + * The MPI needs to have enough limbs to store the full value (in particular, + * this function does not skip 0s in the input). * * \param X The address of the MPI. * \param nx The number of limbs of \p X. @@ -94,7 +94,7 @@ int mbedtls_mpi_core_read_be( mbedtls_mpi_uint *X, * * \param X The address of the MPI. * \param nx The number of limbs of \p X. - * \param buf The output buffer to import. + * \param buf The output buffer to export to. * \param buflen The length in bytes of \p buf. * * \return \c 0 if successful. @@ -110,7 +110,7 @@ int mbedtls_mpi_core_write_le( const mbedtls_mpi_uint *X, * * \param X The address of the MPI. * \param nx The number of limbs of \p X. - * \param buf The output buffer to import. + * \param buf The output buffer to export to. * \param buflen The length in bytes of \p buf. * * \return \c 0 if successful. diff --git a/library/bignum_mod.h b/library/bignum_mod.h index a4f0248536..254a744ff4 100644 --- a/library/bignum_mod.h +++ b/library/bignum_mod.h @@ -67,13 +67,19 @@ typedef enum /** 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. + * (In particular, it must have at least as many limbs as the + * 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() + * is called. * \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. + * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \p r, \p m or \p p is #NULL + * pointer, \p pn is less than the limbs in \p m or if \p p is not + * less than \p m. */ int mbedtls_mpi_mod_residue_setup( mbedtls_mpi_mod_residue *r, mbedtls_mpi_mod_modulus *m, @@ -81,6 +87,12 @@ int mbedtls_mpi_mod_residue_setup( mbedtls_mpi_mod_residue *r, size_t pn ); /** Unbind elements of a residue structure. + * + * This function removes the reference to the limb array that was passed to + * mbedtls_mpi_mod_residue_setup() to make it safe to free or use again. + * + * This function invalidates \p r and it must not be used until after + * mbedtls_mpi_mod_residue_setup() is called on it again. * * \param r The address of residue to release. */ @@ -95,10 +107,15 @@ void mbedtls_mpi_mod_modulus_init( 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 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 + * mbedtls_mpi_mod_modulus_free() is called. * \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. + * \param ext_rep The external representation to be used for residues + * associated with \p m (see #mbedtls_mpi_mod_ext_rep). + * \param int_rep The internal representation to be used for residues + * associated with \p m (see #mbedtls_mpi_mod_rep_selector). * * \return \c 0 if successful. * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \p m or \p p is @@ -110,7 +127,13 @@ int mbedtls_mpi_mod_modulus_setup( mbedtls_mpi_mod_modulus *m, int ext_rep, int int_rep ); -/** Unbind elements of a modulus structure. +/** Free elements of a modulus structure. + * + * This function frees any memory allocated by mbedtls_mpi_mod_modulus_setup(). + * + * \warning This function does not free the limb array passed to + * mbedtls_mpi_mod_modulus_setup() only removes the reference to it, + * making it safe to free or to use it again. * * \param m The address of a modulus. */ diff --git a/library/bignum_mod_raw.h b/library/bignum_mod_raw.h index 8f0f0f25ef..85ca533da5 100644 --- a/library/bignum_mod_raw.h +++ b/library/bignum_mod_raw.h @@ -28,11 +28,13 @@ /** 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). + * The MPI needs to have enough limbs to store the full value (in particular, + * this function 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 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 + * \p m.) + * \param m The address of the modulus related to \p X. * \param buf The input buffer to import from. * \param buflen The length in bytes of \p buf. * @@ -40,7 +42,7 @@ * \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 representation - * of \p m is invalid or \p X is less then \p m. + * of \p m is invalid or \p X is not less than \p m. */ int mbedtls_mpi_mod_raw_read( mbedtls_mpi_uint *X, mbedtls_mpi_mod_modulus *m, @@ -49,9 +51,11 @@ int mbedtls_mpi_mod_raw_read( mbedtls_mpi_uint *X, /** 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 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 + * \p m.) + * \param m The address of the modulus related to \p X. + * \param buf The output buffer to export to. * \param buflen The length in bytes of \p buf. * * \return \c 0 if successful. diff --git a/library/bignum_new.c b/library/bignum_new.c index d1253f8d00..2613941485 100644 --- a/library/bignum_new.c +++ b/library/bignum_new.c @@ -313,8 +313,8 @@ void mbedtls_mpi_core_bigendian_to_host( mbedtls_mpi_uint * const X, /* * 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). + * The MPI needs to have enough limbs to store the full value (in particular, + * this function does not skip 0s in the input). */ int mbedtls_mpi_core_read_le( mbedtls_mpi_uint *X, size_t nx, @@ -338,8 +338,8 @@ cleanup: /* * 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). + * The MPI needs to have enough limbs to store the full value (in particular, + * this function does not skip 0s in the input). */ int mbedtls_mpi_core_read_be( mbedtls_mpi_uint *X, size_t nx,