rsa_internal.h

00001 /**
00002  * \file rsa_internal.h
00003  *
00004  * \brief Context-independent RSA helper functions
00005  *
00006  *  This module declares some RSA-related helper functions useful when
00007  *  implementing the RSA interface. These functions are provided in a separate
00008  *  compilation unit in order to make it easy for designers of alternative RSA
00009  *  implementations to use them in their own code, as it is conceived that the
00010  *  functionality they provide will be necessary for most complete
00011  *  implementations.
00012  *
00013  *  End-users of Mbed TLS who are not providing their own alternative RSA
00014  *  implementations should not use these functions directly, and should instead
00015  *  use only the functions declared in rsa.h.
00016  *
00017  *  The interface provided by this module will be maintained through LTS (Long
00018  *  Term Support) branches of Mbed TLS, but may otherwise be subject to change,
00019  *  and must be considered an internal interface of the library.
00020  *
00021  *  There are two classes of helper functions:
00022  *
00023  *  (1) Parameter-generating helpers. These are:
00024  *      - mbedtls_rsa_deduce_primes
00025  *      - mbedtls_rsa_deduce_private_exponent
00026  *      - mbedtls_rsa_deduce_crt
00027  *       Each of these functions takes a set of core RSA parameters and
00028  *       generates some other, or CRT related parameters.
00029  *
00030  *  (2) Parameter-checking helpers. These are:
00031  *      - mbedtls_rsa_validate_params
00032  *      - mbedtls_rsa_validate_crt
00033  *      They take a set of core or CRT related RSA parameters and check their
00034  *      validity.
00035  *
00036  */
00037 /*
00038  *  Copyright (C) 2006-2017, ARM Limited, All Rights Reserved
00039  *  SPDX-License-Identifier: Apache-2.0
00040  *
00041  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00042  *  not use this file except in compliance with the License.
00043  *  You may obtain a copy of the License at
00044  *
00045  *  http://www.apache.org/licenses/LICENSE-2.0
00046  *
00047  *  Unless required by applicable law or agreed to in writing, software
00048  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00049  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00050  *  See the License for the specific language governing permissions and
00051  *  limitations under the License.
00052  *
00053  *  This file is part of mbed TLS (https://tls.mbed.org)
00054  *
00055  */
00056 
00057 #ifndef MBEDTLS_RSA_INTERNAL_H
00058 #define MBEDTLS_RSA_INTERNAL_H
00059 
00060 #if !defined(MBEDTLS_CONFIG_FILE)
00061 #include "mbedtls/config.h"
00062 #else
00063 #include MBEDTLS_CONFIG_FILE
00064 #endif
00065 
00066 #include "mbedtls/bignum.h"
00067 
00068 #ifdef __cplusplus
00069 extern "C" {
00070 #endif
00071 
00072 
00073 /**
00074  * \brief          Compute RSA prime moduli P, Q from public modulus N=PQ
00075  *                 and a pair of private and public key.
00076  *
00077  * \note           This is a 'static' helper function not operating on
00078  *                 an RSA context. Alternative implementations need not
00079  *                 overwrite it.
00080  *
00081  * \param N        RSA modulus N = PQ, with P, Q to be found
00082  * \param E        RSA public exponent
00083  * \param D        RSA private exponent
00084  * \param P        Pointer to MPI holding first prime factor of N on success
00085  * \param Q        Pointer to MPI holding second prime factor of N on success
00086  *
00087  * \return
00088  *                 - 0 if successful. In this case, P and Q constitute a
00089  *                   factorization of N.
00090  *                 - A non-zero error code otherwise.
00091  *
00092  * \note           It is neither checked that P, Q are prime nor that
00093  *                 D, E are modular inverses wrt. P-1 and Q-1. For that,
00094  *                 use the helper function \c mbedtls_rsa_validate_params.
00095  *
00096  */
00097 int mbedtls_rsa_deduce_primes( mbedtls_mpi const *N, mbedtls_mpi const *E,
00098                                mbedtls_mpi const *D,
00099                                mbedtls_mpi *P, mbedtls_mpi *Q );
00100 
00101 /**
00102  * \brief          Compute RSA private exponent from
00103  *                 prime moduli and public key.
00104  *
00105  * \note           This is a 'static' helper function not operating on
00106  *                 an RSA context. Alternative implementations need not
00107  *                 overwrite it.
00108  *
00109  * \param P        First prime factor of RSA modulus
00110  * \param Q        Second prime factor of RSA modulus
00111  * \param E        RSA public exponent
00112  * \param D        Pointer to MPI holding the private exponent on success.
00113  *
00114  * \return
00115  *                 - 0 if successful. In this case, D is set to a simultaneous
00116  *                   modular inverse of E modulo both P-1 and Q-1.
00117  *                 - A non-zero error code otherwise.
00118  *
00119  * \note           This function does not check whether P and Q are primes.
00120  *
00121  */
00122 int mbedtls_rsa_deduce_private_exponent( mbedtls_mpi const *P,
00123                                          mbedtls_mpi const *Q,
00124                                          mbedtls_mpi const *E,
00125                                          mbedtls_mpi *D );
00126 
00127 
00128 /**
00129  * \brief          Generate RSA-CRT parameters
00130  *
00131  * \note           This is a 'static' helper function not operating on
00132  *                 an RSA context. Alternative implementations need not
00133  *                 overwrite it.
00134  *
00135  * \param P        First prime factor of N
00136  * \param Q        Second prime factor of N
00137  * \param D        RSA private exponent
00138  * \param DP       Output variable for D modulo P-1
00139  * \param DQ       Output variable for D modulo Q-1
00140  * \param QP       Output variable for the modular inverse of Q modulo P.
00141  *
00142  * \return         0 on success, non-zero error code otherwise.
00143  *
00144  * \note           This function does not check whether P, Q are
00145  *                 prime and whether D is a valid private exponent.
00146  *
00147  */
00148 int mbedtls_rsa_deduce_crt( const mbedtls_mpi *P, const mbedtls_mpi *Q,
00149                             const mbedtls_mpi *D, mbedtls_mpi *DP,
00150                             mbedtls_mpi *DQ, mbedtls_mpi *QP );
00151 
00152 
00153 /**
00154  * \brief          Check validity of core RSA parameters
00155  *
00156  * \note           This is a 'static' helper function not operating on
00157  *                 an RSA context. Alternative implementations need not
00158  *                 overwrite it.
00159  *
00160  * \param N        RSA modulus N = PQ
00161  * \param P        First prime factor of N
00162  * \param Q        Second prime factor of N
00163  * \param D        RSA private exponent
00164  * \param E        RSA public exponent
00165  * \param f_rng    PRNG to be used for primality check, or NULL
00166  * \param p_rng    PRNG context for f_rng, or NULL
00167  *
00168  * \return
00169  *                 - 0 if the following conditions are satisfied
00170  *                   if all relevant parameters are provided:
00171  *                    - P prime if f_rng != NULL (%)
00172  *                    - Q prime if f_rng != NULL (%)
00173  *                    - 1 < N = P * Q
00174  *                    - 1 < D, E < N
00175  *                    - D and E are modular inverses modulo P-1 and Q-1
00176  *                   (%) This is only done if MBEDTLS_GENPRIME is defined.
00177  *                 - A non-zero error code otherwise.
00178  *
00179  * \note           The function can be used with a restricted set of arguments
00180  *                 to perform specific checks only. E.g., calling it with
00181  *                 (-,P,-,-,-) and a PRNG amounts to a primality check for P.
00182  */
00183 int mbedtls_rsa_validate_params( const mbedtls_mpi *N, const mbedtls_mpi *P,
00184                                  const mbedtls_mpi *Q, const mbedtls_mpi *D,
00185                                  const mbedtls_mpi *E,
00186                                  int (*f_rng)(void *, unsigned char *, size_t),
00187                                  void *p_rng );
00188 
00189 /**
00190  * \brief          Check validity of RSA CRT parameters
00191  *
00192  * \note           This is a 'static' helper function not operating on
00193  *                 an RSA context. Alternative implementations need not
00194  *                 overwrite it.
00195  *
00196  * \param P        First prime factor of RSA modulus
00197  * \param Q        Second prime factor of RSA modulus
00198  * \param D        RSA private exponent
00199  * \param DP       MPI to check for D modulo P-1
00200  * \param DQ       MPI to check for D modulo P-1
00201  * \param QP       MPI to check for the modular inverse of Q modulo P.
00202  *
00203  * \return
00204  *                 - 0 if the following conditions are satisfied:
00205  *                    - D = DP mod P-1 if P, D, DP != NULL
00206  *                    - Q = DQ mod P-1 if P, D, DQ != NULL
00207  *                    - QP = Q^-1 mod P if P, Q, QP != NULL
00208  *                 - \c MBEDTLS_ERR_RSA_KEY_CHECK_FAILED if check failed,
00209  *                   potentially including \c MBEDTLS_ERR_MPI_XXX if some
00210  *                   MPI calculations failed.
00211  *                 - \c MBEDTLS_ERR_RSA_BAD_INPUT_DATA if insufficient
00212  *                   data was provided to check DP, DQ or QP.
00213  *
00214  * \note           The function can be used with a restricted set of arguments
00215  *                 to perform specific checks only. E.g., calling it with the
00216  *                 parameters (P, -, D, DP, -, -) will check DP = D mod P-1.
00217  */
00218 int mbedtls_rsa_validate_crt( const mbedtls_mpi *P,  const mbedtls_mpi *Q,
00219                               const mbedtls_mpi *D,  const mbedtls_mpi *DP,
00220                               const mbedtls_mpi *DQ, const mbedtls_mpi *QP );
00221 
00222 #ifdef __cplusplus
00223 }
00224 #endif
00225 
00226 #endif /* rsa_internal.h */