Add documentation for new bignum functions
Signed-off-by: Gabor Mezei <gabor.mezei@arm.com>
diff --git a/library/bignum_core.h b/library/bignum_core.h
index 376a267..98a8c97 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 97b3fc7..a4f0248 100644
--- a/library/bignum_mod.h
+++ b/library/bignum_mod.h
@@ -63,21 +63,57 @@
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 21743e0..2d7fc81 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 51e1416..2245650 100644
--- a/library/bignum_new.c
+++ b/library/bignum_new.c
@@ -82,15 +82,6 @@
#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 @@
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 @@
/* 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;