]>
Commit | Line | Data |
---|---|---|
700d8687 OM |
1 | /** |
2 | * \file rsa.h | |
3 | * | |
4 | * \brief This file provides an API for the RSA public-key cryptosystem. | |
5 | * | |
6 | * The RSA public-key cryptosystem is defined in <em>Public-Key | |
7 | * Cryptography Standards (PKCS) #1 v1.5: RSA Encryption</em> | |
8 | * and <em>Public-Key Cryptography Standards (PKCS) #1 v2.1: | |
9 | * RSA Cryptography Specifications</em>. | |
10 | * | |
11 | */ | |
12 | /* | |
13 | * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved | |
14 | * SPDX-License-Identifier: GPL-2.0 | |
15 | * | |
16 | * This program is free software; you can redistribute it and/or modify | |
17 | * it under the terms of the GNU General Public License as published by | |
18 | * the Free Software Foundation; either version 2 of the License, or | |
19 | * (at your option) any later version. | |
20 | * | |
21 | * This program is distributed in the hope that it will be useful, | |
22 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
23 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
24 | * GNU General Public License for more details. | |
25 | * | |
26 | * You should have received a copy of the GNU General Public License along | |
27 | * with this program; if not, write to the Free Software Foundation, Inc., | |
28 | * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. | |
29 | * | |
30 | * This file is part of Mbed TLS (https://tls.mbed.org) | |
31 | */ | |
32 | #ifndef MBEDTLS_RSA_H | |
33 | #define MBEDTLS_RSA_H | |
34 | ||
35 | #if !defined(MBEDTLS_CONFIG_FILE) | |
36 | #include "config.h" | |
37 | #else | |
38 | #include MBEDTLS_CONFIG_FILE | |
39 | #endif | |
40 | ||
41 | #include "bignum.h" | |
42 | #include "md.h" | |
43 | ||
44 | #if defined(MBEDTLS_THREADING_C) | |
45 | #include "threading.h" | |
46 | #endif | |
47 | ||
48 | /* | |
49 | * RSA Error codes | |
50 | */ | |
51 | #define MBEDTLS_ERR_RSA_BAD_INPUT_DATA -0x4080 /**< Bad input parameters to function. */ | |
52 | #define MBEDTLS_ERR_RSA_INVALID_PADDING -0x4100 /**< Input data contains invalid padding and is rejected. */ | |
53 | #define MBEDTLS_ERR_RSA_KEY_GEN_FAILED -0x4180 /**< Something failed during generation of a key. */ | |
54 | #define MBEDTLS_ERR_RSA_KEY_CHECK_FAILED -0x4200 /**< Key failed to pass the validity check of the library. */ | |
55 | #define MBEDTLS_ERR_RSA_PUBLIC_FAILED -0x4280 /**< The public key operation failed. */ | |
56 | #define MBEDTLS_ERR_RSA_PRIVATE_FAILED -0x4300 /**< The private key operation failed. */ | |
57 | #define MBEDTLS_ERR_RSA_VERIFY_FAILED -0x4380 /**< The PKCS#1 verification failed. */ | |
58 | #define MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE -0x4400 /**< The output buffer for decryption is not large enough. */ | |
59 | #define MBEDTLS_ERR_RSA_RNG_FAILED -0x4480 /**< The random generator failed to generate non-zeros. */ | |
60 | #define MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION -0x4500 /**< The implementation does not offer the requested operation, for example, because of security violations or lack of functionality. */ | |
61 | #define MBEDTLS_ERR_RSA_HW_ACCEL_FAILED -0x4580 /**< RSA hardware accelerator failed. */ | |
62 | ||
63 | /* | |
64 | * RSA constants | |
65 | */ | |
66 | #define MBEDTLS_RSA_PUBLIC 0 /**< Request private key operation. */ | |
67 | #define MBEDTLS_RSA_PRIVATE 1 /**< Request public key operation. */ | |
68 | ||
69 | #define MBEDTLS_RSA_PKCS_V15 0 /**< Use PKCS#1 v1.5 encoding. */ | |
70 | #define MBEDTLS_RSA_PKCS_V21 1 /**< Use PKCS#1 v2.1 encoding. */ | |
71 | ||
72 | #define MBEDTLS_RSA_SIGN 1 /**< Identifier for RSA signature operations. */ | |
73 | #define MBEDTLS_RSA_CRYPT 2 /**< Identifier for RSA encryption and decryption operations. */ | |
74 | ||
75 | #define MBEDTLS_RSA_SALT_LEN_ANY -1 | |
76 | ||
77 | /* | |
78 | * The above constants may be used even if the RSA module is compile out, | |
79 | * eg for alternative (PKCS#11) RSA implemenations in the PK layers. | |
80 | */ | |
81 | ||
82 | #ifdef __cplusplus | |
83 | extern "C" { | |
84 | #endif | |
85 | ||
86 | #if !defined(MBEDTLS_RSA_ALT) | |
87 | // Regular implementation | |
88 | // | |
89 | ||
90 | /** | |
91 | * \brief The RSA context structure. | |
92 | * | |
93 | * \note Direct manipulation of the members of this structure | |
94 | * is deprecated. All manipulation should instead be done through | |
95 | * the public interface functions. | |
96 | */ | |
97 | typedef struct mbedtls_rsa_context | |
98 | { | |
99 | int ver; /*!< Always 0.*/ | |
100 | size_t len; /*!< The size of \p N in Bytes. */ | |
101 | ||
102 | mbedtls_mpi N; /*!< The public modulus. */ | |
103 | mbedtls_mpi E; /*!< The public exponent. */ | |
104 | ||
105 | mbedtls_mpi D; /*!< The private exponent. */ | |
106 | mbedtls_mpi P; /*!< The first prime factor. */ | |
107 | mbedtls_mpi Q; /*!< The second prime factor. */ | |
108 | ||
109 | mbedtls_mpi DP; /*!< <code>D % (P - 1)</code>. */ | |
110 | mbedtls_mpi DQ; /*!< <code>D % (Q - 1)</code>. */ | |
111 | mbedtls_mpi QP; /*!< <code>1 / (Q % P)</code>. */ | |
112 | ||
113 | mbedtls_mpi RN; /*!< cached <code>R^2 mod N</code>. */ | |
114 | ||
115 | mbedtls_mpi RP; /*!< cached <code>R^2 mod P</code>. */ | |
116 | mbedtls_mpi RQ; /*!< cached <code>R^2 mod Q</code>. */ | |
117 | ||
118 | mbedtls_mpi Vi; /*!< The cached blinding value. */ | |
119 | mbedtls_mpi Vf; /*!< The cached un-blinding value. */ | |
120 | ||
121 | int padding; /*!< Selects padding mode: | |
122 | #MBEDTLS_RSA_PKCS_V15 for 1.5 padding and | |
123 | #MBEDTLS_RSA_PKCS_V21 for OAEP or PSS. */ | |
124 | int hash_id; /*!< Hash identifier of mbedtls_md_type_t type, | |
125 | as specified in md.h for use in the MGF | |
126 | mask generating function used in the | |
127 | EME-OAEP and EMSA-PSS encodings. */ | |
128 | #if defined(MBEDTLS_THREADING_C) | |
129 | mbedtls_threading_mutex_t mutex; /*!< Thread-safety mutex. */ | |
130 | #endif | |
131 | } | |
132 | mbedtls_rsa_context; | |
133 | ||
134 | #else /* MBEDTLS_RSA_ALT */ | |
135 | #include "rsa_alt.h" | |
136 | #endif /* MBEDTLS_RSA_ALT */ | |
137 | ||
138 | /** | |
139 | * \brief This function initializes an RSA context. | |
140 | * | |
141 | * \note Set padding to #MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP | |
142 | * encryption scheme and the RSASSA-PSS signature scheme. | |
143 | * | |
144 | * \note The \p hash_id parameter is ignored when using | |
145 | * #MBEDTLS_RSA_PKCS_V15 padding. | |
146 | * | |
147 | * \note The choice of padding mode is strictly enforced for private key | |
148 | * operations, since there might be security concerns in | |
149 | * mixing padding modes. For public key operations it is | |
150 | * a default value, which can be overriden by calling specific | |
151 | * \c rsa_rsaes_xxx or \c rsa_rsassa_xxx functions. | |
152 | * | |
153 | * \note The hash selected in \p hash_id is always used for OEAP | |
154 | * encryption. For PSS signatures, it is always used for | |
155 | * making signatures, but can be overriden for verifying them. | |
156 | * If set to #MBEDTLS_MD_NONE, it is always overriden. | |
157 | * | |
158 | * \param ctx The RSA context to initialize. | |
159 | * \param padding Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or | |
160 | * #MBEDTLS_RSA_PKCS_V21. | |
161 | * \param hash_id The hash identifier of #mbedtls_md_type_t type, if | |
162 | * \p padding is #MBEDTLS_RSA_PKCS_V21. | |
163 | */ | |
164 | void mbedtls_rsa_init( mbedtls_rsa_context *ctx, | |
165 | int padding, | |
166 | int hash_id); | |
167 | ||
168 | /** | |
169 | * \brief This function imports a set of core parameters into an | |
170 | * RSA context. | |
171 | * | |
172 | * \note This function can be called multiple times for successive | |
173 | * imports, if the parameters are not simultaneously present. | |
174 | * | |
175 | * Any sequence of calls to this function should be followed | |
176 | * by a call to mbedtls_rsa_complete(), which checks and | |
177 | * completes the provided information to a ready-for-use | |
178 | * public or private RSA key. | |
179 | * | |
180 | * \note See mbedtls_rsa_complete() for more information on which | |
181 | * parameters are necessary to set up a private or public | |
182 | * RSA key. | |
183 | * | |
184 | * \note The imported parameters are copied and need not be preserved | |
185 | * for the lifetime of the RSA context being set up. | |
186 | * | |
187 | * \param ctx The initialized RSA context to store the parameters in. | |
188 | * \param N The RSA modulus, or NULL. | |
189 | * \param P The first prime factor of \p N, or NULL. | |
190 | * \param Q The second prime factor of \p N, or NULL. | |
191 | * \param D The private exponent, or NULL. | |
192 | * \param E The public exponent, or NULL. | |
193 | * | |
194 | * \return \c 0 on success. | |
195 | * \return A non-zero error code on failure. | |
196 | */ | |
197 | int mbedtls_rsa_import( mbedtls_rsa_context *ctx, | |
198 | const mbedtls_mpi *N, | |
199 | const mbedtls_mpi *P, const mbedtls_mpi *Q, | |
200 | const mbedtls_mpi *D, const mbedtls_mpi *E ); | |
201 | ||
202 | /** | |
203 | * \brief This function imports core RSA parameters, in raw big-endian | |
204 | * binary format, into an RSA context. | |
205 | * | |
206 | * \note This function can be called multiple times for successive | |
207 | * imports, if the parameters are not simultaneously present. | |
208 | * | |
209 | * Any sequence of calls to this function should be followed | |
210 | * by a call to mbedtls_rsa_complete(), which checks and | |
211 | * completes the provided information to a ready-for-use | |
212 | * public or private RSA key. | |
213 | * | |
214 | * \note See mbedtls_rsa_complete() for more information on which | |
215 | * parameters are necessary to set up a private or public | |
216 | * RSA key. | |
217 | * | |
218 | * \note The imported parameters are copied and need not be preserved | |
219 | * for the lifetime of the RSA context being set up. | |
220 | * | |
221 | * \param ctx The initialized RSA context to store the parameters in. | |
222 | * \param N The RSA modulus, or NULL. | |
223 | * \param N_len The Byte length of \p N, ignored if \p N == NULL. | |
224 | * \param P The first prime factor of \p N, or NULL. | |
225 | * \param P_len The Byte length of \p P, ignored if \p P == NULL. | |
226 | * \param Q The second prime factor of \p N, or NULL. | |
227 | * \param Q_len The Byte length of \p Q, ignored if \p Q == NULL. | |
228 | * \param D The private exponent, or NULL. | |
229 | * \param D_len The Byte length of \p D, ignored if \p D == NULL. | |
230 | * \param E The public exponent, or NULL. | |
231 | * \param E_len The Byte length of \p E, ignored if \p E == NULL. | |
232 | * | |
233 | * \return \c 0 on success. | |
234 | * \return A non-zero error code on failure. | |
235 | */ | |
236 | int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx, | |
237 | unsigned char const *N, size_t N_len, | |
238 | unsigned char const *P, size_t P_len, | |
239 | unsigned char const *Q, size_t Q_len, | |
240 | unsigned char const *D, size_t D_len, | |
241 | unsigned char const *E, size_t E_len ); | |
242 | ||
243 | /** | |
244 | * \brief This function completes an RSA context from | |
245 | * a set of imported core parameters. | |
246 | * | |
247 | * To setup an RSA public key, precisely \p N and \p E | |
248 | * must have been imported. | |
249 | * | |
250 | * To setup an RSA private key, sufficient information must | |
251 | * be present for the other parameters to be derivable. | |
252 | * | |
253 | * The default implementation supports the following: | |
254 | * <ul><li>Derive \p P, \p Q from \p N, \p D, \p E.</li> | |
255 | * <li>Derive \p N, \p D from \p P, \p Q, \p E.</li></ul> | |
256 | * Alternative implementations need not support these. | |
257 | * | |
258 | * If this function runs successfully, it guarantees that | |
259 | * the RSA context can be used for RSA operations without | |
260 | * the risk of failure or crash. | |
261 | * | |
262 | * \warning This function need not perform consistency checks | |
263 | * for the imported parameters. In particular, parameters that | |
264 | * are not needed by the implementation might be silently | |
265 | * discarded and left unchecked. To check the consistency | |
266 | * of the key material, see mbedtls_rsa_check_privkey(). | |
267 | * | |
268 | * \param ctx The initialized RSA context holding imported parameters. | |
269 | * | |
270 | * \return \c 0 on success. | |
271 | * \return #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted derivations | |
272 | * failed. | |
273 | * | |
274 | */ | |
275 | int mbedtls_rsa_complete( mbedtls_rsa_context *ctx ); | |
276 | ||
277 | /** | |
278 | * \brief This function exports the core parameters of an RSA key. | |
279 | * | |
280 | * If this function runs successfully, the non-NULL buffers | |
281 | * pointed to by \p N, \p P, \p Q, \p D, and \p E are fully | |
282 | * written, with additional unused space filled leading by | |
283 | * zero Bytes. | |
284 | * | |
285 | * Possible reasons for returning | |
286 | * #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION:<ul> | |
287 | * <li>An alternative RSA implementation is in use, which | |
288 | * stores the key externally, and either cannot or should | |
289 | * not export it into RAM.</li> | |
290 | * <li>A SW or HW implementation might not support a certain | |
291 | * deduction. For example, \p P, \p Q from \p N, \p D, | |
292 | * and \p E if the former are not part of the | |
293 | * implementation.</li></ul> | |
294 | * | |
295 | * If the function fails due to an unsupported operation, | |
296 | * the RSA context stays intact and remains usable. | |
297 | * | |
298 | * \param ctx The initialized RSA context. | |
299 | * \param N The MPI to hold the RSA modulus, or NULL. | |
300 | * \param P The MPI to hold the first prime factor of \p N, or NULL. | |
301 | * \param Q The MPI to hold the second prime factor of \p N, or NULL. | |
302 | * \param D The MPI to hold the private exponent, or NULL. | |
303 | * \param E The MPI to hold the public exponent, or NULL. | |
304 | * | |
305 | * \return \c 0 on success. | |
306 | * \return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the | |
307 | * requested parameters cannot be done due to missing | |
308 | * functionality or because of security policies. | |
309 | * \return A non-zero return code on any other failure. | |
310 | * | |
311 | */ | |
312 | int mbedtls_rsa_export( const mbedtls_rsa_context *ctx, | |
313 | mbedtls_mpi *N, mbedtls_mpi *P, mbedtls_mpi *Q, | |
314 | mbedtls_mpi *D, mbedtls_mpi *E ); | |
315 | ||
316 | /** | |
317 | * \brief This function exports core parameters of an RSA key | |
318 | * in raw big-endian binary format. | |
319 | * | |
320 | * If this function runs successfully, the non-NULL buffers | |
321 | * pointed to by \p N, \p P, \p Q, \p D, and \p E are fully | |
322 | * written, with additional unused space filled leading by | |
323 | * zero Bytes. | |
324 | * | |
325 | * Possible reasons for returning | |
326 | * #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION:<ul> | |
327 | * <li>An alternative RSA implementation is in use, which | |
328 | * stores the key externally, and either cannot or should | |
329 | * not export it into RAM.</li> | |
330 | * <li>A SW or HW implementation might not support a certain | |
331 | * deduction. For example, \p P, \p Q from \p N, \p D, | |
332 | * and \p E if the former are not part of the | |
333 | * implementation.</li></ul> | |
334 | * If the function fails due to an unsupported operation, | |
335 | * the RSA context stays intact and remains usable. | |
336 | * | |
337 | * \note The length parameters are ignored if the corresponding | |
338 | * buffer pointers are NULL. | |
339 | * | |
340 | * \param ctx The initialized RSA context. | |
341 | * \param N The Byte array to store the RSA modulus, or NULL. | |
342 | * \param N_len The size of the buffer for the modulus. | |
343 | * \param P The Byte array to hold the first prime factor of \p N, or | |
344 | * NULL. | |
345 | * \param P_len The size of the buffer for the first prime factor. | |
346 | * \param Q The Byte array to hold the second prime factor of \p N, or | |
347 | * NULL. | |
348 | * \param Q_len The size of the buffer for the second prime factor. | |
349 | * \param D The Byte array to hold the private exponent, or NULL. | |
350 | * \param D_len The size of the buffer for the private exponent. | |
351 | * \param E The Byte array to hold the public exponent, or NULL. | |
352 | * \param E_len The size of the buffer for the public exponent. | |
353 | * | |
354 | * \return \c 0 on success. | |
355 | * \return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the | |
356 | * requested parameters cannot be done due to missing | |
357 | * functionality or because of security policies. | |
358 | * \return A non-zero return code on any other failure. | |
359 | */ | |
360 | int mbedtls_rsa_export_raw( const mbedtls_rsa_context *ctx, | |
361 | unsigned char *N, size_t N_len, | |
362 | unsigned char *P, size_t P_len, | |
363 | unsigned char *Q, size_t Q_len, | |
364 | unsigned char *D, size_t D_len, | |
365 | unsigned char *E, size_t E_len ); | |
366 | ||
367 | /** | |
368 | * \brief This function exports CRT parameters of a private RSA key. | |
369 | * | |
370 | * \note Alternative RSA implementations not using CRT-parameters | |
371 | * internally can implement this function based on | |
372 | * mbedtls_rsa_deduce_opt(). | |
373 | * | |
374 | * \param ctx The initialized RSA context. | |
375 | * \param DP The MPI to hold D modulo P-1, or NULL. | |
376 | * \param DQ The MPI to hold D modulo Q-1, or NULL. | |
377 | * \param QP The MPI to hold modular inverse of Q modulo P, or NULL. | |
378 | * | |
379 | * \return \c 0 on success. | |
380 | * \return A non-zero error code on failure. | |
381 | * | |
382 | */ | |
383 | int mbedtls_rsa_export_crt( const mbedtls_rsa_context *ctx, | |
384 | mbedtls_mpi *DP, mbedtls_mpi *DQ, mbedtls_mpi *QP ); | |
385 | ||
386 | /** | |
387 | * \brief This function sets padding for an already initialized RSA | |
388 | * context. See mbedtls_rsa_init() for details. | |
389 | * | |
390 | * \param ctx The RSA context to be set. | |
391 | * \param padding Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or | |
392 | * #MBEDTLS_RSA_PKCS_V21. | |
393 | * \param hash_id The #MBEDTLS_RSA_PKCS_V21 hash identifier. | |
394 | */ | |
395 | void mbedtls_rsa_set_padding( mbedtls_rsa_context *ctx, int padding, | |
396 | int hash_id); | |
397 | ||
398 | /** | |
399 | * \brief This function retrieves the length of RSA modulus in Bytes. | |
400 | * | |
401 | * \param ctx The initialized RSA context. | |
402 | * | |
403 | * \return The length of the RSA modulus in Bytes. | |
404 | * | |
405 | */ | |
406 | size_t mbedtls_rsa_get_len( const mbedtls_rsa_context *ctx ); | |
407 | ||
408 | /** | |
409 | * \brief This function generates an RSA keypair. | |
410 | * | |
411 | * \note mbedtls_rsa_init() must be called before this function, | |
412 | * to set up the RSA context. | |
413 | * | |
414 | * \param ctx The RSA context used to hold the key. | |
415 | * \param f_rng The RNG function. | |
416 | * \param p_rng The RNG context. | |
417 | * \param nbits The size of the public key in bits. | |
418 | * \param exponent The public exponent. For example, 65537. | |
419 | * | |
420 | * \return \c 0 on success. | |
421 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. | |
422 | */ | |
423 | int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx, | |
424 | int (*f_rng)(void *, unsigned char *, size_t), | |
425 | void *p_rng, | |
426 | unsigned int nbits, int exponent ); | |
427 | ||
428 | /** | |
429 | * \brief This function checks if a context contains at least an RSA | |
430 | * public key. | |
431 | * | |
432 | * If the function runs successfully, it is guaranteed that | |
433 | * enough information is present to perform an RSA public key | |
434 | * operation using mbedtls_rsa_public(). | |
435 | * | |
436 | * \param ctx The RSA context to check. | |
437 | * | |
438 | * \return \c 0 on success. | |
439 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. | |
440 | * | |
441 | */ | |
442 | int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx ); | |
443 | ||
444 | /** | |
445 | * \brief This function checks if a context contains an RSA private key | |
446 | * and perform basic consistency checks. | |
447 | * | |
448 | * \note The consistency checks performed by this function not only | |
449 | * ensure that mbedtls_rsa_private() can be called successfully | |
450 | * on the given context, but that the various parameters are | |
451 | * mutually consistent with high probability, in the sense that | |
452 | * mbedtls_rsa_public() and mbedtls_rsa_private() are inverses. | |
453 | * | |
454 | * \warning This function should catch accidental misconfigurations | |
455 | * like swapping of parameters, but it cannot establish full | |
456 | * trust in neither the quality nor the consistency of the key | |
457 | * material that was used to setup the given RSA context: | |
458 | * <ul><li>Consistency: Imported parameters that are irrelevant | |
459 | * for the implementation might be silently dropped. If dropped, | |
460 | * the current function does not have access to them, | |
461 | * and therefore cannot check them. See mbedtls_rsa_complete(). | |
462 | * If you want to check the consistency of the entire | |
463 | * content of an PKCS1-encoded RSA private key, for example, you | |
464 | * should use mbedtls_rsa_validate_params() before setting | |
465 | * up the RSA context. | |
466 | * Additionally, if the implementation performs empirical checks, | |
467 | * these checks substantiate but do not guarantee consistency.</li> | |
468 | * <li>Quality: This function is not expected to perform | |
469 | * extended quality assessments like checking that the prime | |
470 | * factors are safe. Additionally, it is the responsibility of the | |
471 | * user to ensure the trustworthiness of the source of his RSA | |
472 | * parameters, which goes beyond what is effectively checkable | |
473 | * by the library.</li></ul> | |
474 | * | |
475 | * \param ctx The RSA context to check. | |
476 | * | |
477 | * \return \c 0 on success. | |
478 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. | |
479 | */ | |
480 | int mbedtls_rsa_check_privkey( const mbedtls_rsa_context *ctx ); | |
481 | ||
482 | /** | |
483 | * \brief This function checks a public-private RSA key pair. | |
484 | * | |
485 | * It checks each of the contexts, and makes sure they match. | |
486 | * | |
487 | * \param pub The RSA context holding the public key. | |
488 | * \param prv The RSA context holding the private key. | |
489 | * | |
490 | * \return \c 0 on success. | |
491 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. | |
492 | */ | |
493 | int mbedtls_rsa_check_pub_priv( const mbedtls_rsa_context *pub, | |
494 | const mbedtls_rsa_context *prv ); | |
495 | ||
496 | /** | |
497 | * \brief This function performs an RSA public key operation. | |
498 | * | |
499 | * \note This function does not handle message padding. | |
500 | * | |
501 | * \note Make sure to set \p input[0] = 0 or ensure that | |
502 | * input is smaller than \p N. | |
503 | * | |
504 | * \note The input and output buffers must be large | |
505 | * enough. For example, 128 Bytes if RSA-1024 is used. | |
506 | * | |
507 | * \param ctx The RSA context. | |
508 | * \param input The input buffer. | |
509 | * \param output The output buffer. | |
510 | * | |
511 | * \return \c 0 on success. | |
512 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. | |
513 | */ | |
514 | int mbedtls_rsa_public( mbedtls_rsa_context *ctx, | |
515 | const unsigned char *input, | |
516 | unsigned char *output ); | |
517 | ||
518 | /** | |
519 | * \brief This function performs an RSA private key operation. | |
520 | * | |
521 | * \note The input and output buffers must be large | |
522 | * enough. For example, 128 Bytes if RSA-1024 is used. | |
523 | * | |
524 | * \note Blinding is used if and only if a PRNG is provided. | |
525 | * | |
526 | * \note If blinding is used, both the base of exponentation | |
527 | * and the exponent are blinded, providing protection | |
528 | * against some side-channel attacks. | |
529 | * | |
530 | * \warning It is deprecated and a security risk to not provide | |
531 | * a PRNG here and thereby prevent the use of blinding. | |
532 | * Future versions of the library may enforce the presence | |
533 | * of a PRNG. | |
534 | * | |
535 | * \param ctx The RSA context. | |
536 | * \param f_rng The RNG function. Needed for blinding. | |
537 | * \param p_rng The RNG context. | |
538 | * \param input The input buffer. | |
539 | * \param output The output buffer. | |
540 | * | |
541 | * \return \c 0 on success. | |
542 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. | |
543 | * | |
544 | */ | |
545 | int mbedtls_rsa_private( mbedtls_rsa_context *ctx, | |
546 | int (*f_rng)(void *, unsigned char *, size_t), | |
547 | void *p_rng, | |
548 | const unsigned char *input, | |
549 | unsigned char *output ); | |
550 | ||
551 | /** | |
552 | * \brief This function adds the message padding, then performs an RSA | |
553 | * operation. | |
554 | * | |
555 | * It is the generic wrapper for performing a PKCS#1 encryption | |
556 | * operation using the \p mode from the context. | |
557 | * | |
558 | * \note The input and output buffers must be as large as the size | |
559 | * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. | |
560 | * | |
561 | * \deprecated It is deprecated and discouraged to call this function | |
562 | * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library | |
563 | * are likely to remove the \p mode argument and have it | |
564 | * implicitly set to #MBEDTLS_RSA_PUBLIC. | |
565 | * | |
566 | * \note Alternative implementations of RSA need not support | |
567 | * mode being set to #MBEDTLS_RSA_PRIVATE and might instead | |
568 | * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. | |
569 | * | |
570 | * \param ctx The RSA context. | |
571 | * \param f_rng The RNG function. Needed for padding, PKCS#1 v2.1 | |
572 | * encoding, and #MBEDTLS_RSA_PRIVATE. | |
573 | * \param p_rng The RNG context. | |
574 | * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. | |
575 | * \param ilen The length of the plaintext. | |
576 | * \param input The buffer holding the data to encrypt. | |
577 | * \param output The buffer used to hold the ciphertext. | |
578 | * | |
579 | * \return \c 0 on success. | |
580 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. | |
581 | */ | |
582 | int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx, | |
583 | int (*f_rng)(void *, unsigned char *, size_t), | |
584 | void *p_rng, | |
585 | int mode, size_t ilen, | |
586 | const unsigned char *input, | |
587 | unsigned char *output ); | |
588 | ||
589 | /** | |
590 | * \brief This function performs a PKCS#1 v1.5 encryption operation | |
591 | * (RSAES-PKCS1-v1_5-ENCRYPT). | |
592 | * | |
593 | * \note The output buffer must be as large as the size | |
594 | * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. | |
595 | * | |
596 | * \deprecated It is deprecated and discouraged to call this function | |
597 | * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library | |
598 | * are likely to remove the \p mode argument and have it | |
599 | * implicitly set to #MBEDTLS_RSA_PUBLIC. | |
600 | * | |
601 | * \note Alternative implementations of RSA need not support | |
602 | * mode being set to #MBEDTLS_RSA_PRIVATE and might instead | |
603 | * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. | |
604 | * | |
605 | * \param ctx The RSA context. | |
606 | * \param f_rng The RNG function. Needed for padding and | |
607 | * #MBEDTLS_RSA_PRIVATE. | |
608 | * \param p_rng The RNG context. | |
609 | * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. | |
610 | * \param ilen The length of the plaintext. | |
611 | * \param input The buffer holding the data to encrypt. | |
612 | * \param output The buffer used to hold the ciphertext. | |
613 | * | |
614 | * \return \c 0 on success. | |
615 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. | |
616 | */ | |
617 | int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx, | |
618 | int (*f_rng)(void *, unsigned char *, size_t), | |
619 | void *p_rng, | |
620 | int mode, size_t ilen, | |
621 | const unsigned char *input, | |
622 | unsigned char *output ); | |
623 | ||
624 | /** | |
625 | * \brief This function performs a PKCS#1 v2.1 OAEP encryption | |
626 | * operation (RSAES-OAEP-ENCRYPT). | |
627 | * | |
628 | * \note The output buffer must be as large as the size | |
629 | * of ctx->N. For example, 128 Bytes if RSA-1024 is used. | |
630 | * | |
631 | * \deprecated It is deprecated and discouraged to call this function | |
632 | * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library | |
633 | * are likely to remove the \p mode argument and have it | |
634 | * implicitly set to #MBEDTLS_RSA_PUBLIC. | |
635 | * | |
636 | * \note Alternative implementations of RSA need not support | |
637 | * mode being set to #MBEDTLS_RSA_PRIVATE and might instead | |
638 | * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. | |
639 | * | |
640 | * \param ctx The RSA context. | |
641 | * \param f_rng The RNG function. Needed for padding and PKCS#1 v2.1 | |
642 | * encoding and #MBEDTLS_RSA_PRIVATE. | |
643 | * \param p_rng The RNG context. | |
644 | * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. | |
645 | * \param label The buffer holding the custom label to use. | |
646 | * \param label_len The length of the label. | |
647 | * \param ilen The length of the plaintext. | |
648 | * \param input The buffer holding the data to encrypt. | |
649 | * \param output The buffer used to hold the ciphertext. | |
650 | * | |
651 | * \return \c 0 on success. | |
652 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. | |
653 | */ | |
654 | int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx, | |
655 | int (*f_rng)(void *, unsigned char *, size_t), | |
656 | void *p_rng, | |
657 | int mode, | |
658 | const unsigned char *label, size_t label_len, | |
659 | size_t ilen, | |
660 | const unsigned char *input, | |
661 | unsigned char *output ); | |
662 | ||
663 | /** | |
664 | * \brief This function performs an RSA operation, then removes the | |
665 | * message padding. | |
666 | * | |
667 | * It is the generic wrapper for performing a PKCS#1 decryption | |
668 | * operation using the \p mode from the context. | |
669 | * | |
670 | * \note The output buffer length \c output_max_len should be | |
671 | * as large as the size \p ctx->len of \p ctx->N (for example, | |
672 | * 128 Bytes if RSA-1024 is used) to be able to hold an | |
673 | * arbitrary decrypted message. If it is not large enough to | |
674 | * hold the decryption of the particular ciphertext provided, | |
675 | * the function returns \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. | |
676 | * | |
677 | * \note The input buffer must be as large as the size | |
678 | * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. | |
679 | * | |
680 | * \deprecated It is deprecated and discouraged to call this function | |
681 | * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library | |
682 | * are likely to remove the \p mode argument and have it | |
683 | * implicitly set to #MBEDTLS_RSA_PRIVATE. | |
684 | * | |
685 | * \note Alternative implementations of RSA need not support | |
686 | * mode being set to #MBEDTLS_RSA_PUBLIC and might instead | |
687 | * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. | |
688 | * | |
689 | * \param ctx The RSA context. | |
690 | * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. | |
691 | * \param p_rng The RNG context. | |
692 | * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. | |
693 | * \param olen The length of the plaintext. | |
694 | * \param input The buffer holding the encrypted data. | |
695 | * \param output The buffer used to hold the plaintext. | |
696 | * \param output_max_len The maximum length of the output buffer. | |
697 | * | |
698 | * \return \c 0 on success. | |
699 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. | |
700 | */ | |
701 | int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx, | |
702 | int (*f_rng)(void *, unsigned char *, size_t), | |
703 | void *p_rng, | |
704 | int mode, size_t *olen, | |
705 | const unsigned char *input, | |
706 | unsigned char *output, | |
707 | size_t output_max_len ); | |
708 | ||
709 | /** | |
710 | * \brief This function performs a PKCS#1 v1.5 decryption | |
711 | * operation (RSAES-PKCS1-v1_5-DECRYPT). | |
712 | * | |
713 | * \note The output buffer length \c output_max_len should be | |
714 | * as large as the size \p ctx->len of \p ctx->N, for example, | |
715 | * 128 Bytes if RSA-1024 is used, to be able to hold an | |
716 | * arbitrary decrypted message. If it is not large enough to | |
717 | * hold the decryption of the particular ciphertext provided, | |
718 | * the function returns #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. | |
719 | * | |
720 | * \note The input buffer must be as large as the size | |
721 | * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. | |
722 | * | |
723 | * \deprecated It is deprecated and discouraged to call this function | |
724 | * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library | |
725 | * are likely to remove the \p mode argument and have it | |
726 | * implicitly set to #MBEDTLS_RSA_PRIVATE. | |
727 | * | |
728 | * \note Alternative implementations of RSA need not support | |
729 | * mode being set to #MBEDTLS_RSA_PUBLIC and might instead | |
730 | * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. | |
731 | * | |
732 | * \param ctx The RSA context. | |
733 | * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. | |
734 | * \param p_rng The RNG context. | |
735 | * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. | |
736 | * \param olen The length of the plaintext. | |
737 | * \param input The buffer holding the encrypted data. | |
738 | * \param output The buffer to hold the plaintext. | |
739 | * \param output_max_len The maximum length of the output buffer. | |
740 | * | |
741 | * \return \c 0 on success. | |
742 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. | |
743 | * | |
744 | */ | |
745 | int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx, | |
746 | int (*f_rng)(void *, unsigned char *, size_t), | |
747 | void *p_rng, | |
748 | int mode, size_t *olen, | |
749 | const unsigned char *input, | |
750 | unsigned char *output, | |
751 | size_t output_max_len ); | |
752 | ||
753 | /** | |
754 | * \brief This function performs a PKCS#1 v2.1 OAEP decryption | |
755 | * operation (RSAES-OAEP-DECRYPT). | |
756 | * | |
757 | * \note The output buffer length \c output_max_len should be | |
758 | * as large as the size \p ctx->len of \p ctx->N, for | |
759 | * example, 128 Bytes if RSA-1024 is used, to be able to | |
760 | * hold an arbitrary decrypted message. If it is not | |
761 | * large enough to hold the decryption of the particular | |
762 | * ciphertext provided, the function returns | |
763 | * #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. | |
764 | * | |
765 | * \note The input buffer must be as large as the size | |
766 | * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. | |
767 | * | |
768 | * \deprecated It is deprecated and discouraged to call this function | |
769 | * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library | |
770 | * are likely to remove the \p mode argument and have it | |
771 | * implicitly set to #MBEDTLS_RSA_PRIVATE. | |
772 | * | |
773 | * \note Alternative implementations of RSA need not support | |
774 | * mode being set to #MBEDTLS_RSA_PUBLIC and might instead | |
775 | * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. | |
776 | * | |
777 | * \param ctx The RSA context. | |
778 | * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. | |
779 | * \param p_rng The RNG context. | |
780 | * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. | |
781 | * \param label The buffer holding the custom label to use. | |
782 | * \param label_len The length of the label. | |
783 | * \param olen The length of the plaintext. | |
784 | * \param input The buffer holding the encrypted data. | |
785 | * \param output The buffer to hold the plaintext. | |
786 | * \param output_max_len The maximum length of the output buffer. | |
787 | * | |
788 | * \return \c 0 on success. | |
789 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. | |
790 | */ | |
791 | int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx, | |
792 | int (*f_rng)(void *, unsigned char *, size_t), | |
793 | void *p_rng, | |
794 | int mode, | |
795 | const unsigned char *label, size_t label_len, | |
796 | size_t *olen, | |
797 | const unsigned char *input, | |
798 | unsigned char *output, | |
799 | size_t output_max_len ); | |
800 | ||
801 | /** | |
802 | * \brief This function performs a private RSA operation to sign | |
803 | * a message digest using PKCS#1. | |
804 | * | |
805 | * It is the generic wrapper for performing a PKCS#1 | |
806 | * signature using the \p mode from the context. | |
807 | * | |
808 | * \note The \p sig buffer must be as large as the size | |
809 | * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. | |
810 | * | |
811 | * \note For PKCS#1 v2.1 encoding, see comments on | |
812 | * mbedtls_rsa_rsassa_pss_sign() for details on | |
813 | * \p md_alg and \p hash_id. | |
814 | * | |
815 | * \deprecated It is deprecated and discouraged to call this function | |
816 | * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library | |
817 | * are likely to remove the \p mode argument and have it | |
818 | * implicitly set to #MBEDTLS_RSA_PRIVATE. | |
819 | * | |
820 | * \note Alternative implementations of RSA need not support | |
821 | * mode being set to #MBEDTLS_RSA_PUBLIC and might instead | |
822 | * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. | |
823 | * | |
824 | * \param ctx The RSA context. | |
825 | * \param f_rng The RNG function. Needed for PKCS#1 v2.1 encoding and for | |
826 | * #MBEDTLS_RSA_PRIVATE. | |
827 | * \param p_rng The RNG context. | |
828 | * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. | |
829 | * \param md_alg The message-digest algorithm used to hash the original data. | |
830 | * Use #MBEDTLS_MD_NONE for signing raw data. | |
831 | * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE. | |
832 | * \param hash The buffer holding the message digest. | |
833 | * \param sig The buffer to hold the ciphertext. | |
834 | * | |
835 | * \return \c 0 if the signing operation was successful. | |
836 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. | |
837 | */ | |
838 | int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx, | |
839 | int (*f_rng)(void *, unsigned char *, size_t), | |
840 | void *p_rng, | |
841 | int mode, | |
842 | mbedtls_md_type_t md_alg, | |
843 | unsigned int hashlen, | |
844 | const unsigned char *hash, | |
845 | unsigned char *sig ); | |
846 | ||
847 | /** | |
848 | * \brief This function performs a PKCS#1 v1.5 signature | |
849 | * operation (RSASSA-PKCS1-v1_5-SIGN). | |
850 | * | |
851 | * \note The \p sig buffer must be as large as the size | |
852 | * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. | |
853 | * | |
854 | * \deprecated It is deprecated and discouraged to call this function | |
855 | * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library | |
856 | * are likely to remove the \p mode argument and have it | |
857 | * implicitly set to #MBEDTLS_RSA_PRIVATE. | |
858 | * | |
859 | * \note Alternative implementations of RSA need not support | |
860 | * mode being set to #MBEDTLS_RSA_PUBLIC and might instead | |
861 | * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. | |
862 | * | |
863 | * \param ctx The RSA context. | |
864 | * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. | |
865 | * \param p_rng The RNG context. | |
866 | * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. | |
867 | * \param md_alg The message-digest algorithm used to hash the original data. | |
868 | * Use #MBEDTLS_MD_NONE for signing raw data. | |
869 | * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE. | |
870 | * \param hash The buffer holding the message digest. | |
871 | * \param sig The buffer to hold the ciphertext. | |
872 | * | |
873 | * \return \c 0 if the signing operation was successful. | |
874 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. | |
875 | */ | |
876 | int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx, | |
877 | int (*f_rng)(void *, unsigned char *, size_t), | |
878 | void *p_rng, | |
879 | int mode, | |
880 | mbedtls_md_type_t md_alg, | |
881 | unsigned int hashlen, | |
882 | const unsigned char *hash, | |
883 | unsigned char *sig ); | |
884 | ||
885 | /** | |
886 | * \brief This function performs a PKCS#1 v2.1 PSS signature | |
887 | * operation (RSASSA-PSS-SIGN). | |
888 | * | |
889 | * \note The \p sig buffer must be as large as the size | |
890 | * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. | |
891 | * | |
892 | * \note The \p hash_id in the RSA context is the one used for the | |
893 | * encoding. \p md_alg in the function call is the type of hash | |
894 | * that is encoded. According to <em>RFC-3447: Public-Key | |
895 | * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography | |
896 | * Specifications</em> it is advised to keep both hashes the | |
897 | * same. | |
898 | * | |
899 | * \deprecated It is deprecated and discouraged to call this function | |
900 | * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library | |
901 | * are likely to remove the \p mode argument and have it | |
902 | * implicitly set to #MBEDTLS_RSA_PRIVATE. | |
903 | * | |
904 | * \note Alternative implementations of RSA need not support | |
905 | * mode being set to #MBEDTLS_RSA_PUBLIC and might instead | |
906 | * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. | |
907 | * | |
908 | * \param ctx The RSA context. | |
909 | * \param f_rng The RNG function. Needed for PKCS#1 v2.1 encoding and for | |
910 | * #MBEDTLS_RSA_PRIVATE. | |
911 | * \param p_rng The RNG context. | |
912 | * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. | |
913 | * \param md_alg The message-digest algorithm used to hash the original data. | |
914 | * Use #MBEDTLS_MD_NONE for signing raw data. | |
915 | * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE. | |
916 | * \param hash The buffer holding the message digest. | |
917 | * \param sig The buffer to hold the ciphertext. | |
918 | * | |
919 | * \return \c 0 if the signing operation was successful. | |
920 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. | |
921 | */ | |
922 | int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx, | |
923 | int (*f_rng)(void *, unsigned char *, size_t), | |
924 | void *p_rng, | |
925 | int mode, | |
926 | mbedtls_md_type_t md_alg, | |
927 | unsigned int hashlen, | |
928 | const unsigned char *hash, | |
929 | unsigned char *sig ); | |
930 | ||
931 | /** | |
932 | * \brief This function performs a public RSA operation and checks | |
933 | * the message digest. | |
934 | * | |
935 | * This is the generic wrapper for performing a PKCS#1 | |
936 | * verification using the mode from the context. | |
937 | * | |
938 | * \note The \p sig buffer must be as large as the size | |
939 | * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. | |
940 | * | |
941 | * \note For PKCS#1 v2.1 encoding, see comments on | |
942 | * mbedtls_rsa_rsassa_pss_verify() about \p md_alg and | |
943 | * \p hash_id. | |
944 | * | |
945 | * \deprecated It is deprecated and discouraged to call this function | |
946 | * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library | |
947 | * are likely to remove the \p mode argument and have it | |
948 | * set to #MBEDTLS_RSA_PUBLIC. | |
949 | * | |
950 | * \note Alternative implementations of RSA need not support | |
951 | * mode being set to #MBEDTLS_RSA_PRIVATE and might instead | |
952 | * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. | |
953 | * | |
954 | * \param ctx The RSA public key context. | |
955 | * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. | |
956 | * \param p_rng The RNG context. | |
957 | * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. | |
958 | * \param md_alg The message-digest algorithm used to hash the original data. | |
959 | * Use #MBEDTLS_MD_NONE for signing raw data. | |
960 | * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE. | |
961 | * \param hash The buffer holding the message digest. | |
962 | * \param sig The buffer holding the ciphertext. | |
963 | * | |
964 | * \return \c 0 if the verify operation was successful. | |
965 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. | |
966 | */ | |
967 | int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx, | |
968 | int (*f_rng)(void *, unsigned char *, size_t), | |
969 | void *p_rng, | |
970 | int mode, | |
971 | mbedtls_md_type_t md_alg, | |
972 | unsigned int hashlen, | |
973 | const unsigned char *hash, | |
974 | const unsigned char *sig ); | |
975 | ||
976 | /** | |
977 | * \brief This function performs a PKCS#1 v1.5 verification | |
978 | * operation (RSASSA-PKCS1-v1_5-VERIFY). | |
979 | * | |
980 | * \note The \p sig buffer must be as large as the size | |
981 | * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. | |
982 | * | |
983 | * \deprecated It is deprecated and discouraged to call this function | |
984 | * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library | |
985 | * are likely to remove the \p mode argument and have it | |
986 | * set to #MBEDTLS_RSA_PUBLIC. | |
987 | * | |
988 | * \note Alternative implementations of RSA need not support | |
989 | * mode being set to #MBEDTLS_RSA_PRIVATE and might instead | |
990 | * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. | |
991 | * | |
992 | * \param ctx The RSA public key context. | |
993 | * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. | |
994 | * \param p_rng The RNG context. | |
995 | * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. | |
996 | * \param md_alg The message-digest algorithm used to hash the original data. | |
997 | * Use #MBEDTLS_MD_NONE for signing raw data. | |
998 | * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE. | |
999 | * \param hash The buffer holding the message digest. | |
1000 | * \param sig The buffer holding the ciphertext. | |
1001 | * | |
1002 | * \return \c 0 if the verify operation was successful. | |
1003 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. | |
1004 | */ | |
1005 | int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx, | |
1006 | int (*f_rng)(void *, unsigned char *, size_t), | |
1007 | void *p_rng, | |
1008 | int mode, | |
1009 | mbedtls_md_type_t md_alg, | |
1010 | unsigned int hashlen, | |
1011 | const unsigned char *hash, | |
1012 | const unsigned char *sig ); | |
1013 | ||
1014 | /** | |
1015 | * \brief This function performs a PKCS#1 v2.1 PSS verification | |
1016 | * operation (RSASSA-PSS-VERIFY). | |
1017 | * | |
1018 | * The hash function for the MGF mask generating function | |
1019 | * is that specified in the RSA context. | |
1020 | * | |
1021 | * \note The \p sig buffer must be as large as the size | |
1022 | * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. | |
1023 | * | |
1024 | * \note The \p hash_id in the RSA context is the one used for the | |
1025 | * verification. \p md_alg in the function call is the type of | |
1026 | * hash that is verified. According to <em>RFC-3447: Public-Key | |
1027 | * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography | |
1028 | * Specifications</em> it is advised to keep both hashes the | |
1029 | * same. If \p hash_id in the RSA context is unset, | |
1030 | * the \p md_alg from the function call is used. | |
1031 | * | |
1032 | * \deprecated It is deprecated and discouraged to call this function | |
1033 | * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library | |
1034 | * are likely to remove the \p mode argument and have it | |
1035 | * implicitly set to #MBEDTLS_RSA_PUBLIC. | |
1036 | * | |
1037 | * \note Alternative implementations of RSA need not support | |
1038 | * mode being set to #MBEDTLS_RSA_PRIVATE and might instead | |
1039 | * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. | |
1040 | * | |
1041 | * \param ctx The RSA public key context. | |
1042 | * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. | |
1043 | * \param p_rng The RNG context. | |
1044 | * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. | |
1045 | * \param md_alg The message-digest algorithm used to hash the original data. | |
1046 | * Use #MBEDTLS_MD_NONE for signing raw data. | |
1047 | * \param hashlen The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE. | |
1048 | * \param hash The buffer holding the message digest. | |
1049 | * \param sig The buffer holding the ciphertext. | |
1050 | * | |
1051 | * \return \c 0 if the verify operation was successful. | |
1052 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. | |
1053 | */ | |
1054 | int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx, | |
1055 | int (*f_rng)(void *, unsigned char *, size_t), | |
1056 | void *p_rng, | |
1057 | int mode, | |
1058 | mbedtls_md_type_t md_alg, | |
1059 | unsigned int hashlen, | |
1060 | const unsigned char *hash, | |
1061 | const unsigned char *sig ); | |
1062 | ||
1063 | /** | |
1064 | * \brief This function performs a PKCS#1 v2.1 PSS verification | |
1065 | * operation (RSASSA-PSS-VERIFY). | |
1066 | * | |
1067 | * The hash function for the MGF mask generating function | |
1068 | * is that specified in \p mgf1_hash_id. | |
1069 | * | |
1070 | * \note The \p sig buffer must be as large as the size | |
1071 | * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. | |
1072 | * | |
1073 | * \note The \p hash_id in the RSA context is ignored. | |
1074 | * | |
1075 | * \param ctx The RSA public key context. | |
1076 | * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. | |
1077 | * \param p_rng The RNG context. | |
1078 | * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. | |
1079 | * \param md_alg The message-digest algorithm used to hash the original data. | |
1080 | * Use #MBEDTLS_MD_NONE for signing raw data. | |
1081 | * \param hashlen The length of the message digest. Only used if \p md_alg is | |
1082 | * #MBEDTLS_MD_NONE. | |
1083 | * \param hash The buffer holding the message digest. | |
1084 | * \param mgf1_hash_id The message digest used for mask generation. | |
1085 | * \param expected_salt_len The length of the salt used in padding. Use | |
1086 | * #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length. | |
1087 | * \param sig The buffer holding the ciphertext. | |
1088 | * | |
1089 | * \return \c 0 if the verify operation was successful. | |
1090 | * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. | |
1091 | */ | |
1092 | int mbedtls_rsa_rsassa_pss_verify_ext( mbedtls_rsa_context *ctx, | |
1093 | int (*f_rng)(void *, unsigned char *, size_t), | |
1094 | void *p_rng, | |
1095 | int mode, | |
1096 | mbedtls_md_type_t md_alg, | |
1097 | unsigned int hashlen, | |
1098 | const unsigned char *hash, | |
1099 | mbedtls_md_type_t mgf1_hash_id, | |
1100 | int expected_salt_len, | |
1101 | const unsigned char *sig ); | |
1102 | ||
1103 | /** | |
1104 | * \brief This function copies the components of an RSA context. | |
1105 | * | |
1106 | * \param dst The destination context. | |
1107 | * \param src The source context. | |
1108 | * | |
1109 | * \return \c 0 on success. | |
1110 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure. | |
1111 | */ | |
1112 | int mbedtls_rsa_copy( mbedtls_rsa_context *dst, const mbedtls_rsa_context *src ); | |
1113 | ||
1114 | /** | |
1115 | * \brief This function frees the components of an RSA key. | |
1116 | * | |
1117 | * \param ctx The RSA Context to free. | |
1118 | */ | |
1119 | void mbedtls_rsa_free( mbedtls_rsa_context *ctx ); | |
1120 | ||
1121 | /** | |
1122 | * \brief The RSA checkup routine. | |
1123 | * | |
1124 | * \return \c 0 on success. | |
1125 | * \return \c 1 on failure. | |
1126 | */ | |
1127 | int mbedtls_rsa_self_test( int verbose ); | |
1128 | ||
1129 | #ifdef __cplusplus | |
1130 | } | |
1131 | #endif | |
1132 | ||
1133 | #endif /* rsa.h */ |