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