mbedtls/library/bignum_mod_raw.h

10  * has no protection against passing invalid arguments such as arrays of
13  * expense of code size and sometimes more cumbersome memory management.
18  *   of type #mbedtls_mpi_mod_modulus. The structure must be set up with an
19  *   array of limbs storing the bignum value of the modulus. The modulus must
22  * - **Bignum parameters**: Bignums are passed as pointers to an array of
27  *       The initial content of output-only parameters is ignored.
28  *     - \c T is a temporary storage area. The initial content of such a
31  *   member of the modulus argument. All bignum parameters must have the same
32  *   number of limbs as the modulus. All bignum sizes must be at least 1 and
35  * - **Bignum representation**: the representation of inputs and outputs is
36  *   specified by the \c int_rep field of the modulus for arithmetic
45  * - **Overlap**: apart from aliasing of limb array pointers (where two
52  *   memory or handle reading/writing of bignums will return an error if
56  *   an input is out of range, outputs are fully unspecified, though bignum
57  *   values out of range should not cause buffer overflows (beware that this is
78  * \brief   Perform a safe conditional copy of an MPI which doesn't reveal
83  * \param[out] X        The address of the destination MPI.
85  *                      store the full value of \p A.
86  * \param[in]  A        The address of the source MPI. This must be initialized.
87  * \param[in]  N        The address of the modulus related to \p X and \p A.
91  *                      * \c 0: Keep the original value of \p X.
96  * \warning        If \p assign is neither 0 nor 1, the result of this function
106  * \brief   Perform a safe conditional swap of two MPIs which doesn't reveal
111  * \param[in,out] X     The address of the first MPI. This must be initialized.
112  * \param[in,out] Y     The address of the second MPI. This must be initialized.
113  * \param[in]     N     The address of the modulus related to \p X and \p Y.
116  *                      * \c 1: Swap the values of \p X and \p Y.
117  *                      * \c 0: Keep the original values of \p X and \p Y.
122  * \warning        If \p swap is neither 0 nor 1, the result of this function
124  *                 values different to either of the original ones.
136  * \param[out] X        The address of the MPI. The size is determined by \p N.
139  * \param[in] N         The address of the modulus related to \p X.
141  * \param input_length  The length in bytes of \p input.
142  * \param ext_rep       The endianness of the number in the input buffer.
148  *               of \p N is invalid or \p X is not less than \p N.
158  * \param[in] A         The address of the MPI. The size is determined by \p N.
161  * \param[in] N         The address of the modulus related to \p A.
163  * \param output_length The length in bytes of \p output.
168  *               large enough to hold the value of \p A.
170  *               of \p N is invalid.
181  * The size of the operation is determined by \p N. \p A and \p B must have
182  * the same number of limbs as \p N.
187  * \param[out] X        The address of the result MPI.
189  *                      store the full value of the result.
190  * \param[in]  A        The address of the first MPI. This must be initialized.
191  * \param[in]  B        The address of the second MPI. This must be initialized.
192  * \param[in]  N        The address of the modulus. Used to perform a modulo
193  *                      operation on the result of the subtraction.
206  * The size of the operation is determined by \p N. \p A, \p B and \p X must
208  * of limbs as \p N.
214  * \param[out] X        The address of the result MPI. Must have the same
215  *                      number of limbs as \p N.
216  *                      On successful completion, \p X contains the result of
219  * \param[in]  A        The address of the first MPI.
220  * \param[in]  B        The address of the second MPI.
221  * \param[in]  N        The address of the modulus. Used to perform a modulo
222  *                      operation on the result of the multiplication.
223  * \param[in,out] T     Temporary storage of size at least 2 * N->limbs + 1
226  *                      It must not alias or otherwise overlap any of the
236  * \brief          Returns the number of limbs of working memory required for
243  * \param AN_limbs The number of limbs in the input `A` and the modulus `N`
247  * \return         The number of limbs of working memory required by
253  * \brief Perform fixed-width modular inversion of a Montgomery-form MPI with
258  * \param[out] X     The modular inverse of \p A with respect to \p N.
260  * \param[in] A      The number to calculate the modular inverse of.
262  * \param[in] N      The modulus, as a little-endian array of length \p AN_limbs.
264  * \param AN_limbs   The number of limbs in \p A, \p N and \p RR.
265  * \param[in] RR     The precomputed residue of 2^{2*biL} modulo N, as a little-
266  *                   endian array of length \p AN_limbs.
267  * \param[in,out] T  Temporary storage of at least the number of limbs returned
271  *                   It must not alias or otherwise overlap any of the other
289  * The number of limbs in each operand, and the result, is given by the
295  * \param[out] X    The result of the modular addition.
296  * \param[in] A     Little-endian presentation of the left operand. This
298  * \param[in] B     Little-endian presentation of the right operand. This
300  * \param[in] N     The address of the modulus.
313  *                  If this function returns an error, the content of \p X
330  *                  If this function returns an error, the content of \p X
347  * when the RNG is a suitably parametrized instance of HMAC_DRBG
358  *                 This is the upper bound of the output range, exclusive.
365  *                 of attempts. This has a negligible probability if \p N
377  * \param X      The address of the MPI.
378  *               Must have the same number of limbs as \p N.
379  * \param N      The address of the modulus, which gives the size of
389  * \param X      The address of the MPI.
390  *               Must have the same number of limbs as \p N.
391  * \param N      The address of the modulus, which gives the size of
401  * The size of the operation is determined by \p N. \p A must have
402  * the same number of limbs as \p N.
406  * \param[out] X        The result of the modular negation.
408  * \param[in] A         Little-endian presentation of the input operand. This