eden-emu/mbedtls
20
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #6766 from wernerlewis/bignum_mod_docs

Browse source 
Bignum: document conventions for bignum mod and mod_raw
This commit is contained in:
Manuel Pégourié-Gonnard 2022-12-16 09:58:36 +01:00 • committed by GitHub
commit 057b458583
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 102 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

45
library/bignum_mod_raw.h
View file

@ -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).
*/
/*