rsa.h

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