rsa_internal.h

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