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