MBEDTLS_BIGNUM_MOD_H macro

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