third_party/mbedtls/repo/include/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 (C) 2006-2017, ARM Limited, All Rights Reserved
  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  *  This file is part of mbed TLS (https://tls.mbed.org)
  54  *
  55  */
  56
  57 #ifndef MBEDTLS_RSA_INTERNAL_H
  58 #define MBEDTLS_RSA_INTERNAL_H
  59
  60 #if !defined(MBEDTLS_CONFIG_FILE)
  61 #include "config.h"
  62 #else
  63 #include MBEDTLS_CONFIG_FILE
  64 #endif
  65
  66 #include "bignum.h"
  67
  68 #ifdef __cplusplus
  69 extern "C" {
  70 #endif
  71
  72
  73 /**
  74  * \brief          Compute RSA prime moduli P, Q from public modulus N=PQ
  75  *                 and a pair of private and public key.
  76  *
  77  * \note           This is a 'static' helper function not operating on
  78  *                 an RSA context. Alternative implementations need not
  79  *                 overwrite it.
  80  *
  81  * \param N        RSA modulus N = PQ, with P, Q to be found
  82  * \param E        RSA public exponent
  83  * \param D        RSA private exponent
  84  * \param P        Pointer to MPI holding first prime factor of N on success
  85  * \param Q        Pointer to MPI holding second prime factor of N on success
  86  *
  87  * \return
  88  *                 - 0 if successful. In this case, P and Q constitute a
  89  *                   factorization of N.
  90  *                 - A non-zero error code otherwise.
  91  *
  92  * \note           It is neither checked that P, Q are prime nor that
  93  *                 D, E are modular inverses wrt. P-1 and Q-1. For that,
  94  *                 use the helper function \c mbedtls_rsa_validate_params.
  95  *
  96  */
  97 int mbedtls_rsa_deduce_primes( mbedtls_mpi const *N, mbedtls_mpi const *E,
  98                                mbedtls_mpi const *D,
  99                                mbedtls_mpi *P, mbedtls_mpi *Q );
 100
 101 /**
 102  * \brief          Compute RSA private exponent from
 103  *                 prime moduli and public key.
 104  *
 105  * \note           This is a 'static' helper function not operating on
 106  *                 an RSA context. Alternative implementations need not
 107  *                 overwrite it.
 108  *
 109  * \param P        First prime factor of RSA modulus
 110  * \param Q        Second prime factor of RSA modulus
 111  * \param E        RSA public exponent
 112  * \param D        Pointer to MPI holding the private exponent on success.
 113  *
 114  * \return
 115  *                 - 0 if successful. In this case, D is set to a simultaneous
 116  *                   modular inverse of E modulo both P-1 and Q-1.
 117  *                 - A non-zero error code otherwise.
 118  *
 119  * \note           This function does not check whether P and Q are primes.
 120  *
 121  */
 122 int mbedtls_rsa_deduce_private_exponent( mbedtls_mpi const *P,
 123                                          mbedtls_mpi const *Q,
 124                                          mbedtls_mpi const *E,
 125                                          mbedtls_mpi *D );
 126
 127
 128 /**
 129  * \brief          Generate RSA-CRT parameters
 130  *
 131  * \note           This is a 'static' helper function not operating on
 132  *                 an RSA context. Alternative implementations need not
 133  *                 overwrite it.
 134  *
 135  * \param P        First prime factor of N
 136  * \param Q        Second prime factor of N
 137  * \param D        RSA private exponent
 138  * \param DP       Output variable for D modulo P-1
 139  * \param DQ       Output variable for D modulo Q-1
 140  * \param QP       Output variable for the modular inverse of Q modulo P.
 141  *
 142  * \return         0 on success, non-zero error code otherwise.
 143  *
 144  * \note           This function does not check whether P, Q are
 145  *                 prime and whether D is a valid private exponent.
 146  *
 147  */
 148 int mbedtls_rsa_deduce_crt( const mbedtls_mpi *P, const mbedtls_mpi *Q,
 149                             const mbedtls_mpi *D, mbedtls_mpi *DP,
 150                             mbedtls_mpi *DQ, mbedtls_mpi *QP );
 151
 152
 153 /**
 154  * \brief          Check validity of core RSA parameters
 155  *
 156  * \note           This is a 'static' helper function not operating on
 157  *                 an RSA context. Alternative implementations need not
 158  *                 overwrite it.
 159  *
 160  * \param N        RSA modulus N = PQ
 161  * \param P        First prime factor of N
 162  * \param Q        Second prime factor of N
 163  * \param D        RSA private exponent
 164  * \param E        RSA public exponent
 165  * \param f_rng    PRNG to be used for primality check, or NULL
 166  * \param p_rng    PRNG context for f_rng, or NULL
 167  *
 168  * \return
 169  *                 - 0 if the following conditions are satisfied
 170  *                   if all relevant parameters are provided:
 171  *                    - P prime if f_rng != NULL (%)
 172  *                    - Q prime if f_rng != NULL (%)
 173  *                    - 1 < N = P * Q
 174  *                    - 1 < D, E < N
 175  *                    - D and E are modular inverses modulo P-1 and Q-1
 176  *                   (%) This is only done if MBEDTLS_GENPRIME is defined.
 177  *                 - A non-zero error code otherwise.
 178  *
 179  * \note           The function can be used with a restricted set of arguments
 180  *                 to perform specific checks only. E.g., calling it with
 181  *                 (-,P,-,-,-) and a PRNG amounts to a primality check for P.
 182  */
 183 int mbedtls_rsa_validate_params( const mbedtls_mpi *N, const mbedtls_mpi *P,
 184                                  const mbedtls_mpi *Q, const mbedtls_mpi *D,
 185                                  const mbedtls_mpi *E,
 186                                  int (*f_rng)(void *, unsigned char *, size_t),
 187                                  void *p_rng );
 188
 189 /**
 190  * \brief          Check validity of RSA CRT parameters
 191  *
 192  * \note           This is a 'static' helper function not operating on
 193  *                 an RSA context. Alternative implementations need not
 194  *                 overwrite it.
 195  *
 196  * \param P        First prime factor of RSA modulus
 197  * \param Q        Second prime factor of RSA modulus
 198  * \param D        RSA private exponent
 199  * \param DP       MPI to check for D modulo P-1
 200  * \param DQ       MPI to check for D modulo P-1
 201  * \param QP       MPI to check for the modular inverse of Q modulo P.
 202  *
 203  * \return
 204  *                 - 0 if the following conditions are satisfied:
 205  *                    - D = DP mod P-1 if P, D, DP != NULL
 206  *                    - Q = DQ mod P-1 if P, D, DQ != NULL
 207  *                    - QP = Q^-1 mod P if P, Q, QP != NULL
 208  *                 - \c MBEDTLS_ERR_RSA_KEY_CHECK_FAILED if check failed,
 209  *                   potentially including \c MBEDTLS_ERR_MPI_XXX if some
 210  *                   MPI calculations failed.
 211  *                 - \c MBEDTLS_ERR_RSA_BAD_INPUT_DATA if insufficient
 212  *                   data was provided to check DP, DQ or QP.
 213  *
 214  * \note           The function can be used with a restricted set of arguments
 215  *                 to perform specific checks only. E.g., calling it with the
 216  *                 parameters (P, -, D, DP, -, -) will check DP = D mod P-1.
 217  */
 218 int mbedtls_rsa_validate_crt( const mbedtls_mpi *P,  const mbedtls_mpi *Q,
 219                               const mbedtls_mpi *D,  const mbedtls_mpi *DP,
 220                               const mbedtls_mpi *DQ, const mbedtls_mpi *QP );
 221
 222 #ifdef __cplusplus
 223 }
 224 #endif
 225
 226 #endif /* rsa_internal.h */