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