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