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