Merge pull request #6766 from wernerlewis/bignum_mod_docs
Bignum: document conventions for bignum mod and mod_raw
diff --git a/library/bignum_mod.h b/library/bignum_mod.h
index 11b4e98..f089f65 100644
--- a/library/bignum_mod.h
+++ b/library/bignum_mod.h
@@ -2,6 +2,63 @@
* Modular bignum functions
*
* This module implements operations on integers modulo some fixed modulus.
+ *
+ * The functions in this module obey the following conventions unless
+ * explicitly indicated otherwise:
+ *
+ * - **Modulus parameters**: the modulus is passed as a pointer to a structure
+ * of type #mbedtls_mpi_mod_modulus. The structure must be set up with an
+ * array of limbs storing the bignum value of the modulus. The modulus must
+ * be odd and is assumed to have no leading zeroes. The modulus is usually
+ * named \c N and is usually input-only. Functions which take a parameter
+ * of type \c const #mbedtls_mpi_mod_modulus* must not modify its value.
+ * - **Bignum parameters**: Bignums are passed as pointers to an array of
+ * limbs or to a #mbedtls_mpi_mod_residue structure. A limb has the type
+ * #mbedtls_mpi_uint. Residues must be initialized before use, and must be
+ * associated with the modulus \c N. Unless otherwise specified:
+ * - Bignum parameters called \c A, \c B, ... are inputs and are not
+ * modified by the function. Functions which take a parameter of
+ * type \c const #mbedtls_mpi_mod_residue* must not modify its value.
+ * - Bignum parameters called \c X, \c Y, ... are outputs or input-output.
+ * The initial bignum value of output-only parameters is ignored, but
+ * they must be set up and associated with the modulus \c N. Some
+ * functions (typically constant-flow) require that the limbs in an
+ * output residue are initialized.
+ * - Bignum parameters called \c p are inputs used to set up a modulus or
+ * residue. These must be pointers to an array of limbs.
+ * - \c T is a temporary storage area. The initial content of such a
+ * parameter is ignored and the final content is unspecified.
+ * - Some functions use different names, such as \c r for the residue.
+ * - **Bignum sizes**: bignum sizes are always expressed in limbs. Both
+ * #mbedtls_mpi_mod_modulus and #mbedtls_mpi_mod_residue have a \c limbs
+ * member storing its size. All bignum parameters must have the same
+ * number of limbs as the modulus. All bignum sizes must be at least 1 and
+ * must be significantly less than #SIZE_MAX. The behavior if a size is 0 is
+ * undefined.
+ * - **Bignum representation**: the representation of inputs and outputs is
+ * specified by the \c int_rep field of the modulus.
+ * - **Parameter ordering**: for bignum parameters, outputs come before inputs.
+ * The modulus is passed after residues. Temporaries come last.
+ * - **Aliasing**: in general, output bignums may be aliased to one or more
+ * inputs. Modulus values may not be aliased to any other parameter. Outputs
+ * may not be aliased to one another. Temporaries may not be aliased to any
+ * other parameter.
+ * - **Overlap**: apart from aliasing of residue pointers (where two residue
+ * arguments are equal pointers), overlap is not supported and may result
+ * in undefined behavior.
+ * - **Error handling**: functions generally check compatibility of input
+ * sizes. Most functions will not check that input values are in canonical
+ * form (i.e. that \c A < \c N), this is only checked during setup of a
+ * residue structure.
+ * - **Modular representatives**: all functions expect inputs to be in the
+ * range [0, \c N - 1] and guarantee outputs in the range [0, \c N - 1].
+ * Residues are set up with an associated modulus, and operations are only
+ * guaranteed to work if the modulus is associated with all residue
+ * parameters. If a residue is passed with a modulus other than the one it
+ * is associated with, then it may be out of range. If an input is out of
+ * range, outputs are fully unspecified, though bignum values out of range
+ * should not cause buffer overflows (beware that this is not extensively
+ * tested).
*/
/*
diff --git a/library/bignum_mod_raw.h b/library/bignum_mod_raw.h
index f9968ba..e6237b3 100644
--- a/library/bignum_mod_raw.h
+++ b/library/bignum_mod_raw.h
@@ -11,6 +11,51 @@
* the wrong size. The functions in bignum_mod.h provide a higher-level
* interface that includes protections against accidental misuse, at the
* expense of code size and sometimes more cumbersome memory management.
+ *
+ * The functions in this module obey the following conventions unless
+ * explicitly indicated otherwise:
+ * - **Modulus parameters**: the modulus is passed as a pointer to a structure
+ * of type #mbedtls_mpi_mod_modulus. The structure must be set up with an
+ * array of limbs storing the bignum value of the modulus. The modulus must
+ * be odd and is assumed to have no leading zeroes. The modulus is usually
+ * named \c N and is usually input-only.
+ * - **Bignum parameters**: Bignums are passed as pointers to an array of
+ * limbs. A limb has the type #mbedtls_mpi_uint. Unless otherwise specified:
+ * - Bignum parameters called \c A, \c B, ... are inputs, and are not
+ * modified by the function.
+ * - Bignum parameters called \c X, \c Y are outputs or input-output.
+ * The initial content of output-only parameters is ignored.
+ * - \c T is a temporary storage area. The initial content of such a
+ * parameter is ignored and the final content is unspecified.
+ * - **Bignum sizes**: bignum sizes are usually expressed by the \c limbs
+ * member of the modulus argument. All bignum parameters must have the same
+ * number of limbs as the modulus. All bignum sizes must be at least 1 and
+ * must be significantly less than #SIZE_MAX. The behavior if a size is 0 is
+ * undefined.
+ * - **Bignum representation**: the representation of inputs and outputs is
+ * specified by the \c int_rep field of the modulus for arithmetic
+ * functions. Utility functions may allow for different representation.
+ * - **Parameter ordering**: for bignum parameters, outputs come before inputs.
+ * The modulus is passed after other bignum input parameters. Temporaries
+ * come last.
+ * - **Aliasing**: in general, output bignums may be aliased to one or more
+ * inputs. Modulus values may not be aliased to any other parameter. Outputs
+ * may not be aliased to one another. Temporaries may not be aliased to any
+ * other parameter.
+ * - **Overlap**: apart from aliasing of limb array pointers (where two
+ * arguments are equal pointers), overlap is not supported and may result
+ * in undefined behavior.
+ * - **Error handling**: This is a low-level module. Functions generally do not
+ * try to protect against invalid arguments such as nonsensical sizes or
+ * null pointers. Note that passing bignums with a different size than the
+ * modulus may lead to buffer overflows. Some functions which allocate
+ * memory or handle reading/writing of bignums will return an error if
+ * memory allocation fails or if buffer sizes are invalid.
+ * - **Modular representatives**: all functions expect inputs to be in the
+ * range [0, \c N - 1] and guarantee outputs in the range [0, \c N - 1]. If
+ * an input is out of range, outputs are fully unspecified, though bignum
+ * values out of range should not cause buffer overflows (beware that this is
+ * not extensively tested).
*/
/*