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 */
|
---|