mbedtls/library/bignum_mod.h

10  *   of type #mbedtls_mpi_mod_modulus. The structure must be set up with an
11  *   array of limbs storing the bignum value of the modulus. The modulus must
14  *   of type \c const #mbedtls_mpi_mod_modulus* must not modify its value.
15  * - **Bignum parameters**: Bignums are passed as pointers to an array of
20  *       modified by the function. Functions which take a parameter of
23  *       The initial bignum value of output-only parameters is ignored, but
28  *       residue. These must be pointers to an array of limbs.
29  *     - \c T is a temporary storage area. The initial content of such a
35  *   number of limbs as the modulus. All bignum sizes must be at least 1 and
38  * - **Bignum representation**: the representation of inputs and outputs is
39  *   specified by the \c int_rep field of the modulus.
46  * - **Overlap**: apart from aliasing of residue pointers (where two residue
49  * - **Error handling**: functions generally check compatibility of input
51  *   form (i.e. that \c A < \c N), this is only checked during setup of a
58  *   is associated with, then it may be out of range. If an input is out of
59  *   range, outputs are fully unspecified, though bignum values out of range
80  * This also determines which fields of the modulus structure are valid and
90      * and one or more of the following have been configured:
123     size_t limbs;                            // number of limbs
124     size_t bits;                             // bitlen of p
125     mbedtls_mpi_mod_rep_selector int_rep;    // selector to signal the active member of the union
139  * The value at the pointed-to memory will be the initial value of \p r and must
141  * and interpreted according to the value of the `N->int_rep` field.
146  * \param[out] r    The address of the residue to setup.
147  * \param[in] N     The address of the modulus related to \p r.
148  * \param[in] p     The address of the limb array containing the value of \p r.
155  * \param p_limbs   The number of limbs of \p p. Must be the same as the number
156  *                  of limbs in the modulus \p N.
167 /** Unbind elements of a residue structure.
175  * \param[out] r     The address of residue to release.
181  * \param[out] N     The address of the modulus structure to initialize.
187  * \param[out] N    The address of the modulus structure to populate.
188  * \param[in] p     The address of the limb array storing the value of \p N.
192  * \param p_limbs   The number of limbs of \p p.
202  * \param[out] N    The address of the modulus structure to populate.
203  * \param[in] p     The address of the limb array storing the value of \p N.
207  * \param p_limbs   The number of limbs of \p p.
217 /** Free elements of a modulus structure.
225  * \param[in,out] N     The address of the modulus structure to free.
235  * The size of the operation is determined by \p N. \p A, \p B and \p X must
237  * of limbs as \p N.
243  * \param[out] X        The address of the result MPI. Must have the same
244  *                      number of limbs as \p N.
245  *                      On successful completion, \p X contains the result of
248  * \param[in]  A        The address of the first MPI.
249  * \param[in]  B        The address of the second MPI.
250  * \param[in]  N        The address of the modulus. Used to perform a modulo
251  *                      operation on the result of the multiplication.
255  *              have the same number of limbs or \p N is invalid.
268  * \p A, \p B and \p X must all have the same number of limbs as \p N.
277  * \param[out] X    The address of the result MPI. Must be initialized.
278  *                  Must have the same number of limbs as the modulus \p N.
279  * \param[in]  A    The address of the first MPI.
280  * \param[in]  B    The address of the second MPI.
281  * \param[in]  N    The address of the modulus. Used to perform a modulo
282  *                  operation on the result of the subtraction.
286  *                  have the correct number of limbs.
294  * \brief Perform modular inversion of an MPI with respect to a modulus \p N.
297  * have the same number of limbs as \p N.
303  * \param[out] X   The modular inverse of \p A with respect to \p N.
304  * \param[in] A    The number to calculate the modular inverse of.
310  *                 have the same number of limbs.
327  * all have the same number of limbs as \p N.
336  * \param[out] X    The address of the result residue. Must be initialized.
337  *                  Must have the same number of limbs as the modulus \p N.
338  * \param[in]  A    The address of the first input residue.
339  * \param[in]  B    The address of the second input residue.
340  * \param[in]  N    The address of the modulus. Used to perform a modulo
341  *                  operation on the result of the addition.
345  *                  have the correct number of limbs.
358  * when the RNG is a suitably parametrized instance of HMAC_DRBG
368  *                 This is the upper bound of the output range, exclusive.
375  *                 of attempts. This has a negligible probability if \p N
388  * based on the value of the `N->int_rep` field.
395  * \param[out] r    The address of the residue. It must have exactly the same
396  *                  number of limbs as the modulus \p N.
397  * \param[in] N     The address of the modulus.
399  * \param buflen    The length in bytes of \p buf.
400  * \param ext_rep   The endianness of the number in the input buffer.
420  * based on the value of `N->int_rep` field.
422  * \warning     If the buffer is smaller than `N->bits`, the number of
427  * \param[in] r     The address of the residue. It must have the same number of
431  * \param[in] N     The address of the modulus associated with \p r.
433  * \param buflen    The length in bytes of \p buf.
439  *               large enough to hold the value of \p r (without leading