1 /** 2 * \file bignum_internal.h 3 * 4 * \brief Internal-only bignum public-key cryptosystem API. 5 * 6 * This file declares bignum-related functions that are to be used 7 * only from within the Mbed TLS library itself. 8 * 9 */ 10 /* 11 * Copyright The Mbed TLS Contributors 12 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 13 */ 14 #ifndef MBEDTLS_BIGNUM_INTERNAL_H 15 #define MBEDTLS_BIGNUM_INTERNAL_H 16 17 /** 18 * \brief Perform a modular exponentiation: X = A^E mod N 19 * 20 * \warning This function is not constant time with respect to \p E (the exponent). 21 * 22 * \param X The destination MPI. This must point to an initialized MPI. 23 * This must not alias E or N. 24 * \param A The base of the exponentiation. 25 * This must point to an initialized MPI. 26 * \param E The exponent MPI. This must point to an initialized MPI. 27 * \param N The base for the modular reduction. This must point to an 28 * initialized MPI. 29 * \param prec_RR A helper MPI depending solely on \p N which can be used to 30 * speed-up multiple modular exponentiations for the same value 31 * of \p N. This may be \c NULL. If it is not \c NULL, it must 32 * point to an initialized MPI. If it hasn't been used after 33 * the call to mbedtls_mpi_init(), this function will compute 34 * the helper value and store it in \p prec_RR for reuse on 35 * subsequent calls to this function. Otherwise, the function 36 * will assume that \p prec_RR holds the helper value set by a 37 * previous call to mbedtls_mpi_exp_mod(), and reuse it. 38 * 39 * \return \c 0 if successful. 40 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. 41 * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \c N is negative or 42 * even, or if \c E is negative. 43 * \return Another negative error code on different kinds of failures. 44 * 45 */ 46 int mbedtls_mpi_exp_mod_unsafe(mbedtls_mpi *X, const mbedtls_mpi *A, 47 const mbedtls_mpi *E, const mbedtls_mpi *N, 48 mbedtls_mpi *prec_RR); 49 50 /** 51 * \brief A wrapper around a constant time function to compute 52 * GCD(A, N) and/or A^-1 mod N if it exists. 53 * 54 * \warning Requires N to be odd, and 0 <= A <= N. Additionally, if 55 * I != NULL, requires N > 1. 56 * The wrapper part of this function is not constant time. 57 * 58 * \note A and N must not alias each other. 59 * When I == NULL (computing only the GCD), G can alias A or N. 60 * When I != NULL (computing the modular inverse), G or I can 61 * alias A, but neither of them can alias N (the modulus). 62 * 63 * \param[out] G The GCD of \p A and \p N. 64 * This may be NULL, to only compute I. 65 * \param[out] I The inverse of \p A modulo \p N if it exists (that is, 66 * if \p G above is 1 on exit), in the range [1, \p N); 67 * indeterminate otherwise. 68 * This may be NULL, to only compute G. 69 * \param[in] A The 1st operand of GCD and number to invert. 70 * This value must be less than or equal to \p N. 71 * \param[in] N The 2nd operand of GCD and modulus for inversion. 72 * Must be odd or the results are indeterminate. 73 * 74 * \return \c 0 if successful. 75 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. 76 * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if preconditions were not 77 * met. 78 */ 79 int mbedtls_mpi_gcd_modinv_odd(mbedtls_mpi *G, 80 mbedtls_mpi *I, 81 const mbedtls_mpi *A, 82 const mbedtls_mpi *N); 83 84 /** 85 * \brief Modular inverse: X = A^-1 mod N with N odd 86 * 87 * \param[out] X The inverse of \p A modulo \p N in the range [1, \p N) 88 * on success; indeterminate otherwise. 89 * \param[in] A The number to invert. 90 * \param[in] N The modulus. Must be odd and greater than 1. 91 * 92 * \return \c 0 if successful. 93 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. 94 * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if preconditions were not 95 * met. 96 * \return #MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if A is not invertible mod N. 97 */ 98 int mbedtls_mpi_inv_mod_odd(mbedtls_mpi *X, 99 const mbedtls_mpi *A, 100 const mbedtls_mpi *N); 101 102 /** 103 * \brief Modular inverse: X = A^-1 mod N with N even, 104 * A odd and 1 < A < N. 105 * 106 * \param[out] X The inverse of \p A modulo \p N in the range [1, \p N) 107 * on success; indeterminate otherwise. 108 * \param[in] A The number to invert. Must be odd, greated than 1 109 * and less than \p N. 110 * \param[in] N The modulus. Must be even and greater than 1. 111 * 112 * \return \c 0 if successful. 113 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. 114 * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if preconditions were not 115 * met. 116 * \return #MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if A is not invertible mod N. 117 */ 118 int mbedtls_mpi_inv_mod_even_in_range(mbedtls_mpi *X, 119 mbedtls_mpi const *A, 120 mbedtls_mpi const *N); 121 122 #endif /* bignum_internal.h */ 123