From 128895775d4ccb64977f1d3f7020b85f19428fa8 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 9 Nov 2022 21:55:33 +0100 Subject: [PATCH] Document invariants of MPI objects Note that s must be +1 for zero. Note that p may be NULL for zero, when n is 0. Signed-off-by: Gilles Peskine --- include/mbedtls/bignum.h | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/include/mbedtls/bignum.h b/include/mbedtls/bignum.h index 9d15955f3..3bd1ca026 100644 --- a/include/mbedtls/bignum.h +++ b/include/mbedtls/bignum.h @@ -188,9 +188,27 @@ extern "C" { */ typedef struct mbedtls_mpi { - int MBEDTLS_PRIVATE(s); /*!< Sign: -1 if the mpi is negative, 1 otherwise */ - size_t MBEDTLS_PRIVATE(n); /*!< total # of limbs */ - mbedtls_mpi_uint *MBEDTLS_PRIVATE(p); /*!< pointer to limbs */ + /** Sign: -1 if the mpi is negative, 1 otherwise. + * + * The number 0 must be represented with `s = +1`. Although many library + * functions treat all-limbs-zero as equivalent to a valid representation + * of 0 regardless of the sign bit, there are exceptions, so bignum + * functions and external callers must always set \c s to +1 for the + * number zero. + * + * Note that this implies that calloc() or `... = {0}` does not create + * a valid MPI representation. You must call mbedtls_mpi_init(). + */ + int MBEDTLS_PRIVATE(s); + + /** Total number of limbs in \c p. */ + size_t MBEDTLS_PRIVATE(n); + + /** Pointer to limbs. + * + * This may be \c NULL if \c n is 0. + */ + mbedtls_mpi_uint *MBEDTLS_PRIVATE(p); } mbedtls_mpi;