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