common/mbedtls/rsa_internal.h

   1 /**
   2  * \file rsa_internal.h
   3  *
   4  * \brief Context-independent RSA helper functions
   5  *
   6  *  This module declares some RSA-related helper functions useful when
   7  *  implementing the RSA interface. These functions are provided in a separate
   8  *  compilation unit in order to make it easy for designers of alternative RSA
   9  *  implementations to use them in their own code, as it is conceived that the
  10  *  functionality they provide will be necessary for most complete
  11  *  implementations.
  12  *
  13  *  End-users of Mbed TLS who are not providing their own alternative RSA
  14  *  implementations should not use these functions directly, and should instead
  15  *  use only the functions declared in rsa.h.
  16  *
  17  *  The interface provided by this module will be maintained through LTS (Long
  18  *  Term Support) branches of Mbed TLS, but may otherwise be subject to change,
  19  *  and must be considered an internal interface of the library.
  20  *
  21  *  There are two classes of helper functions:
  22  *
  23  *  (1) Parameter-generating helpers. These are:
  24  *      - mbedtls_rsa_deduce_primes
  25  *      - mbedtls_rsa_deduce_private_exponent
  26  *      - mbedtls_rsa_deduce_crt
  27  *       Each of these functions takes a set of core RSA parameters and
  28  *       generates some other, or CRT related parameters.
  29  *
  30  *  (2) Parameter-checking helpers. These are:
  31  *      - mbedtls_rsa_validate_params
  32  *      - mbedtls_rsa_validate_crt
  33  *      They take a set of core or CRT related RSA parameters and check their
  34  *      validity.
  35  *
  36  */
  37 /*
  38  *  Copyright The Mbed TLS Contributors
  39  *  SPDX-License-Identifier: Apache-2.0
  40  *
  41  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
  42  *  not use this file except in compliance with the License.
  43  *  You may obtain a copy of the License at
  44  *
  45  *  http://www.apache.org/licenses/LICENSE-2.0
  46  *
  47  *  Unless required by applicable law or agreed to in writing, software
  48  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  49  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  50  *  See the License for the specific language governing permissions and
  51  *  limitations under the License.
  52  *
  53  */
  54
  55 #ifndef MBEDTLS_RSA_INTERNAL_H
  56 #define MBEDTLS_RSA_INTERNAL_H
  57
  58 #if !defined(MBEDTLS_CONFIG_FILE)
  59 #include "mbedtls/config.h"
  60 #else
  61 #include MBEDTLS_CONFIG_FILE
  62 #endif
  63
  64 #include "mbedtls/bignum.h"
  65
  66 #ifdef __cplusplus
  67 extern "C" {
  68 #endif
  69
  70
  71 /**
  72  * \brief          Compute RSA prime moduli P, Q from public modulus N=PQ
  73  *                 and a pair of private and public key.
  74  *
  75  * \note           This is a 'static' helper function not operating on
  76  *                 an RSA context. Alternative implementations need not
  77  *                 overwrite it.
  78  *
  79  * \param N        RSA modulus N = PQ, with P, Q to be found
  80  * \param E        RSA public exponent
  81  * \param D        RSA private exponent
  82  * \param P        Pointer to MPI holding first prime factor of N on success
  83  * \param Q        Pointer to MPI holding second prime factor of N on success
  84  *
  85  * \return
  86  *                 - 0 if successful. In this case, P and Q constitute a
  87  *                   factorization of N.
  88  *                 - A non-zero error code otherwise.
  89  *
  90  * \note           It is neither checked that P, Q are prime nor that
  91  *                 D, E are modular inverses wrt. P-1 and Q-1. For that,
  92  *                 use the helper function \c mbedtls_rsa_validate_params.
  93  *
  94  */
  95 int mbedtls_rsa_deduce_primes(mbedtls_mpi const *N, mbedtls_mpi const *E,
  96                               mbedtls_mpi const *D,
  97                               mbedtls_mpi *P, mbedtls_mpi *Q);
  98
  99 /**
 100  * \brief          Compute RSA private exponent from
 101  *                 prime moduli and public key.
 102  *
 103  * \note           This is a 'static' helper function not operating on
 104  *                 an RSA context. Alternative implementations need not
 105  *                 overwrite it.
 106  *
 107  * \param P        First prime factor of RSA modulus
 108  * \param Q        Second prime factor of RSA modulus
 109  * \param E        RSA public exponent
 110  * \param D        Pointer to MPI holding the private exponent on success.
 111  *
 112  * \return
 113  *                 - 0 if successful. In this case, D is set to a simultaneous
 114  *                   modular inverse of E modulo both P-1 and Q-1.
 115  *                 - A non-zero error code otherwise.
 116  *
 117  * \note           This function does not check whether P and Q are primes.
 118  *
 119  */
 120 int mbedtls_rsa_deduce_private_exponent(mbedtls_mpi const *P,
 121                                         mbedtls_mpi const *Q,
 122                                         mbedtls_mpi const *E,
 123                                         mbedtls_mpi *D);
 124
 125
 126 /**
 127  * \brief          Generate RSA-CRT parameters
 128  *
 129  * \note           This is a 'static' helper function not operating on
 130  *                 an RSA context. Alternative implementations need not
 131  *                 overwrite it.
 132  *
 133  * \param P        First prime factor of N
 134  * \param Q        Second prime factor of N
 135  * \param D        RSA private exponent
 136  * \param DP       Output variable for D modulo P-1
 137  * \param DQ       Output variable for D modulo Q-1
 138  * \param QP       Output variable for the modular inverse of Q modulo P.
 139  *
 140  * \return         0 on success, non-zero error code otherwise.
 141  *
 142  * \note           This function does not check whether P, Q are
 143  *                 prime and whether D is a valid private exponent.
 144  *
 145  */
 146 int mbedtls_rsa_deduce_crt(const mbedtls_mpi *P, const mbedtls_mpi *Q,
 147                            const mbedtls_mpi *D, mbedtls_mpi *DP,
 148                            mbedtls_mpi *DQ, mbedtls_mpi *QP);
 149
 150
 151 /**
 152  * \brief          Check validity of core RSA parameters
 153  *
 154  * \note           This is a 'static' helper function not operating on
 155  *                 an RSA context. Alternative implementations need not
 156  *                 overwrite it.
 157  *
 158  * \param N        RSA modulus N = PQ
 159  * \param P        First prime factor of N
 160  * \param Q        Second prime factor of N
 161  * \param D        RSA private exponent
 162  * \param E        RSA public exponent
 163  * \param f_rng    PRNG to be used for primality check, or NULL
 164  * \param p_rng    PRNG context for f_rng, or NULL
 165  *
 166  * \return
 167  *                 - 0 if the following conditions are satisfied
 168  *                   if all relevant parameters are provided:
 169  *                    - P prime if f_rng != NULL (%)
 170  *                    - Q prime if f_rng != NULL (%)
 171  *                    - 1 < N = P * Q
 172  *                    - 1 < D, E < N
 173  *                    - D and E are modular inverses modulo P-1 and Q-1
 174  *                   (%) This is only done if MBEDTLS_GENPRIME is defined.
 175  *                 - A non-zero error code otherwise.
 176  *
 177  * \note           The function can be used with a restricted set of arguments
 178  *                 to perform specific checks only. E.g., calling it with
 179  *                 (-,P,-,-,-) and a PRNG amounts to a primality check for P.
 180  */
 181 int mbedtls_rsa_validate_params(const mbedtls_mpi *N, const mbedtls_mpi *P,
 182                                 const mbedtls_mpi *Q, const mbedtls_mpi *D,
 183                                 const mbedtls_mpi *E,
 184                                 int (*f_rng)(void *, unsigned char *, size_t),
 185                                 void *p_rng);
 186
 187 /**
 188  * \brief          Check validity of RSA CRT parameters
 189  *
 190  * \note           This is a 'static' helper function not operating on
 191  *                 an RSA context. Alternative implementations need not
 192  *                 overwrite it.
 193  *
 194  * \param P        First prime factor of RSA modulus
 195  * \param Q        Second prime factor of RSA modulus
 196  * \param D        RSA private exponent
 197  * \param DP       MPI to check for D modulo P-1
 198  * \param DQ       MPI to check for D modulo P-1
 199  * \param QP       MPI to check for the modular inverse of Q modulo P.
 200  *
 201  * \return
 202  *                 - 0 if the following conditions are satisfied:
 203  *                    - D = DP mod P-1 if P, D, DP != NULL
 204  *                    - Q = DQ mod P-1 if P, D, DQ != NULL
 205  *                    - QP = Q^-1 mod P if P, Q, QP != NULL
 206  *                 - \c MBEDTLS_ERR_RSA_KEY_CHECK_FAILED if check failed,
 207  *                   potentially including \c MBEDTLS_ERR_MPI_XXX if some
 208  *                   MPI calculations failed.
 209  *                 - \c MBEDTLS_ERR_RSA_BAD_INPUT_DATA if insufficient
 210  *                   data was provided to check DP, DQ or QP.
 211  *
 212  * \note           The function can be used with a restricted set of arguments
 213  *                 to perform specific checks only. E.g., calling it with the
 214  *                 parameters (P, -, D, DP, -, -) will check DP = D mod P-1.
 215  */
 216 int mbedtls_rsa_validate_crt(const mbedtls_mpi *P,  const mbedtls_mpi *Q,
 217                              const mbedtls_mpi *D,  const mbedtls_mpi *DP,
 218                              const mbedtls_mpi *DQ, const mbedtls_mpi *QP);
 219
 220 #ifdef __cplusplus
 221 }
 222 #endif
 223
 224 #endif /* rsa_internal.h */