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