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