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