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 the RSA modulus in bits. 431 * 432 * \param ctx The initialized RSA context. 433 * 434 * \return The length of the RSA modulus in bits. 435 * 436 */ 437 size_t mbedtls_rsa_get_bitlen(const mbedtls_rsa_context *ctx); 438 439 /** 440 * \brief This function retrieves the length of RSA modulus in Bytes. 441 * 442 * \param ctx The initialized RSA context. 443 * 444 * \return The length of the RSA modulus in Bytes. 445 * 446 */ 447 size_t mbedtls_rsa_get_len(const mbedtls_rsa_context *ctx); 448 449 /** 450 * \brief This function generates an RSA keypair. 451 * 452 * \note mbedtls_rsa_init() must be called before this function, 453 * to set up the RSA context. 454 * 455 * \param ctx The initialized RSA context used to hold the key. 456 * \param f_rng The RNG function to be used for key generation. 457 * This is mandatory and must not be \c NULL. 458 * \param p_rng The RNG context to be passed to \p f_rng. 459 * This may be \c NULL if \p f_rng doesn't need a context. 460 * \param nbits The size of the public key in bits. 461 * \param exponent The public exponent to use. For example, \c 65537. 462 * This must be odd and greater than \c 1. 463 * 464 * \return \c 0 on success. 465 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 466 */ 467 int mbedtls_rsa_gen_key(mbedtls_rsa_context *ctx, 468 int (*f_rng)(void *, unsigned char *, size_t), 469 void *p_rng, 470 unsigned int nbits, int exponent); 471 472 /** 473 * \brief This function checks if a context contains at least an RSA 474 * public key. 475 * 476 * If the function runs successfully, it is guaranteed that 477 * enough information is present to perform an RSA public key 478 * operation using mbedtls_rsa_public(). 479 * 480 * \param ctx The initialized RSA context to check. 481 * 482 * \return \c 0 on success. 483 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 484 * 485 */ 486 int mbedtls_rsa_check_pubkey(const mbedtls_rsa_context *ctx); 487 488 /** 489 * \brief This function checks if a context contains an RSA private key 490 * and perform basic consistency checks. 491 * 492 * \note The consistency checks performed by this function not only 493 * ensure that mbedtls_rsa_private() can be called successfully 494 * on the given context, but that the various parameters are 495 * mutually consistent with high probability, in the sense that 496 * mbedtls_rsa_public() and mbedtls_rsa_private() are inverses. 497 * 498 * \warning This function should catch accidental misconfigurations 499 * like swapping of parameters, but it cannot establish full 500 * trust in neither the quality nor the consistency of the key 501 * material that was used to setup the given RSA context: 502 * <ul><li>Consistency: Imported parameters that are irrelevant 503 * for the implementation might be silently dropped. If dropped, 504 * the current function does not have access to them, 505 * and therefore cannot check them. See mbedtls_rsa_complete(). 506 * If you want to check the consistency of the entire 507 * content of a PKCS1-encoded RSA private key, for example, you 508 * should use mbedtls_rsa_validate_params() before setting 509 * up the RSA context. 510 * Additionally, if the implementation performs empirical checks, 511 * these checks substantiate but do not guarantee consistency.</li> 512 * <li>Quality: This function is not expected to perform 513 * extended quality assessments like checking that the prime 514 * factors are safe. Additionally, it is the responsibility of the 515 * user to ensure the trustworthiness of the source of his RSA 516 * parameters, which goes beyond what is effectively checkable 517 * by the library.</li></ul> 518 * 519 * \param ctx The initialized RSA context to check. 520 * 521 * \return \c 0 on success. 522 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 523 */ 524 int mbedtls_rsa_check_privkey(const mbedtls_rsa_context *ctx); 525 526 /** 527 * \brief This function checks a public-private RSA key pair. 528 * 529 * It checks each of the contexts, and makes sure they match. 530 * 531 * \param pub The initialized RSA context holding the public key. 532 * \param prv The initialized RSA context holding the private key. 533 * 534 * \return \c 0 on success. 535 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 536 */ 537 int mbedtls_rsa_check_pub_priv(const mbedtls_rsa_context *pub, 538 const mbedtls_rsa_context *prv); 539 540 /** 541 * \brief This function performs an RSA public key operation. 542 * 543 * \param ctx The initialized RSA context to use. 544 * \param input The input buffer. This must be a readable buffer 545 * of length \c ctx->len Bytes. For example, \c 256 Bytes 546 * for an 2048-bit RSA modulus. 547 * \param output The output buffer. This must be a writable buffer 548 * of length \c ctx->len Bytes. For example, \c 256 Bytes 549 * for an 2048-bit RSA modulus. 550 * 551 * \note This function does not handle message padding. 552 * 553 * \note Make sure to set \p input[0] = 0 or ensure that 554 * input is smaller than \c N. 555 * 556 * \return \c 0 on success. 557 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 558 */ 559 int mbedtls_rsa_public(mbedtls_rsa_context *ctx, 560 const unsigned char *input, 561 unsigned char *output); 562 563 /** 564 * \brief This function performs an RSA private key operation. 565 * 566 * \note Blinding is used if and only if a PRNG is provided. 567 * 568 * \note If blinding is used, both the base of exponentiation 569 * and the exponent are blinded, providing protection 570 * against some side-channel attacks. 571 * 572 * \warning It is deprecated and a security risk to not provide 573 * a PRNG here and thereby prevent the use of blinding. 574 * Future versions of the library may enforce the presence 575 * of a PRNG. 576 * 577 * \param ctx The initialized RSA context to use. 578 * \param f_rng The RNG function, used for blinding. It is mandatory. 579 * \param p_rng The RNG context to pass to \p f_rng. This may be \c NULL 580 * if \p f_rng doesn't need a context. 581 * \param input The input buffer. This must be a readable buffer 582 * of length \c ctx->len Bytes. For example, \c 256 Bytes 583 * for an 2048-bit RSA modulus. 584 * \param output The output buffer. This must be a writable buffer 585 * of length \c ctx->len Bytes. For example, \c 256 Bytes 586 * for an 2048-bit RSA modulus. 587 * 588 * \return \c 0 on success. 589 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 590 * 591 */ 592 int mbedtls_rsa_private(mbedtls_rsa_context *ctx, 593 int (*f_rng)(void *, unsigned char *, size_t), 594 void *p_rng, 595 const unsigned char *input, 596 unsigned char *output); 597 598 /** 599 * \brief This function adds the message padding, then performs an RSA 600 * operation. 601 * 602 * It is the generic wrapper for performing a PKCS#1 encryption 603 * operation. 604 * 605 * \param ctx The initialized RSA context to use. 606 * \param f_rng The RNG to use. It is used for padding generation 607 * and it is mandatory. 608 * \param p_rng The RNG context to be passed to \p f_rng. May be 609 * \c NULL if \p f_rng doesn't need a context argument. 610 * \param ilen The length of the plaintext in Bytes. 611 * \param input The input data to encrypt. This must be a readable 612 * buffer of size \p ilen Bytes. It may be \c NULL if 613 * `ilen == 0`. 614 * \param output The output buffer. This must be a writable buffer 615 * of length \c ctx->len Bytes. For example, \c 256 Bytes 616 * for an 2048-bit RSA modulus. 617 * 618 * \return \c 0 on success. 619 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 620 */ 621 int mbedtls_rsa_pkcs1_encrypt(mbedtls_rsa_context *ctx, 622 int (*f_rng)(void *, unsigned char *, size_t), 623 void *p_rng, 624 size_t ilen, 625 const unsigned char *input, 626 unsigned char *output); 627 628 /** 629 * \brief This function performs a PKCS#1 v1.5 encryption operation 630 * (RSAES-PKCS1-v1_5-ENCRYPT). 631 * 632 * \param ctx The initialized RSA context to use. 633 * \param f_rng The RNG function to use. It is mandatory and used for 634 * padding generation. 635 * \param p_rng The RNG context to be passed to \p f_rng. This may 636 * be \c NULL if \p f_rng doesn't need a context argument. 637 * \param ilen The length of the plaintext in Bytes. 638 * \param input The input data to encrypt. This must be a readable 639 * buffer of size \p ilen Bytes. It may be \c NULL if 640 * `ilen == 0`. 641 * \param output The output buffer. This must be a writable buffer 642 * of length \c ctx->len Bytes. For example, \c 256 Bytes 643 * for an 2048-bit RSA modulus. 644 * 645 * \return \c 0 on success. 646 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 647 */ 648 int mbedtls_rsa_rsaes_pkcs1_v15_encrypt(mbedtls_rsa_context *ctx, 649 int (*f_rng)(void *, unsigned char *, size_t), 650 void *p_rng, 651 size_t ilen, 652 const unsigned char *input, 653 unsigned char *output); 654 655 /** 656 * \brief This function performs a PKCS#1 v2.1 OAEP encryption 657 * operation (RSAES-OAEP-ENCRYPT). 658 * 659 * \note The output buffer must be as large as the size 660 * of ctx->N. For example, 128 Bytes if RSA-1024 is used. 661 * 662 * \param ctx The initialized RSA context to use. 663 * \param f_rng The RNG function to use. This is needed for padding 664 * generation and is mandatory. 665 * \param p_rng The RNG context to be passed to \p f_rng. This may 666 * be \c NULL if \p f_rng doesn't need a context argument. 667 * \param label The buffer holding the custom label to use. 668 * This must be a readable buffer of length \p label_len 669 * Bytes. It may be \c NULL if \p label_len is \c 0. 670 * \param label_len The length of the label in Bytes. 671 * \param ilen The length of the plaintext buffer \p input in Bytes. 672 * \param input The input data to encrypt. This must be a readable 673 * buffer of size \p ilen Bytes. It may be \c NULL if 674 * `ilen == 0`. 675 * \param output The output buffer. This must be a writable buffer 676 * of length \c ctx->len Bytes. For example, \c 256 Bytes 677 * for an 2048-bit RSA modulus. 678 * 679 * \return \c 0 on success. 680 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 681 */ 682 int mbedtls_rsa_rsaes_oaep_encrypt(mbedtls_rsa_context *ctx, 683 int (*f_rng)(void *, unsigned char *, size_t), 684 void *p_rng, 685 const unsigned char *label, size_t label_len, 686 size_t ilen, 687 const unsigned char *input, 688 unsigned char *output); 689 690 /** 691 * \brief This function performs an RSA operation, then removes the 692 * message padding. 693 * 694 * It is the generic wrapper for performing a PKCS#1 decryption 695 * operation. 696 * 697 * \warning When \p ctx->padding is set to #MBEDTLS_RSA_PKCS_V15, 698 * mbedtls_rsa_rsaes_pkcs1_v15_decrypt() is called, which is an 699 * inherently dangerous function (CWE-242). 700 * 701 * \note The output buffer length \c output_max_len should be 702 * as large as the size \p ctx->len of \p ctx->N (for example, 703 * 128 Bytes if RSA-1024 is used) to be able to hold an 704 * arbitrary decrypted message. If it is not large enough to 705 * hold the decryption of the particular ciphertext provided, 706 * the function returns \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. 707 * 708 * \param ctx The initialized RSA context to use. 709 * \param f_rng The RNG function. This is used for blinding and is 710 * mandatory; see mbedtls_rsa_private() for more. 711 * \param p_rng The RNG context to be passed to \p f_rng. This may be 712 * \c NULL if \p f_rng doesn't need a context. 713 * \param olen The address at which to store the length of 714 * the plaintext. This must not be \c NULL. 715 * \param input The ciphertext buffer. This must be a readable buffer 716 * of length \c ctx->len Bytes. For example, \c 256 Bytes 717 * for an 2048-bit RSA modulus. 718 * \param output The buffer used to hold the plaintext. This must 719 * be a writable buffer of length \p output_max_len Bytes. 720 * \param output_max_len The length in Bytes of the output buffer \p output. 721 * 722 * \return \c 0 on success. 723 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 724 */ 725 int mbedtls_rsa_pkcs1_decrypt(mbedtls_rsa_context *ctx, 726 int (*f_rng)(void *, unsigned char *, size_t), 727 void *p_rng, 728 size_t *olen, 729 const unsigned char *input, 730 unsigned char *output, 731 size_t output_max_len); 732 733 /** 734 * \brief This function performs a PKCS#1 v1.5 decryption 735 * operation (RSAES-PKCS1-v1_5-DECRYPT). 736 * 737 * \warning This is an inherently dangerous function (CWE-242). Unless 738 * it is used in a side channel free and safe way (eg. 739 * implementing the TLS protocol as per 7.4.7.1 of RFC 5246), 740 * the calling code is vulnerable. 741 * 742 * \note The output buffer length \c output_max_len should be 743 * as large as the size \p ctx->len of \p ctx->N, for example, 744 * 128 Bytes if RSA-1024 is used, to be able to hold an 745 * arbitrary decrypted message. If it is not large enough to 746 * hold the decryption of the particular ciphertext provided, 747 * the function returns #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. 748 * 749 * \param ctx The initialized RSA context to use. 750 * \param f_rng The RNG function. This is used for blinding and is 751 * mandatory; see mbedtls_rsa_private() for more. 752 * \param p_rng The RNG context to be passed to \p f_rng. This may be 753 * \c NULL if \p f_rng doesn't need a context. 754 * \param olen The address at which to store the length of 755 * the plaintext. This must not be \c NULL. 756 * \param input The ciphertext buffer. This must be a readable buffer 757 * of length \c ctx->len Bytes. For example, \c 256 Bytes 758 * for an 2048-bit RSA modulus. 759 * \param output The buffer used to hold the plaintext. This must 760 * be a writable buffer of length \p output_max_len Bytes. 761 * \param output_max_len The length in Bytes of the output buffer \p output. 762 * 763 * \return \c 0 on success. 764 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 765 * 766 */ 767 int mbedtls_rsa_rsaes_pkcs1_v15_decrypt(mbedtls_rsa_context *ctx, 768 int (*f_rng)(void *, unsigned char *, size_t), 769 void *p_rng, 770 size_t *olen, 771 const unsigned char *input, 772 unsigned char *output, 773 size_t output_max_len); 774 775 /** 776 * \brief This function performs a PKCS#1 v2.1 OAEP decryption 777 * operation (RSAES-OAEP-DECRYPT). 778 * 779 * \note The output buffer length \c output_max_len should be 780 * as large as the size \p ctx->len of \p ctx->N, for 781 * example, 128 Bytes if RSA-1024 is used, to be able to 782 * hold an arbitrary decrypted message. If it is not 783 * large enough to hold the decryption of the particular 784 * ciphertext provided, the function returns 785 * #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE. 786 * 787 * \param ctx The initialized RSA context to use. 788 * \param f_rng The RNG function. This is used for blinding and is 789 * mandatory. 790 * \param p_rng The RNG context to be passed to \p f_rng. This may be 791 * \c NULL if \p f_rng doesn't need a context. 792 * \param label The buffer holding the custom label to use. 793 * This must be a readable buffer of length \p label_len 794 * Bytes. It may be \c NULL if \p label_len is \c 0. 795 * \param label_len The length of the label in Bytes. 796 * \param olen The address at which to store the length of 797 * the plaintext. This must not be \c NULL. 798 * \param input The ciphertext buffer. This must be a readable buffer 799 * of length \c ctx->len Bytes. For example, \c 256 Bytes 800 * for an 2048-bit RSA modulus. 801 * \param output The buffer used to hold the plaintext. This must 802 * be a writable buffer of length \p output_max_len Bytes. 803 * \param output_max_len The length in Bytes of the output buffer \p output. 804 * 805 * \return \c 0 on success. 806 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 807 */ 808 int mbedtls_rsa_rsaes_oaep_decrypt(mbedtls_rsa_context *ctx, 809 int (*f_rng)(void *, unsigned char *, size_t), 810 void *p_rng, 811 const unsigned char *label, size_t label_len, 812 size_t *olen, 813 const unsigned char *input, 814 unsigned char *output, 815 size_t output_max_len); 816 817 /** 818 * \brief This function performs a private RSA operation to sign 819 * a message digest using PKCS#1. 820 * 821 * It is the generic wrapper for performing a PKCS#1 822 * signature. 823 * 824 * \note The \p sig buffer must be as large as the size 825 * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. 826 * 827 * \note For PKCS#1 v2.1 encoding, see comments on 828 * mbedtls_rsa_rsassa_pss_sign() for details on 829 * \p md_alg and \p hash_id. 830 * 831 * \param ctx The initialized RSA context to use. 832 * \param f_rng The RNG function to use. This is mandatory and 833 * must not be \c NULL. 834 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL 835 * if \p f_rng doesn't need a context argument. 836 * \param md_alg The message-digest algorithm used to hash the original data. 837 * Use #MBEDTLS_MD_NONE for signing raw data. 838 * \param hashlen The length of the message digest or raw data in Bytes. 839 * If \p md_alg is not #MBEDTLS_MD_NONE, this must match the 840 * output length of the corresponding hash algorithm. 841 * \param hash The buffer holding the message digest or raw data. 842 * This must be a readable buffer of at least \p hashlen Bytes. 843 * \param sig The buffer to hold the signature. This must be a writable 844 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 845 * for an 2048-bit RSA modulus. A buffer length of 846 * #MBEDTLS_MPI_MAX_SIZE is always safe. 847 * 848 * \return \c 0 if the signing operation was successful. 849 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 850 */ 851 int mbedtls_rsa_pkcs1_sign(mbedtls_rsa_context *ctx, 852 int (*f_rng)(void *, unsigned char *, size_t), 853 void *p_rng, 854 mbedtls_md_type_t md_alg, 855 unsigned int hashlen, 856 const unsigned char *hash, 857 unsigned char *sig); 858 859 /** 860 * \brief This function performs a PKCS#1 v1.5 signature 861 * operation (RSASSA-PKCS1-v1_5-SIGN). 862 * 863 * \param ctx The initialized RSA context to use. 864 * \param f_rng The RNG function. This is used for blinding and is 865 * mandatory; see mbedtls_rsa_private() for more. 866 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL 867 * if \p f_rng doesn't need a context argument. 868 * \param md_alg The message-digest algorithm used to hash the original data. 869 * Use #MBEDTLS_MD_NONE for signing raw data. 870 * \param hashlen The length of the message digest or raw data in Bytes. 871 * If \p md_alg is not #MBEDTLS_MD_NONE, this must match the 872 * output length of the corresponding hash algorithm. 873 * \param hash The buffer holding the message digest or raw data. 874 * This must be a readable buffer of at least \p hashlen Bytes. 875 * \param sig The buffer to hold the signature. This must be a writable 876 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 877 * for an 2048-bit RSA modulus. A buffer length of 878 * #MBEDTLS_MPI_MAX_SIZE is always safe. 879 * 880 * \return \c 0 if the signing operation was successful. 881 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 882 */ 883 int mbedtls_rsa_rsassa_pkcs1_v15_sign(mbedtls_rsa_context *ctx, 884 int (*f_rng)(void *, unsigned char *, size_t), 885 void *p_rng, 886 mbedtls_md_type_t md_alg, 887 unsigned int hashlen, 888 const unsigned char *hash, 889 unsigned char *sig); 890 891 #if defined(MBEDTLS_PKCS1_V21) 892 /** 893 * \brief This function performs a PKCS#1 v2.1 PSS signature 894 * operation (RSASSA-PSS-SIGN). 895 * 896 * \note The \c hash_id set in \p ctx by calling 897 * mbedtls_rsa_set_padding() selects the hash used for the 898 * encoding operation and for the mask generation function 899 * (MGF1). For more details on the encoding operation and the 900 * mask generation function, consult <em>RFC-3447: Public-Key 901 * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography 902 * Specifications</em>. 903 * 904 * \note This function enforces that the provided salt length complies 905 * with FIPS 186-4 §5.5 (e) and RFC 8017 (PKCS#1 v2.2) §9.1.1 906 * step 3. The constraint is that the hash length plus the salt 907 * length plus 2 bytes must be at most the key length. If this 908 * constraint is not met, this function returns 909 * #MBEDTLS_ERR_RSA_BAD_INPUT_DATA. 910 * 911 * \param ctx The initialized RSA context to use. 912 * \param f_rng The RNG function. It is mandatory and must not be \c NULL. 913 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL 914 * if \p f_rng doesn't need a context argument. 915 * \param md_alg The message-digest algorithm used to hash the original data. 916 * Use #MBEDTLS_MD_NONE for signing raw data. 917 * \param hashlen The length of the message digest or raw data in Bytes. 918 * If \p md_alg is not #MBEDTLS_MD_NONE, this must match the 919 * output length of the corresponding hash algorithm. 920 * \param hash The buffer holding the message digest or raw data. 921 * This must be a readable buffer of at least \p hashlen Bytes. 922 * \param saltlen The length of the salt that should be used. 923 * If passed #MBEDTLS_RSA_SALT_LEN_ANY, the function will use 924 * the largest possible salt length up to the hash length, 925 * which is the largest permitted by some standards including 926 * FIPS 186-4 §5.5. 927 * \param sig The buffer to hold the signature. This must be a writable 928 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 929 * for an 2048-bit RSA modulus. A buffer length of 930 * #MBEDTLS_MPI_MAX_SIZE is always safe. 931 * 932 * \return \c 0 if the signing operation was successful. 933 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 934 */ 935 int mbedtls_rsa_rsassa_pss_sign_ext(mbedtls_rsa_context *ctx, 936 int (*f_rng)(void *, unsigned char *, size_t), 937 void *p_rng, 938 mbedtls_md_type_t md_alg, 939 unsigned int hashlen, 940 const unsigned char *hash, 941 int saltlen, 942 unsigned char *sig); 943 944 /** 945 * \brief This function performs a PKCS#1 v2.1 PSS signature 946 * operation (RSASSA-PSS-SIGN). 947 * 948 * \note The \c hash_id set in \p ctx by calling 949 * mbedtls_rsa_set_padding() selects the hash used for the 950 * encoding operation and for the mask generation function 951 * (MGF1). For more details on the encoding operation and the 952 * mask generation function, consult <em>RFC-3447: Public-Key 953 * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography 954 * Specifications</em>. 955 * 956 * \note This function always uses the maximum possible salt size, 957 * up to the length of the payload hash. This choice of salt 958 * size complies with FIPS 186-4 §5.5 (e) and RFC 8017 (PKCS#1 959 * v2.2) §9.1.1 step 3. Furthermore this function enforces a 960 * minimum salt size which is the hash size minus 2 bytes. If 961 * this minimum size is too large given the key size (the salt 962 * size, plus the hash size, plus 2 bytes must be no more than 963 * the key size in bytes), this function returns 964 * #MBEDTLS_ERR_RSA_BAD_INPUT_DATA. 965 * 966 * \param ctx The initialized RSA context to use. 967 * \param f_rng The RNG function. It is mandatory and must not be \c NULL. 968 * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL 969 * if \p f_rng doesn't need a context argument. 970 * \param md_alg The message-digest algorithm used to hash the original data. 971 * Use #MBEDTLS_MD_NONE for signing raw data. 972 * \param hashlen The length of the message digest or raw data in Bytes. 973 * If \p md_alg is not #MBEDTLS_MD_NONE, this must match the 974 * output length of the corresponding hash algorithm. 975 * \param hash The buffer holding the message digest or raw data. 976 * This must be a readable buffer of at least \p hashlen Bytes. 977 * \param sig The buffer to hold the signature. This must be a writable 978 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 979 * for an 2048-bit RSA modulus. A buffer length of 980 * #MBEDTLS_MPI_MAX_SIZE is always safe. 981 * 982 * \return \c 0 if the signing operation was successful. 983 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 984 */ 985 int mbedtls_rsa_rsassa_pss_sign(mbedtls_rsa_context *ctx, 986 int (*f_rng)(void *, unsigned char *, size_t), 987 void *p_rng, 988 mbedtls_md_type_t md_alg, 989 unsigned int hashlen, 990 const unsigned char *hash, 991 unsigned char *sig); 992 #endif /* MBEDTLS_PKCS1_V21 */ 993 994 /** 995 * \brief This function performs a public RSA operation and checks 996 * the message digest. 997 * 998 * This is the generic wrapper for performing a PKCS#1 999 * verification. 1000 * 1001 * \note For PKCS#1 v2.1 encoding, see comments on 1002 * mbedtls_rsa_rsassa_pss_verify() about \c md_alg and 1003 * \c hash_id. 1004 * 1005 * \param ctx The initialized RSA public key context to use. 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 or raw data in Bytes. 1009 * If \p md_alg is not #MBEDTLS_MD_NONE, this must match the 1010 * output length of the corresponding hash algorithm. 1011 * \param hash The buffer holding the message digest or raw data. 1012 * This must be a readable buffer of at least \p hashlen Bytes. 1013 * \param sig The buffer holding the signature. This must be a readable 1014 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 1015 * for an 2048-bit RSA modulus. 1016 * 1017 * \return \c 0 if the verify operation was successful. 1018 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 1019 */ 1020 int mbedtls_rsa_pkcs1_verify(mbedtls_rsa_context *ctx, 1021 mbedtls_md_type_t md_alg, 1022 unsigned int hashlen, 1023 const unsigned char *hash, 1024 const unsigned char *sig); 1025 1026 /** 1027 * \brief This function performs a PKCS#1 v1.5 verification 1028 * operation (RSASSA-PKCS1-v1_5-VERIFY). 1029 * 1030 * \param ctx The initialized RSA public key context to use. 1031 * \param md_alg The message-digest algorithm used to hash the original data. 1032 * Use #MBEDTLS_MD_NONE for signing raw data. 1033 * \param hashlen The length of the message digest or raw data in Bytes. 1034 * If \p md_alg is not #MBEDTLS_MD_NONE, this must match the 1035 * output length of the corresponding hash algorithm. 1036 * \param hash The buffer holding the message digest or raw data. 1037 * This must be a readable buffer of at least \p hashlen Bytes. 1038 * \param sig The buffer holding the signature. This must be a readable 1039 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 1040 * for an 2048-bit RSA modulus. 1041 * 1042 * \return \c 0 if the verify operation was successful. 1043 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 1044 */ 1045 int mbedtls_rsa_rsassa_pkcs1_v15_verify(mbedtls_rsa_context *ctx, 1046 mbedtls_md_type_t md_alg, 1047 unsigned int hashlen, 1048 const unsigned char *hash, 1049 const unsigned char *sig); 1050 1051 /** 1052 * \brief This function performs a PKCS#1 v2.1 PSS verification 1053 * operation (RSASSA-PSS-VERIFY). 1054 * 1055 * \note The \c hash_id set in \p ctx by calling 1056 * mbedtls_rsa_set_padding() selects the hash used for the 1057 * encoding operation and for the mask generation function 1058 * (MGF1). For more details on the encoding operation and the 1059 * mask generation function, consult <em>RFC-3447: Public-Key 1060 * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography 1061 * Specifications</em>. If the \c hash_id set in \p ctx by 1062 * mbedtls_rsa_set_padding() is #MBEDTLS_MD_NONE, the \p md_alg 1063 * parameter is used. 1064 * 1065 * \param ctx The initialized RSA public key context to use. 1066 * \param md_alg The message-digest algorithm used to hash the original data. 1067 * Use #MBEDTLS_MD_NONE for signing raw data. 1068 * \param hashlen The length of the message digest or raw data in Bytes. 1069 * If \p md_alg is not #MBEDTLS_MD_NONE, this must match the 1070 * output length of the corresponding hash algorithm. 1071 * \param hash The buffer holding the message digest or raw data. 1072 * This must be a readable buffer of at least \p hashlen Bytes. 1073 * \param sig The buffer holding the signature. This must be a readable 1074 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 1075 * for an 2048-bit RSA modulus. 1076 * 1077 * \return \c 0 if the verify operation was successful. 1078 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 1079 */ 1080 int mbedtls_rsa_rsassa_pss_verify(mbedtls_rsa_context *ctx, 1081 mbedtls_md_type_t md_alg, 1082 unsigned int hashlen, 1083 const unsigned char *hash, 1084 const unsigned char *sig); 1085 1086 /** 1087 * \brief This function performs a PKCS#1 v2.1 PSS verification 1088 * operation (RSASSA-PSS-VERIFY). 1089 * 1090 * \note The \p sig buffer must be as large as the size 1091 * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. 1092 * 1093 * \note The \c hash_id set in \p ctx by mbedtls_rsa_set_padding() is 1094 * ignored. 1095 * 1096 * \param ctx The initialized RSA public key context to use. 1097 * \param md_alg The message-digest algorithm used to hash the original data. 1098 * Use #MBEDTLS_MD_NONE for signing raw data. 1099 * \param hashlen The length of the message digest or raw data in Bytes. 1100 * If \p md_alg is not #MBEDTLS_MD_NONE, this must match the 1101 * output length of the corresponding hash algorithm. 1102 * \param hash The buffer holding the message digest or raw data. 1103 * This must be a readable buffer of at least \p hashlen Bytes. 1104 * \param mgf1_hash_id The message digest algorithm used for the 1105 * verification operation and the mask generation 1106 * function (MGF1). For more details on the encoding 1107 * operation and the mask generation function, consult 1108 * <em>RFC-3447: Public-Key Cryptography Standards 1109 * (PKCS) #1 v2.1: RSA Cryptography 1110 * Specifications</em>. 1111 * \param expected_salt_len The length of the salt used in padding. Use 1112 * #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length. 1113 * \param sig The buffer holding the signature. This must be a readable 1114 * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes 1115 * for an 2048-bit RSA modulus. 1116 * 1117 * \return \c 0 if the verify operation was successful. 1118 * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure. 1119 */ 1120 int mbedtls_rsa_rsassa_pss_verify_ext(mbedtls_rsa_context *ctx, 1121 mbedtls_md_type_t md_alg, 1122 unsigned int hashlen, 1123 const unsigned char *hash, 1124 mbedtls_md_type_t mgf1_hash_id, 1125 int expected_salt_len, 1126 const unsigned char *sig); 1127 1128 /** 1129 * \brief This function copies the components of an RSA context. 1130 * 1131 * \param dst The destination context. This must be initialized. 1132 * \param src The source context. This must be initialized. 1133 * 1134 * \return \c 0 on success. 1135 * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure. 1136 */ 1137 int mbedtls_rsa_copy(mbedtls_rsa_context *dst, const mbedtls_rsa_context *src); 1138 1139 /** 1140 * \brief This function frees the components of an RSA key. 1141 * 1142 * \param ctx The RSA context to free. May be \c NULL, in which case 1143 * this function is a no-op. If it is not \c NULL, it must 1144 * point to an initialized RSA context. 1145 */ 1146 void mbedtls_rsa_free(mbedtls_rsa_context *ctx); 1147 1148 #if defined(MBEDTLS_SELF_TEST) 1149 1150 /** 1151 * \brief The RSA checkup routine. 1152 * 1153 * \return \c 0 on success. 1154 * \return \c 1 on failure. 1155 */ 1156 int mbedtls_rsa_self_test(int verbose); 1157 1158 #endif /* MBEDTLS_SELF_TEST */ 1159 1160 #ifdef __cplusplus 1161 } 1162 #endif 1163 1164 #endif /* rsa.h */ 1165
