git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/mbedtls/include/mbedtls/rsa_internal.h

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