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