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