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 <Gilles.Peskine@arm.com>
diff --git a/include/mbedtls/bignum.h b/include/mbedtls/bignum.h
index 60c1ce2..cede923 100644
--- a/include/mbedtls/bignum.h
+++ b/include/mbedtls/bignum.h
@@ -191,9 +191,27 @@
*/
typedef struct mbedtls_mpi
{
- int s; /*!< Sign: -1 if the mpi is negative, 1 otherwise */
- size_t n; /*!< total # of limbs */
- mbedtls_mpi_uint *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 s;
+
+ /** Total number of limbs in \c p. */
+ size_t n;
+
+ /** Pointer to limbs.
+ *
+ * This may be \c NULL if \c n is 0.
+ */
+ mbedtls_mpi_uint *p;
}
mbedtls_mpi;