extlibs/mbedtls/mbedtls/include/mbedtls/rsa.h

   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 #if defined(MBEDTLS_SELF_TEST)
1256
1257 /**
1258  * \brief          The RSA checkup routine.
1259  *
1260  * \return         \c 0 on success.
1261  * \return         \c 1 on failure.
1262  */
1263 int mbedtls_rsa_self_test( int verbose );
1264
1265 #endif /* MBEDTLS_SELF_TEST */
1266
1267 #ifdef __cplusplus
1268 }
1269 #endif
1270
1271 #endif /* rsa.h */