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