rsa.h

00001 /**
00002  * \file rsa.h
00003  *
00004  * \brief This file provides an API for the RSA public-key cryptosystem.
00005  *
00006  * The RSA public-key cryptosystem is defined in <em>Public-Key
00007  * Cryptography Standards (PKCS) #1 v1.5: RSA Encryption</em>
00008  * and <em>Public-Key Cryptography Standards (PKCS) #1 v2.1:
00009  * RSA Cryptography Specifications</em>.
00010  *
00011  */
00012 /*
00013  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
00014  *  SPDX-License-Identifier: Apache-2.0
00015  *
00016  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00017  *  not use this file except in compliance with the License.
00018  *  You may obtain a copy of the License at
00019  *
00020  *  http://www.apache.org/licenses/LICENSE-2.0
00021  *
00022  *  Unless required by applicable law or agreed to in writing, software
00023  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00024  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00025  *  See the License for the specific language governing permissions and
00026  *  limitations under the License.
00027  *
00028  *  This file is part of Mbed TLS (https://tls.mbed.org)
00029  */
00030 #ifndef MBEDTLS_RSA_H
00031 #define MBEDTLS_RSA_H
00032 
00033 #if !defined(MBEDTLS_CONFIG_FILE)
00034 #include "config.h"
00035 #else
00036 #include MBEDTLS_CONFIG_FILE
00037 #endif
00038 
00039 #include "bignum.h"
00040 #include "md.h"
00041 
00042 #if defined(MBEDTLS_THREADING_C)
00043 #include "threading.h"
00044 #endif
00045 
00046 /*
00047  * RSA Error codes
00048  */
00049 #define MBEDTLS_ERR_RSA_BAD_INPUT_DATA                    -0x4080  /**< Bad input parameters to function. */
00050 #define MBEDTLS_ERR_RSA_INVALID_PADDING                   -0x4100  /**< Input data contains invalid padding and is rejected. */
00051 #define MBEDTLS_ERR_RSA_KEY_GEN_FAILED                    -0x4180  /**< Something failed during generation of a key. */
00052 #define MBEDTLS_ERR_RSA_KEY_CHECK_FAILED                  -0x4200  /**< Key failed to pass the validity check of the library. */
00053 #define MBEDTLS_ERR_RSA_PUBLIC_FAILED                     -0x4280  /**< The public key operation failed. */
00054 #define MBEDTLS_ERR_RSA_PRIVATE_FAILED                    -0x4300  /**< The private key operation failed. */
00055 #define MBEDTLS_ERR_RSA_VERIFY_FAILED                     -0x4380  /**< The PKCS#1 verification failed. */
00056 #define MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE                  -0x4400  /**< The output buffer for decryption is not large enough. */
00057 #define MBEDTLS_ERR_RSA_RNG_FAILED                        -0x4480  /**< The random generator failed to generate non-zeros. */
00058 #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. */
00059 #define MBEDTLS_ERR_RSA_HW_ACCEL_FAILED                   -0x4580  /**< RSA hardware accelerator failed. */
00060 
00061 /*
00062  * RSA constants
00063  */
00064 #define MBEDTLS_RSA_PUBLIC      0 /**< Request private key operation. */
00065 #define MBEDTLS_RSA_PRIVATE     1 /**< Request public key operation. */
00066 
00067 #define MBEDTLS_RSA_PKCS_V15    0 /**< Use PKCS#1 v1.5 encoding. */
00068 #define MBEDTLS_RSA_PKCS_V21    1 /**< Use PKCS#1 v2.1 encoding. */
00069 
00070 #define MBEDTLS_RSA_SIGN        1 /**< Identifier for RSA signature operations. */
00071 #define MBEDTLS_RSA_CRYPT       2 /**< Identifier for RSA encryption and decryption operations. */
00072 
00073 #define MBEDTLS_RSA_SALT_LEN_ANY    -1
00074 
00075 /*
00076  * The above constants may be used even if the RSA module is compile out,
00077  * eg for alternative (PKCS#11) RSA implemenations in the PK layers.
00078  */
00079 
00080 #ifdef __cplusplus
00081 extern "C" {
00082 #endif
00083 
00084 #if !defined(MBEDTLS_RSA_ALT)
00085 // Regular implementation
00086 //
00087 
00088 /**
00089  * \brief   The RSA context structure.
00090  *
00091  * \note    Direct manipulation of the members of this structure
00092  *          is deprecated. All manipulation should instead be done through
00093  *          the public interface functions.
00094  */
00095 typedef struct
00096 {
00097     int ver ;                    /*!<  Always 0.*/
00098     size_t len ;                 /*!<  The size of \p N in Bytes. */
00099 
00100     mbedtls_mpi N ;              /*!<  The public modulus. */
00101     mbedtls_mpi E ;              /*!<  The public exponent. */
00102 
00103     mbedtls_mpi D ;              /*!<  The private exponent. */
00104     mbedtls_mpi P ;              /*!<  The first prime factor. */
00105     mbedtls_mpi Q ;              /*!<  The second prime factor. */
00106 
00107     mbedtls_mpi DP ;             /*!<  <code>D % (P - 1)</code>. */
00108     mbedtls_mpi DQ ;             /*!<  <code>D % (Q - 1)</code>. */
00109     mbedtls_mpi QP ;             /*!<  <code>1 / (Q % P)</code>. */
00110 
00111     mbedtls_mpi RN ;             /*!<  cached <code>R^2 mod N</code>. */
00112 
00113     mbedtls_mpi RP ;             /*!<  cached <code>R^2 mod P</code>. */
00114     mbedtls_mpi RQ ;             /*!<  cached <code>R^2 mod Q</code>. */
00115 
00116     mbedtls_mpi Vi ;             /*!<  The cached blinding value. */
00117     mbedtls_mpi Vf ;             /*!<  The cached un-blinding value. */
00118 
00119     int padding;                /*!< Selects padding mode:
00120                                      #MBEDTLS_RSA_PKCS_V15 for 1.5 padding and
00121                                      #MBEDTLS_RSA_PKCS_V21 for OAEP or PSS. */
00122     int hash_id;                /*!< Hash identifier of mbedtls_md_type_t type,
00123                                      as specified in md.h for use in the MGF
00124                                      mask generating function used in the
00125                                      EME-OAEP and EMSA-PSS encodings. */
00126 #if defined(MBEDTLS_THREADING_C)
00127     mbedtls_threading_mutex_t mutex ;    /*!<  Thread-safety mutex. */
00128 #endif
00129 }
00130 mbedtls_rsa_context;
00131 
00132 #else  /* MBEDTLS_RSA_ALT */
00133 #include "rsa_alt.h"
00134 #endif /* MBEDTLS_RSA_ALT */
00135 
00136 /**
00137  * \brief          This function initializes an RSA context.
00138  *
00139  * \note           Set padding to #MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP
00140  *                 encryption scheme and the RSASSA-PSS signature scheme.
00141  *
00142  * \note           The \p hash_id parameter is ignored when using
00143  *                 #MBEDTLS_RSA_PKCS_V15 padding.
00144  *
00145  * \note           The choice of padding mode is strictly enforced for private key
00146  *                 operations, since there might be security concerns in
00147  *                 mixing padding modes. For public key operations it is
00148  *                 a default value, which can be overriden by calling specific
00149  *                 \c rsa_rsaes_xxx or \c rsa_rsassa_xxx functions.
00150  *
00151  * \note           The hash selected in \p hash_id is always used for OEAP
00152  *                 encryption. For PSS signatures, it is always used for
00153  *                 making signatures, but can be overriden for verifying them.
00154  *                 If set to #MBEDTLS_MD_NONE, it is always overriden.
00155  *
00156  * \param ctx      The RSA context to initialize.
00157  * \param padding  Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or
00158  *                 #MBEDTLS_RSA_PKCS_V21.
00159  * \param hash_id  The hash identifier of #mbedtls_md_type_t type, if
00160  *                 \p padding is #MBEDTLS_RSA_PKCS_V21.
00161  */
00162 void mbedtls_rsa_init( mbedtls_rsa_context *ctx,
00163                        int padding,
00164                        int hash_id);
00165 
00166 /**
00167  * \brief          This function imports a set of core parameters into an
00168  *                 RSA context.
00169  *
00170  * \note           This function can be called multiple times for successive
00171  *                 imports, if the parameters are not simultaneously present.
00172  *
00173  *                 Any sequence of calls to this function should be followed
00174  *                 by a call to mbedtls_rsa_complete(), which checks and
00175  *                 completes the provided information to a ready-for-use
00176  *                 public or private RSA key.
00177  *
00178  * \note           See mbedtls_rsa_complete() for more information on which
00179  *                 parameters are necessary to set up a private or public
00180  *                 RSA key.
00181  *
00182  * \note           The imported parameters are copied and need not be preserved
00183  *                 for the lifetime of the RSA context being set up.
00184  *
00185  * \param ctx      The initialized RSA context to store the parameters in.
00186  * \param N        The RSA modulus, or NULL.
00187  * \param P        The first prime factor of \p N, or NULL.
00188  * \param Q        The second prime factor of \p N, or NULL.
00189  * \param D        The private exponent, or NULL.
00190  * \param E        The public exponent, or NULL.
00191  *
00192  * \return         \c 0 on success.
00193  * \return         A non-zero error code on failure.
00194  */
00195 int mbedtls_rsa_import( mbedtls_rsa_context *ctx,
00196                         const mbedtls_mpi *N,
00197                         const mbedtls_mpi *P, const mbedtls_mpi *Q,
00198                         const mbedtls_mpi *D, const mbedtls_mpi *E );
00199 
00200 /**
00201  * \brief          This function imports core RSA parameters, in raw big-endian
00202  *                 binary format, into an RSA context.
00203  *
00204  * \note           This function can be called multiple times for successive
00205  *                 imports, if the parameters are not simultaneously present.
00206  *
00207  *                 Any sequence of calls to this function should be followed
00208  *                 by a call to mbedtls_rsa_complete(), which checks and
00209  *                 completes the provided information to a ready-for-use
00210  *                 public or private RSA key.
00211  *
00212  * \note           See mbedtls_rsa_complete() for more information on which
00213  *                 parameters are necessary to set up a private or public
00214  *                 RSA key.
00215  *
00216  * \note           The imported parameters are copied and need not be preserved
00217  *                 for the lifetime of the RSA context being set up.
00218  *
00219  * \param ctx      The initialized RSA context to store the parameters in.
00220  * \param N        The RSA modulus, or NULL.
00221  * \param N_len    The Byte length of \p N, ignored if \p N == NULL.
00222  * \param P        The first prime factor of \p N, or NULL.
00223  * \param P_len    The Byte length of \p P, ignored if \p P == NULL.
00224  * \param Q        The second prime factor of \p N, or NULL.
00225  * \param Q_len    The Byte length of \p Q, ignored if \p Q == NULL.
00226  * \param D        The private exponent, or NULL.
00227  * \param D_len    The Byte length of \p D, ignored if \p D == NULL.
00228  * \param E        The public exponent, or NULL.
00229  * \param E_len    The Byte length of \p E, ignored if \p E == NULL.
00230  *
00231  * \return         \c 0 on success.
00232  * \return         A non-zero error code on failure.
00233  */
00234 int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx,
00235                             unsigned char const *N, size_t N_len,
00236                             unsigned char const *P, size_t P_len,
00237                             unsigned char const *Q, size_t Q_len,
00238                             unsigned char const *D, size_t D_len,
00239                             unsigned char const *E, size_t E_len );
00240 
00241 /**
00242  * \brief          This function completes an RSA context from
00243  *                 a set of imported core parameters.
00244  *
00245  *                 To setup an RSA public key, precisely \p N and \p E
00246  *                 must have been imported.
00247  *
00248  *                 To setup an RSA private key, sufficient information must
00249  *                 be present for the other parameters to be derivable.
00250  *
00251  *                 The default implementation supports the following:
00252  *                 <ul><li>Derive \p P, \p Q from \p N, \p D, \p E.</li>
00253  *                 <li>Derive \p N, \p D from \p P, \p Q, \p E.</li></ul>
00254  *                 Alternative implementations need not support these.
00255  *
00256  *                 If this function runs successfully, it guarantees that
00257  *                 the RSA context can be used for RSA operations without
00258  *                 the risk of failure or crash.
00259  *
00260  * \warning        This function need not perform consistency checks
00261  *                 for the imported parameters. In particular, parameters that
00262  *                 are not needed by the implementation might be silently
00263  *                 discarded and left unchecked. To check the consistency
00264  *                 of the key material, see mbedtls_rsa_check_privkey().
00265  *
00266  * \param ctx      The initialized RSA context holding imported parameters.
00267  *
00268  * \return         \c 0 on success.
00269  * \return         #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted derivations
00270  *                 failed.
00271  *
00272  */
00273 int mbedtls_rsa_complete( mbedtls_rsa_context *ctx );
00274 
00275 /**
00276  * \brief          This function exports the core parameters of an RSA key.
00277  *
00278  *                 If this function runs successfully, the non-NULL buffers
00279  *                 pointed to by \p N, \p P, \p Q, \p D, and \p E are fully
00280  *                 written, with additional unused space filled leading by
00281  *                 zero Bytes.
00282  *
00283  *                 Possible reasons for returning
00284  *                 #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION:<ul>
00285  *                 <li>An alternative RSA implementation is in use, which
00286  *                 stores the key externally, and either cannot or should
00287  *                 not export it into RAM.</li>
00288  *                 <li>A SW or HW implementation might not support a certain
00289  *                 deduction. For example, \p P, \p Q from \p N, \p D,
00290  *                 and \p E if the former are not part of the
00291  *                 implementation.</li></ul>
00292  *
00293  *                 If the function fails due to an unsupported operation,
00294  *                 the RSA context stays intact and remains usable.
00295  *
00296  * \param ctx      The initialized RSA context.
00297  * \param N        The MPI to hold the RSA modulus, or NULL.
00298  * \param P        The MPI to hold the first prime factor of \p N, or NULL.
00299  * \param Q        The MPI to hold the second prime factor of \p N, or NULL.
00300  * \param D        The MPI to hold the private exponent, or NULL.
00301  * \param E        The MPI to hold the public exponent, or NULL.
00302  *
00303  * \return         \c 0 on success.
00304  * \return         #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
00305  *                 requested parameters cannot be done due to missing
00306  *                 functionality or because of security policies.
00307  * \return         A non-zero return code on any other failure.
00308  *
00309  */
00310 int mbedtls_rsa_export( const mbedtls_rsa_context *ctx,
00311                         mbedtls_mpi *N, mbedtls_mpi *P, mbedtls_mpi *Q,
00312                         mbedtls_mpi *D, mbedtls_mpi *E );
00313 
00314 /**
00315  * \brief          This function exports core parameters of an RSA key
00316  *                 in raw big-endian binary format.
00317  *
00318  *                 If this function runs successfully, the non-NULL buffers
00319  *                 pointed to by \p N, \p P, \p Q, \p D, and \p E are fully
00320  *                 written, with additional unused space filled leading by
00321  *                 zero Bytes.
00322  *
00323  *                 Possible reasons for returning
00324  *                 #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION:<ul>
00325  *                 <li>An alternative RSA implementation is in use, which
00326  *                 stores the key externally, and either cannot or should
00327  *                 not export it into RAM.</li>
00328  *                 <li>A SW or HW implementation might not support a certain
00329  *                 deduction. For example, \p P, \p Q from \p N, \p D,
00330  *                 and \p E if the former are not part of the
00331  *                 implementation.</li></ul>
00332  *                 If the function fails due to an unsupported operation,
00333  *                 the RSA context stays intact and remains usable.
00334  *
00335  * \note           The length parameters are ignored if the corresponding
00336  *                 buffer pointers are NULL.
00337  *
00338  * \param ctx      The initialized RSA context.
00339  * \param N        The Byte array to store the RSA modulus, or NULL.
00340  * \param N_len    The size of the buffer for the modulus.
00341  * \param P        The Byte array to hold the first prime factor of \p N, or
00342  *                 NULL.
00343  * \param P_len    The size of the buffer for the first prime factor.
00344  * \param Q        The Byte array to hold the second prime factor of \p N, or
00345  *                 NULL.
00346  * \param Q_len    The size of the buffer for the second prime factor.
00347  * \param D        The Byte array to hold the private exponent, or NULL.
00348  * \param D_len    The size of the buffer for the private exponent.
00349  * \param E        The Byte array to hold the public exponent, or NULL.
00350  * \param E_len    The size of the buffer for the public exponent.
00351  *
00352  * \return         \c 0 on success.
00353  * \return         #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
00354  *                 requested parameters cannot be done due to missing
00355  *                 functionality or because of security policies.
00356  * \return         A non-zero return code on any other failure.
00357  */
00358 int mbedtls_rsa_export_raw( const mbedtls_rsa_context *ctx,
00359                             unsigned char *N, size_t N_len,
00360                             unsigned char *P, size_t P_len,
00361                             unsigned char *Q, size_t Q_len,
00362                             unsigned char *D, size_t D_len,
00363                             unsigned char *E, size_t E_len );
00364 
00365 /**
00366  * \brief          This function exports CRT parameters of a private RSA key.
00367  *
00368  * \note           Alternative RSA implementations not using CRT-parameters
00369  *                 internally can implement this function based on
00370  *                 mbedtls_rsa_deduce_opt().
00371  *
00372  * \param ctx      The initialized RSA context.
00373  * \param DP       The MPI to hold D modulo P-1, or NULL.
00374  * \param DQ       The MPI to hold D modulo Q-1, or NULL.
00375  * \param QP       The MPI to hold modular inverse of Q modulo P, or NULL.
00376  *
00377  * \return         \c 0 on success.
00378  * \return         A non-zero error code on failure.
00379  *
00380  */
00381 int mbedtls_rsa_export_crt( const mbedtls_rsa_context *ctx,
00382                             mbedtls_mpi *DP, mbedtls_mpi *DQ, mbedtls_mpi *QP );
00383 
00384 /**
00385  * \brief          This function sets padding for an already initialized RSA
00386  *                 context. See mbedtls_rsa_init() for details.
00387  *
00388  * \param ctx      The RSA context to be set.
00389  * \param padding  Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or
00390  *                 #MBEDTLS_RSA_PKCS_V21.
00391  * \param hash_id  The #MBEDTLS_RSA_PKCS_V21 hash identifier.
00392  */
00393 void mbedtls_rsa_set_padding( mbedtls_rsa_context *ctx, int padding,
00394                               int hash_id);
00395 
00396 /**
00397  * \brief          This function retrieves the length of RSA modulus in Bytes.
00398  *
00399  * \param ctx      The initialized RSA context.
00400  *
00401  * \return         The length of the RSA modulus in Bytes.
00402  *
00403  */
00404 size_t mbedtls_rsa_get_len( const mbedtls_rsa_context *ctx );
00405 
00406 /**
00407  * \brief          This function generates an RSA keypair.
00408  *
00409  * \note           mbedtls_rsa_init() must be called before this function,
00410  *                 to set up the RSA context.
00411  *
00412  * \param ctx      The RSA context used to hold the key.
00413  * \param f_rng    The RNG function.
00414  * \param p_rng    The RNG context.
00415  * \param nbits    The size of the public key in bits.
00416  * \param exponent The public exponent. For example, 65537.
00417  *
00418  * \return         \c 0 on success.
00419  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
00420  */
00421 int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx,
00422                          int (*f_rng)(void *, unsigned char *, size_t),
00423                          void *p_rng,
00424                          unsigned int nbits, int exponent );
00425 
00426 /**
00427  * \brief          This function checks if a context contains at least an RSA
00428  *                 public key.
00429  *
00430  *                 If the function runs successfully, it is guaranteed that
00431  *                 enough information is present to perform an RSA public key
00432  *                 operation using mbedtls_rsa_public().
00433  *
00434  * \param ctx      The RSA context to check.
00435  *
00436  * \return         \c 0 on success.
00437  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
00438  *
00439  */
00440 int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx );
00441 
00442 /**
00443  * \brief      This function checks if a context contains an RSA private key
00444  *             and perform basic consistency checks.
00445  *
00446  * \note       The consistency checks performed by this function not only
00447  *             ensure that mbedtls_rsa_private() can be called successfully
00448  *             on the given context, but that the various parameters are
00449  *             mutually consistent with high probability, in the sense that
00450  *             mbedtls_rsa_public() and mbedtls_rsa_private() are inverses.
00451  *
00452  * \warning    This function should catch accidental misconfigurations
00453  *             like swapping of parameters, but it cannot establish full
00454  *             trust in neither the quality nor the consistency of the key
00455  *             material that was used to setup the given RSA context:
00456  *             <ul><li>Consistency: Imported parameters that are irrelevant
00457  *             for the implementation might be silently dropped. If dropped,
00458  *             the current function does not have access to them,
00459  *             and therefore cannot check them. See mbedtls_rsa_complete().
00460  *             If you want to check the consistency of the entire
00461  *             content of an PKCS1-encoded RSA private key, for example, you
00462  *             should use mbedtls_rsa_validate_params() before setting
00463  *             up the RSA context.
00464  *             Additionally, if the implementation performs empirical checks,
00465  *             these checks substantiate but do not guarantee consistency.</li>
00466  *             <li>Quality: This function is not expected to perform
00467  *             extended quality assessments like checking that the prime
00468  *             factors are safe. Additionally, it is the responsibility of the
00469  *             user to ensure the trustworthiness of the source of his RSA
00470  *             parameters, which goes beyond what is effectively checkable
00471  *             by the library.</li></ul>
00472  *
00473  * \param ctx  The RSA context to check.
00474  *
00475  * \return     \c 0 on success.
00476  * \return     An \c MBEDTLS_ERR_RSA_XXX error code on failure.
00477  */
00478 int mbedtls_rsa_check_privkey( const mbedtls_rsa_context *ctx );
00479 
00480 /**
00481  * \brief          This function checks a public-private RSA key pair.
00482  *
00483  *                 It checks each of the contexts, and makes sure they match.
00484  *
00485  * \param pub      The RSA context holding the public key.
00486  * \param prv      The RSA context holding the private key.
00487  *
00488  * \return         \c 0 on success.
00489  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
00490  */
00491 int mbedtls_rsa_check_pub_priv( const mbedtls_rsa_context *pub,
00492                                 const mbedtls_rsa_context *prv );
00493 
00494 /**
00495  * \brief          This function performs an RSA public key operation.
00496  *
00497  * \note           This function does not handle message padding.
00498  *
00499  * \note           Make sure to set \p input[0] = 0 or ensure that
00500  *                 input is smaller than \p N.
00501  *
00502  * \note           The input and output buffers must be large
00503  *                 enough. For example, 128 Bytes if RSA-1024 is used.
00504  *
00505  * \param ctx      The RSA context.
00506  * \param input    The input buffer.
00507  * \param output   The output buffer.
00508  *
00509  * \return         \c 0 on success.
00510  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
00511  */
00512 int mbedtls_rsa_public( mbedtls_rsa_context *ctx,
00513                 const unsigned char *input,
00514                 unsigned char *output );
00515 
00516 /**
00517  * \brief          This function performs an RSA private key operation.
00518  *
00519  * \note           The input and output buffers must be large
00520  *                 enough. For example, 128 Bytes if RSA-1024 is used.
00521  *
00522  * \note           Blinding is used if and only if a PRNG is provided.
00523  *
00524  * \note           If blinding is used, both the base of exponentation
00525  *                 and the exponent are blinded, providing protection
00526  *                 against some side-channel attacks.
00527  *
00528  * \warning        It is deprecated and a security risk to not provide
00529  *                 a PRNG here and thereby prevent the use of blinding.
00530  *                 Future versions of the library may enforce the presence
00531  *                 of a PRNG.
00532  *
00533  * \param ctx      The RSA context.
00534  * \param f_rng    The RNG function. Needed for blinding.
00535  * \param p_rng    The RNG context.
00536  * \param input    The input buffer.
00537  * \param output   The output buffer.
00538  *
00539  * \return         \c 0 on success.
00540  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
00541  *
00542  */
00543 int mbedtls_rsa_private( mbedtls_rsa_context *ctx,
00544                  int (*f_rng)(void *, unsigned char *, size_t),
00545                  void *p_rng,
00546                  const unsigned char *input,
00547                  unsigned char *output );
00548 
00549 /**
00550  * \brief          This function adds the message padding, then performs an RSA
00551  *                 operation.
00552  *
00553  *                 It is the generic wrapper for performing a PKCS#1 encryption
00554  *                 operation using the \p mode from the context.
00555  *
00556  * \note           The input and output buffers must be as large as the size
00557  *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
00558  *
00559  * \deprecated     It is deprecated and discouraged to call this function
00560  *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
00561  *                 are likely to remove the \p mode argument and have it
00562  *                 implicitly set to #MBEDTLS_RSA_PUBLIC.
00563  *
00564  * \note           Alternative implementations of RSA need not support
00565  *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
00566  *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
00567  *
00568  * \param ctx      The RSA context.
00569  * \param f_rng    The RNG function. Needed for padding, PKCS#1 v2.1
00570  *                 encoding, and #MBEDTLS_RSA_PRIVATE.
00571  * \param p_rng    The RNG context.
00572  * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
00573  * \param ilen     The length of the plaintext.
00574  * \param input    The buffer holding the data to encrypt.
00575  * \param output   The buffer used to hold the ciphertext.
00576  *
00577  * \return         \c 0 on success.
00578  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
00579  */
00580 int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx,
00581                        int (*f_rng)(void *, unsigned char *, size_t),
00582                        void *p_rng,
00583                        int mode, size_t ilen,
00584                        const unsigned char *input,
00585                        unsigned char *output );
00586 
00587 /**
00588  * \brief          This function performs a PKCS#1 v1.5 encryption operation
00589  *                 (RSAES-PKCS1-v1_5-ENCRYPT).
00590  *
00591  * \note           The output buffer must be as large as the size
00592  *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
00593  *
00594  * \deprecated     It is deprecated and discouraged to call this function
00595  *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
00596  *                 are likely to remove the \p mode argument and have it
00597  *                 implicitly set to #MBEDTLS_RSA_PUBLIC.
00598  *
00599  * \note           Alternative implementations of RSA need not support
00600  *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
00601  *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
00602  *
00603  * \param ctx      The RSA context.
00604  * \param f_rng    The RNG function. Needed for padding and
00605  *                 #MBEDTLS_RSA_PRIVATE.
00606  * \param p_rng    The RNG context.
00607  * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
00608  * \param ilen     The length of the plaintext.
00609  * \param input    The buffer holding the data to encrypt.
00610  * \param output   The buffer used to hold the ciphertext.
00611  *
00612  * \return         \c 0 on success.
00613  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
00614  */
00615 int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx,
00616                                  int (*f_rng)(void *, unsigned char *, size_t),
00617                                  void *p_rng,
00618                                  int mode, size_t ilen,
00619                                  const unsigned char *input,
00620                                  unsigned char *output );
00621 
00622 /**
00623  * \brief            This function performs a PKCS#1 v2.1 OAEP encryption
00624  *                   operation (RSAES-OAEP-ENCRYPT).
00625  *
00626  * \note             The output buffer must be as large as the size
00627  *                   of ctx->N. For example, 128 Bytes if RSA-1024 is used.
00628  *
00629  * \deprecated       It is deprecated and discouraged to call this function
00630  *                   in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
00631  *                   are likely to remove the \p mode argument and have it
00632  *                   implicitly set to #MBEDTLS_RSA_PUBLIC.
00633  *
00634  * \note             Alternative implementations of RSA need not support
00635  *                   mode being set to #MBEDTLS_RSA_PRIVATE and might instead
00636  *                   return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
00637  *
00638  * \param ctx        The RSA context.
00639  * \param f_rng      The RNG function. Needed for padding and PKCS#1 v2.1
00640  *                   encoding and #MBEDTLS_RSA_PRIVATE.
00641  * \param p_rng      The RNG context.
00642  * \param mode       #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
00643  * \param label      The buffer holding the custom label to use.
00644  * \param label_len  The length of the label.
00645  * \param ilen       The length of the plaintext.
00646  * \param input      The buffer holding the data to encrypt.
00647  * \param output     The buffer used to hold the ciphertext.
00648  *
00649  * \return           \c 0 on success.
00650  * \return           An \c MBEDTLS_ERR_RSA_XXX error code on failure.
00651  */
00652 int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx,
00653                             int (*f_rng)(void *, unsigned char *, size_t),
00654                             void *p_rng,
00655                             int mode,
00656                             const unsigned char *label, size_t label_len,
00657                             size_t ilen,
00658                             const unsigned char *input,
00659                             unsigned char *output );
00660 
00661 /**
00662  * \brief          This function performs an RSA operation, then removes the
00663  *                 message padding.
00664  *
00665  *                 It is the generic wrapper for performing a PKCS#1 decryption
00666  *                 operation using the \p mode from the context.
00667  *
00668  * \note           The output buffer length \c output_max_len should be
00669  *                 as large as the size \p ctx->len of \p ctx->N (for example,
00670  *                 128 Bytes if RSA-1024 is used) to be able to hold an
00671  *                 arbitrary decrypted message. If it is not large enough to
00672  *                 hold the decryption of the particular ciphertext provided,
00673  *                 the function returns \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
00674  *
00675  * \note           The input buffer must be as large as the size
00676  *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
00677  *
00678  * \deprecated     It is deprecated and discouraged to call this function
00679  *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
00680  *                 are likely to remove the \p mode argument and have it
00681  *                 implicitly set to #MBEDTLS_RSA_PRIVATE.
00682  *
00683  * \note           Alternative implementations of RSA need not support
00684  *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
00685  *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
00686  *
00687  * \param ctx      The RSA context.
00688  * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
00689  * \param p_rng    The RNG context.
00690  * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
00691  * \param olen     The length of the plaintext.
00692  * \param input    The buffer holding the encrypted data.
00693  * \param output   The buffer used to hold the plaintext.
00694  * \param output_max_len    The maximum length of the output buffer.
00695  *
00696  * \return         \c 0 on success.
00697  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
00698  */
00699 int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx,
00700                        int (*f_rng)(void *, unsigned char *, size_t),
00701                        void *p_rng,
00702                        int mode, size_t *olen,
00703                        const unsigned char *input,
00704                        unsigned char *output,
00705                        size_t output_max_len );
00706 
00707 /**
00708  * \brief          This function performs a PKCS#1 v1.5 decryption
00709  *                 operation (RSAES-PKCS1-v1_5-DECRYPT).
00710  *
00711  * \note           The output buffer length \c output_max_len should be
00712  *                 as large as the size \p ctx->len of \p ctx->N, for example,
00713  *                 128 Bytes if RSA-1024 is used, to be able to hold an
00714  *                 arbitrary decrypted message. If it is not large enough to
00715  *                 hold the decryption of the particular ciphertext provided,
00716  *                 the function returns #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
00717  *
00718  * \note           The input buffer must be as large as the size
00719  *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
00720  *
00721  * \deprecated     It is deprecated and discouraged to call this function
00722  *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
00723  *                 are likely to remove the \p mode argument and have it
00724  *                 implicitly set to #MBEDTLS_RSA_PRIVATE.
00725  *
00726  * \note           Alternative implementations of RSA need not support
00727  *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
00728  *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
00729  *
00730  * \param ctx      The RSA context.
00731  * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
00732  * \param p_rng    The RNG context.
00733  * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
00734  * \param olen     The length of the plaintext.
00735  * \param input    The buffer holding the encrypted data.
00736  * \param output   The buffer to hold the plaintext.
00737  * \param output_max_len    The maximum length of the output buffer.
00738  *
00739  * \return         \c 0 on success.
00740  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
00741  *
00742  */
00743 int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx,
00744                                  int (*f_rng)(void *, unsigned char *, size_t),
00745                                  void *p_rng,
00746                                  int mode, size_t *olen,
00747                                  const unsigned char *input,
00748                                  unsigned char *output,
00749                                  size_t output_max_len );
00750 
00751 /**
00752  * \brief            This function performs a PKCS#1 v2.1 OAEP decryption
00753  *                   operation (RSAES-OAEP-DECRYPT).
00754  *
00755  * \note             The output buffer length \c output_max_len should be
00756  *                   as large as the size \p ctx->len of \p ctx->N, for
00757  *                   example, 128 Bytes if RSA-1024 is used, to be able to
00758  *                   hold an arbitrary decrypted message. If it is not
00759  *                   large enough to hold the decryption of the particular
00760  *                   ciphertext provided, the function returns
00761  *                   #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
00762  *
00763  * \note             The input buffer must be as large as the size
00764  *                   of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
00765  *
00766  * \deprecated       It is deprecated and discouraged to call this function
00767  *                   in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
00768  *                   are likely to remove the \p mode argument and have it
00769  *                   implicitly set to #MBEDTLS_RSA_PRIVATE.
00770  *
00771  * \note             Alternative implementations of RSA need not support
00772  *                   mode being set to #MBEDTLS_RSA_PUBLIC and might instead
00773  *                   return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
00774  *
00775  * \param ctx        The RSA context.
00776  * \param f_rng      The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
00777  * \param p_rng      The RNG context.
00778  * \param mode       #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
00779  * \param label      The buffer holding the custom label to use.
00780  * \param label_len  The length of the label.
00781  * \param olen       The length of the plaintext.
00782  * \param input      The buffer holding the encrypted data.
00783  * \param output     The buffer to hold the plaintext.
00784  * \param output_max_len    The maximum length of the output buffer.
00785  *
00786  * \return         \c 0 on success.
00787  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
00788  */
00789 int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx,
00790                             int (*f_rng)(void *, unsigned char *, size_t),
00791                             void *p_rng,
00792                             int mode,
00793                             const unsigned char *label, size_t label_len,
00794                             size_t *olen,
00795                             const unsigned char *input,
00796                             unsigned char *output,
00797                             size_t output_max_len );
00798 
00799 /**
00800  * \brief          This function performs a private RSA operation to sign
00801  *                 a message digest using PKCS#1.
00802  *
00803  *                 It is the generic wrapper for performing a PKCS#1
00804  *                 signature using the \p mode from the context.
00805  *
00806  * \note           The \p sig buffer must be as large as the size
00807  *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
00808  *
00809  * \note           For PKCS#1 v2.1 encoding, see comments on
00810  *                 mbedtls_rsa_rsassa_pss_sign() for details on
00811  *                 \p md_alg and \p hash_id.
00812  *
00813  * \deprecated     It is deprecated and discouraged to call this function
00814  *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
00815  *                 are likely to remove the \p mode argument and have it
00816  *                 implicitly set to #MBEDTLS_RSA_PRIVATE.
00817  *
00818  * \note           Alternative implementations of RSA need not support
00819  *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
00820  *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
00821  *
00822  * \param ctx      The RSA context.
00823  * \param f_rng    The RNG function. Needed for PKCS#1 v2.1 encoding and for
00824  *                 #MBEDTLS_RSA_PRIVATE.
00825  * \param p_rng    The RNG context.
00826  * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
00827  * \param md_alg   The message-digest algorithm used to hash the original data.
00828  *                 Use #MBEDTLS_MD_NONE for signing raw data.
00829  * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
00830  * \param hash     The buffer holding the message digest.
00831  * \param sig      The buffer to hold the ciphertext.
00832  *
00833  * \return         \c 0 if the signing operation was successful.
00834  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
00835  */
00836 int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx,
00837                     int (*f_rng)(void *, unsigned char *, size_t),
00838                     void *p_rng,
00839                     int mode,
00840                     mbedtls_md_type_t md_alg,
00841                     unsigned int hashlen,
00842                     const unsigned char *hash,
00843                     unsigned char *sig );
00844 
00845 /**
00846  * \brief          This function performs a PKCS#1 v1.5 signature
00847  *                 operation (RSASSA-PKCS1-v1_5-SIGN).
00848  *
00849  * \note           The \p sig buffer must be as large as the size
00850  *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
00851  *
00852  * \deprecated     It is deprecated and discouraged to call this function
00853  *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
00854  *                 are likely to remove the \p mode argument and have it
00855  *                 implicitly set to #MBEDTLS_RSA_PRIVATE.
00856  *
00857  * \note           Alternative implementations of RSA need not support
00858  *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
00859  *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
00860  *
00861  * \param ctx      The RSA context.
00862  * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
00863  * \param p_rng    The RNG context.
00864  * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
00865  * \param md_alg   The message-digest algorithm used to hash the original data.
00866  *                 Use #MBEDTLS_MD_NONE for signing raw data.
00867  * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
00868  * \param hash     The buffer holding the message digest.
00869  * \param sig      The buffer to hold the ciphertext.
00870  *
00871  * \return         \c 0 if the signing operation was successful.
00872  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
00873  */
00874 int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx,
00875                                int (*f_rng)(void *, unsigned char *, size_t),
00876                                void *p_rng,
00877                                int mode,
00878                                mbedtls_md_type_t md_alg,
00879                                unsigned int hashlen,
00880                                const unsigned char *hash,
00881                                unsigned char *sig );
00882 
00883 /**
00884  * \brief          This function performs a PKCS#1 v2.1 PSS signature
00885  *                 operation (RSASSA-PSS-SIGN).
00886  *
00887  * \note           The \p sig buffer must be as large as the size
00888  *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
00889  *
00890  * \note           The \p hash_id in the RSA context is the one used for the
00891  *                 encoding. \p md_alg in the function call is the type of hash
00892  *                 that is encoded. According to <em>RFC-3447: Public-Key
00893  *                 Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
00894  *                 Specifications</em> it is advised to keep both hashes the
00895  *                 same.
00896  *
00897  * \deprecated     It is deprecated and discouraged to call this function
00898  *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
00899  *                 are likely to remove the \p mode argument and have it
00900  *                 implicitly set to #MBEDTLS_RSA_PRIVATE.
00901  *
00902  * \note           Alternative implementations of RSA need not support
00903  *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
00904  *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
00905  *
00906  * \param ctx      The RSA context.
00907  * \param f_rng    The RNG function. Needed for PKCS#1 v2.1 encoding and for
00908  *                 #MBEDTLS_RSA_PRIVATE.
00909  * \param p_rng    The RNG context.
00910  * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
00911  * \param md_alg   The message-digest algorithm used to hash the original data.
00912  *                 Use #MBEDTLS_MD_NONE for signing raw data.
00913  * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
00914  * \param hash     The buffer holding the message digest.
00915  * \param sig      The buffer to hold the ciphertext.
00916  *
00917  * \return         \c 0 if the signing operation was successful.
00918  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
00919  */
00920 int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx,
00921                          int (*f_rng)(void *, unsigned char *, size_t),
00922                          void *p_rng,
00923                          int mode,
00924                          mbedtls_md_type_t md_alg,
00925                          unsigned int hashlen,
00926                          const unsigned char *hash,
00927                          unsigned char *sig );
00928 
00929 /**
00930  * \brief          This function performs a public RSA operation and checks
00931  *                 the message digest.
00932  *
00933  *                 This is the generic wrapper for performing a PKCS#1
00934  *                 verification using the mode from the context.
00935  *
00936  * \note           The \p sig buffer must be as large as the size
00937  *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
00938  *
00939  * \note           For PKCS#1 v2.1 encoding, see comments on
00940  *                 mbedtls_rsa_rsassa_pss_verify() about \p md_alg and
00941  *                 \p hash_id.
00942  *
00943  * \deprecated     It is deprecated and discouraged to call this function
00944  *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
00945  *                 are likely to remove the \p mode argument and have it
00946  *                 set to #MBEDTLS_RSA_PUBLIC.
00947  *
00948  * \note           Alternative implementations of RSA need not support
00949  *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
00950  *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
00951  *
00952  * \param ctx      The RSA public key context.
00953  * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
00954  * \param p_rng    The RNG context.
00955  * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
00956  * \param md_alg   The message-digest algorithm used to hash the original data.
00957  *                 Use #MBEDTLS_MD_NONE for signing raw data.
00958  * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
00959  * \param hash     The buffer holding the message digest.
00960  * \param sig      The buffer holding the ciphertext.
00961  *
00962  * \return         \c 0 if the verify operation was successful.
00963  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
00964  */
00965 int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx,
00966                       int (*f_rng)(void *, unsigned char *, size_t),
00967                       void *p_rng,
00968                       int mode,
00969                       mbedtls_md_type_t md_alg,
00970                       unsigned int hashlen,
00971                       const unsigned char *hash,
00972                       const unsigned char *sig );
00973 
00974 /**
00975  * \brief          This function performs a PKCS#1 v1.5 verification
00976  *                 operation (RSASSA-PKCS1-v1_5-VERIFY).
00977  *
00978  * \note           The \p sig buffer must be as large as the size
00979  *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
00980  *
00981  * \deprecated     It is deprecated and discouraged to call this function
00982  *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
00983  *                 are likely to remove the \p mode argument and have it
00984  *                 set to #MBEDTLS_RSA_PUBLIC.
00985  *
00986  * \note           Alternative implementations of RSA need not support
00987  *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
00988  *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
00989  *
00990  * \param ctx      The RSA public key context.
00991  * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
00992  * \param p_rng    The RNG context.
00993  * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
00994  * \param md_alg   The message-digest algorithm used to hash the original data.
00995  *                 Use #MBEDTLS_MD_NONE for signing raw data.
00996  * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
00997  * \param hash     The buffer holding the message digest.
00998  * \param sig      The buffer holding the ciphertext.
00999  *
01000  * \return         \c 0 if the verify operation was successful.
01001  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
01002  */
01003 int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx,
01004                                  int (*f_rng)(void *, unsigned char *, size_t),
01005                                  void *p_rng,
01006                                  int mode,
01007                                  mbedtls_md_type_t md_alg,
01008                                  unsigned int hashlen,
01009                                  const unsigned char *hash,
01010                                  const unsigned char *sig );
01011 
01012 /**
01013  * \brief          This function performs a PKCS#1 v2.1 PSS verification
01014  *                 operation (RSASSA-PSS-VERIFY).
01015  *
01016  *                 The hash function for the MGF mask generating function
01017  *                 is that specified in the RSA context.
01018  *
01019  * \note           The \p sig buffer must be as large as the size
01020  *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
01021  *
01022  * \note           The \p hash_id in the RSA context is the one used for the
01023  *                 verification. \p md_alg in the function call is the type of
01024  *                 hash that is verified. According to <em>RFC-3447: Public-Key
01025  *                 Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
01026  *                 Specifications</em> it is advised to keep both hashes the
01027  *                 same. If \p hash_id in the RSA context is unset,
01028  *                 the \p md_alg from the function call is used.
01029  *
01030  * \deprecated     It is deprecated and discouraged to call this function
01031  *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
01032  *                 are likely to remove the \p mode argument and have it
01033  *                 implicitly set to #MBEDTLS_RSA_PUBLIC.
01034  *
01035  * \note           Alternative implementations of RSA need not support
01036  *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
01037  *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
01038  *
01039  * \param ctx      The RSA public key context.
01040  * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
01041  * \param p_rng    The RNG context.
01042  * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
01043  * \param md_alg   The message-digest algorithm used to hash the original data.
01044  *                 Use #MBEDTLS_MD_NONE for signing raw data.
01045  * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
01046  * \param hash     The buffer holding the message digest.
01047  * \param sig      The buffer holding the ciphertext.
01048  *
01049  * \return         \c 0 if the verify operation was successful.
01050  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
01051  */
01052 int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx,
01053                            int (*f_rng)(void *, unsigned char *, size_t),
01054                            void *p_rng,
01055                            int mode,
01056                            mbedtls_md_type_t md_alg,
01057                            unsigned int hashlen,
01058                            const unsigned char *hash,
01059                            const unsigned char *sig );
01060 
01061 /**
01062  * \brief          This function performs a PKCS#1 v2.1 PSS verification
01063  *                 operation (RSASSA-PSS-VERIFY).
01064  *
01065  *                 The hash function for the MGF mask generating function
01066  *                 is that specified in \p mgf1_hash_id.
01067  *
01068  * \note           The \p sig buffer must be as large as the size
01069  *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
01070  *
01071  * \note           The \p hash_id in the RSA context is ignored.
01072  *
01073  * \param ctx      The RSA public key context.
01074  * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
01075  * \param p_rng    The RNG context.
01076  * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
01077  * \param md_alg   The message-digest algorithm used to hash the original data.
01078  *                 Use #MBEDTLS_MD_NONE for signing raw data.
01079  * \param hashlen  The length of the message digest. Only used if \p md_alg is
01080  *                 #MBEDTLS_MD_NONE.
01081  * \param hash     The buffer holding the message digest.
01082  * \param mgf1_hash_id       The message digest used for mask generation.
01083  * \param expected_salt_len  The length of the salt used in padding. Use
01084  *                           #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length.
01085  * \param sig      The buffer holding the ciphertext.
01086  *
01087  * \return         \c 0 if the verify operation was successful.
01088  * \return         An \c MBEDTLS_ERR_RSA_XXX error code on failure.
01089  */
01090 int mbedtls_rsa_rsassa_pss_verify_ext( mbedtls_rsa_context *ctx,
01091                                int (*f_rng)(void *, unsigned char *, size_t),
01092                                void *p_rng,
01093                                int mode,
01094                                mbedtls_md_type_t md_alg,
01095                                unsigned int hashlen,
01096                                const unsigned char *hash,
01097                                mbedtls_md_type_t mgf1_hash_id,
01098                                int expected_salt_len,
01099                                const unsigned char *sig );
01100 
01101 /**
01102  * \brief          This function copies the components of an RSA context.
01103  *
01104  * \param dst      The destination context.
01105  * \param src      The source context.
01106  *
01107  * \return         \c 0 on success.
01108  * \return         #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure.
01109  */
01110 int mbedtls_rsa_copy( mbedtls_rsa_context *dst, const mbedtls_rsa_context *src );
01111 
01112 /**
01113  * \brief          This function frees the components of an RSA key.
01114  *
01115  * \param ctx      The RSA Context to free.
01116  */
01117 void mbedtls_rsa_free( mbedtls_rsa_context *ctx );
01118 
01119 /**
01120  * \brief          The RSA checkup routine.
01121  *
01122  * \return         \c 0 on success.
01123  * \return         \c 1 on failure.
01124  */
01125 int mbedtls_rsa_self_test( int verbose );
01126 
01127 #ifdef __cplusplus
01128 }
01129 #endif
01130 
01131 #endif /* rsa.h */