AuroraMiddleware/mbedtls
1
0
Fork 0
Code Issues Pull Requests Releases 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-08 11:50:02 +01:00
parent 8ff0729dd7
commit dae1147596
4 changed files with 53 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
library/bignum_core.h
View File

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

39
library/bignum_mod.h
View File

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

20
library/bignum_mod_raw.h
View File

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

8
library/bignum_new.c
View File

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