12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274 |
- /**
- * \file rsa.h
- *
- * \brief This file provides an API for the RSA public-key cryptosystem.
- *
- * The RSA public-key cryptosystem is defined in <em>Public-Key
- * Cryptography Standards (PKCS) #1 v1.5: RSA Encryption</em>
- * and <em>Public-Key Cryptography Standards (PKCS) #1 v2.1:
- * RSA Cryptography Specifications</em>.
- *
- */
- /*
- * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
- * SPDX-License-Identifier: Apache-2.0
- *
- * Licensed under the Apache License, Version 2.0 (the "License"); you may
- * not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
- * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- *
- * This file is part of Mbed TLS (https://tls.mbed.org)
- */
- #ifndef MBEDTLS_RSA_H
- #define MBEDTLS_RSA_H
- #if !defined(MBEDTLS_CONFIG_FILE)
- #include "config.h"
- #else
- #include MBEDTLS_CONFIG_FILE
- #endif
- #include "bignum.h"
- #include "md.h"
- #if defined(MBEDTLS_THREADING_C)
- #include "threading.h"
- #endif
- /*
- * RSA Error codes
- */
- #define MBEDTLS_ERR_RSA_BAD_INPUT_DATA -0x4080 /**< Bad input parameters to function. */
- #define MBEDTLS_ERR_RSA_INVALID_PADDING -0x4100 /**< Input data contains invalid padding and is rejected. */
- #define MBEDTLS_ERR_RSA_KEY_GEN_FAILED -0x4180 /**< Something failed during generation of a key. */
- #define MBEDTLS_ERR_RSA_KEY_CHECK_FAILED -0x4200 /**< Key failed to pass the validity check of the library. */
- #define MBEDTLS_ERR_RSA_PUBLIC_FAILED -0x4280 /**< The public key operation failed. */
- #define MBEDTLS_ERR_RSA_PRIVATE_FAILED -0x4300 /**< The private key operation failed. */
- #define MBEDTLS_ERR_RSA_VERIFY_FAILED -0x4380 /**< The PKCS#1 verification failed. */
- #define MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE -0x4400 /**< The output buffer for decryption is not large enough. */
- #define MBEDTLS_ERR_RSA_RNG_FAILED -0x4480 /**< The random generator failed to generate non-zeros. */
- /* MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION is deprecated and should not be used.
- */
- #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. */
- /* MBEDTLS_ERR_RSA_HW_ACCEL_FAILED is deprecated and should not be used. */
- #define MBEDTLS_ERR_RSA_HW_ACCEL_FAILED -0x4580 /**< RSA hardware accelerator failed. */
- /*
- * RSA constants
- */
- #define MBEDTLS_RSA_PUBLIC 0 /**< Request private key operation. */
- #define MBEDTLS_RSA_PRIVATE 1 /**< Request public key operation. */
- #define MBEDTLS_RSA_PKCS_V15 0 /**< Use PKCS#1 v1.5 encoding. */
- #define MBEDTLS_RSA_PKCS_V21 1 /**< Use PKCS#1 v2.1 encoding. */
- #define MBEDTLS_RSA_SIGN 1 /**< Identifier for RSA signature operations. */
- #define MBEDTLS_RSA_CRYPT 2 /**< Identifier for RSA encryption and decryption operations. */
- #define MBEDTLS_RSA_SALT_LEN_ANY -1
- /*
- * The above constants may be used even if the RSA module is compile out,
- * eg for alternative (PKCS#11) RSA implemenations in the PK layers.
- */
- #ifdef __cplusplus
- extern "C" {
- #endif
- #if !defined(MBEDTLS_RSA_ALT)
- // Regular implementation
- //
- /**
- * \brief The RSA context structure.
- *
- * \note Direct manipulation of the members of this structure
- * is deprecated. All manipulation should instead be done through
- * the public interface functions.
- */
- typedef struct mbedtls_rsa_context
- {
- int ver; /*!< Always 0.*/
- size_t len; /*!< The size of \p N in Bytes. */
- mbedtls_mpi N; /*!< The public modulus. */
- mbedtls_mpi E; /*!< The public exponent. */
- mbedtls_mpi D; /*!< The private exponent. */
- mbedtls_mpi P; /*!< The first prime factor. */
- mbedtls_mpi Q; /*!< The second prime factor. */
- mbedtls_mpi DP; /*!< <code>D % (P - 1)</code>. */
- mbedtls_mpi DQ; /*!< <code>D % (Q - 1)</code>. */
- mbedtls_mpi QP; /*!< <code>1 / (Q % P)</code>. */
- mbedtls_mpi RN; /*!< cached <code>R^2 mod N</code>. */
- mbedtls_mpi RP; /*!< cached <code>R^2 mod P</code>. */
- mbedtls_mpi RQ; /*!< cached <code>R^2 mod Q</code>. */
- mbedtls_mpi Vi; /*!< The cached blinding value. */
- mbedtls_mpi Vf; /*!< The cached un-blinding value. */
- int padding; /*!< Selects padding mode:
- #MBEDTLS_RSA_PKCS_V15 for 1.5 padding and
- #MBEDTLS_RSA_PKCS_V21 for OAEP or PSS. */
- int hash_id; /*!< Hash identifier of mbedtls_md_type_t type,
- as specified in md.h for use in the MGF
- mask generating function used in the
- EME-OAEP and EMSA-PSS encodings. */
- #if defined(MBEDTLS_THREADING_C)
- mbedtls_threading_mutex_t mutex; /*!< Thread-safety mutex. */
- #endif
- }
- mbedtls_rsa_context;
- #else /* MBEDTLS_RSA_ALT */
- #include "rsa_alt.h"
- #endif /* MBEDTLS_RSA_ALT */
- /**
- * \brief This function initializes an RSA context.
- *
- * \note Set padding to #MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP
- * encryption scheme and the RSASSA-PSS signature scheme.
- *
- * \note The \p hash_id parameter is ignored when using
- * #MBEDTLS_RSA_PKCS_V15 padding.
- *
- * \note The choice of padding mode is strictly enforced for private key
- * operations, since there might be security concerns in
- * mixing padding modes. For public key operations it is
- * a default value, which can be overridden by calling specific
- * \c rsa_rsaes_xxx or \c rsa_rsassa_xxx functions.
- *
- * \note The hash selected in \p hash_id is always used for OEAP
- * encryption. For PSS signatures, it is always used for
- * making signatures, but can be overridden for verifying them.
- * If set to #MBEDTLS_MD_NONE, it is always overridden.
- *
- * \param ctx The RSA context to initialize. This must not be \c NULL.
- * \param padding The padding mode to use. This must be either
- * #MBEDTLS_RSA_PKCS_V15 or #MBEDTLS_RSA_PKCS_V21.
- * \param hash_id The hash identifier of ::mbedtls_md_type_t type, if
- * \p padding is #MBEDTLS_RSA_PKCS_V21. It is unused
- * otherwise.
- */
- void mbedtls_rsa_init( mbedtls_rsa_context *ctx,
- int padding,
- int hash_id );
- /**
- * \brief This function imports a set of core parameters into an
- * RSA context.
- *
- * \note This function can be called multiple times for successive
- * imports, if the parameters are not simultaneously present.
- *
- * Any sequence of calls to this function should be followed
- * by a call to mbedtls_rsa_complete(), which checks and
- * completes the provided information to a ready-for-use
- * public or private RSA key.
- *
- * \note See mbedtls_rsa_complete() for more information on which
- * parameters are necessary to set up a private or public
- * RSA key.
- *
- * \note The imported parameters are copied and need not be preserved
- * for the lifetime of the RSA context being set up.
- *
- * \param ctx The initialized RSA context to store the parameters in.
- * \param N The RSA modulus. This may be \c NULL.
- * \param P The first prime factor of \p N. This may be \c NULL.
- * \param Q The second prime factor of \p N. This may be \c NULL.
- * \param D The private exponent. This may be \c NULL.
- * \param E The public exponent. This may be \c NULL.
- *
- * \return \c 0 on success.
- * \return A non-zero error code on failure.
- */
- int mbedtls_rsa_import( mbedtls_rsa_context *ctx,
- const mbedtls_mpi *N,
- const mbedtls_mpi *P, const mbedtls_mpi *Q,
- const mbedtls_mpi *D, const mbedtls_mpi *E );
- /**
- * \brief This function imports core RSA parameters, in raw big-endian
- * binary format, into an RSA context.
- *
- * \note This function can be called multiple times for successive
- * imports, if the parameters are not simultaneously present.
- *
- * Any sequence of calls to this function should be followed
- * by a call to mbedtls_rsa_complete(), which checks and
- * completes the provided information to a ready-for-use
- * public or private RSA key.
- *
- * \note See mbedtls_rsa_complete() for more information on which
- * parameters are necessary to set up a private or public
- * RSA key.
- *
- * \note The imported parameters are copied and need not be preserved
- * for the lifetime of the RSA context being set up.
- *
- * \param ctx The initialized RSA context to store the parameters in.
- * \param N The RSA modulus. This may be \c NULL.
- * \param N_len The Byte length of \p N; it is ignored if \p N == NULL.
- * \param P The first prime factor of \p N. This may be \c NULL.
- * \param P_len The Byte length of \p P; it ns ignored if \p P == NULL.
- * \param Q The second prime factor of \p N. This may be \c NULL.
- * \param Q_len The Byte length of \p Q; it is ignored if \p Q == NULL.
- * \param D The private exponent. This may be \c NULL.
- * \param D_len The Byte length of \p D; it is ignored if \p D == NULL.
- * \param E The public exponent. This may be \c NULL.
- * \param E_len The Byte length of \p E; it is ignored if \p E == NULL.
- *
- * \return \c 0 on success.
- * \return A non-zero error code on failure.
- */
- int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx,
- unsigned char const *N, size_t N_len,
- unsigned char const *P, size_t P_len,
- unsigned char const *Q, size_t Q_len,
- unsigned char const *D, size_t D_len,
- unsigned char const *E, size_t E_len );
- /**
- * \brief This function completes an RSA context from
- * a set of imported core parameters.
- *
- * To setup an RSA public key, precisely \p N and \p E
- * must have been imported.
- *
- * To setup an RSA private key, sufficient information must
- * be present for the other parameters to be derivable.
- *
- * The default implementation supports the following:
- * <ul><li>Derive \p P, \p Q from \p N, \p D, \p E.</li>
- * <li>Derive \p N, \p D from \p P, \p Q, \p E.</li></ul>
- * Alternative implementations need not support these.
- *
- * If this function runs successfully, it guarantees that
- * the RSA context can be used for RSA operations without
- * the risk of failure or crash.
- *
- * \warning This function need not perform consistency checks
- * for the imported parameters. In particular, parameters that
- * are not needed by the implementation might be silently
- * discarded and left unchecked. To check the consistency
- * of the key material, see mbedtls_rsa_check_privkey().
- *
- * \param ctx The initialized RSA context holding imported parameters.
- *
- * \return \c 0 on success.
- * \return #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted derivations
- * failed.
- *
- */
- int mbedtls_rsa_complete( mbedtls_rsa_context *ctx );
- /**
- * \brief This function exports the core parameters of an RSA key.
- *
- * If this function runs successfully, the non-NULL buffers
- * pointed to by \p N, \p P, \p Q, \p D, and \p E are fully
- * written, with additional unused space filled leading by
- * zero Bytes.
- *
- * Possible reasons for returning
- * #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED:<ul>
- * <li>An alternative RSA implementation is in use, which
- * stores the key externally, and either cannot or should
- * not export it into RAM.</li>
- * <li>A SW or HW implementation might not support a certain
- * deduction. For example, \p P, \p Q from \p N, \p D,
- * and \p E if the former are not part of the
- * implementation.</li></ul>
- *
- * If the function fails due to an unsupported operation,
- * the RSA context stays intact and remains usable.
- *
- * \param ctx The initialized RSA context.
- * \param N The MPI to hold the RSA modulus.
- * This may be \c NULL if this field need not be exported.
- * \param P The MPI to hold the first prime factor of \p N.
- * This may be \c NULL if this field need not be exported.
- * \param Q The MPI to hold the second prime factor of \p N.
- * This may be \c NULL if this field need not be exported.
- * \param D The MPI to hold the private exponent.
- * This may be \c NULL if this field need not be exported.
- * \param E The MPI to hold the public exponent.
- * This may be \c NULL if this field need not be exported.
- *
- * \return \c 0 on success.
- * \return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED if exporting the
- * requested parameters cannot be done due to missing
- * functionality or because of security policies.
- * \return A non-zero return code on any other failure.
- *
- */
- int mbedtls_rsa_export( const mbedtls_rsa_context *ctx,
- mbedtls_mpi *N, mbedtls_mpi *P, mbedtls_mpi *Q,
- mbedtls_mpi *D, mbedtls_mpi *E );
- /**
- * \brief This function exports core parameters of an RSA key
- * in raw big-endian binary format.
- *
- * If this function runs successfully, the non-NULL buffers
- * pointed to by \p N, \p P, \p Q, \p D, and \p E are fully
- * written, with additional unused space filled leading by
- * zero Bytes.
- *
- * Possible reasons for returning
- * #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED:<ul>
- * <li>An alternative RSA implementation is in use, which
- * stores the key externally, and either cannot or should
- * not export it into RAM.</li>
- * <li>A SW or HW implementation might not support a certain
- * deduction. For example, \p P, \p Q from \p N, \p D,
- * and \p E if the former are not part of the
- * implementation.</li></ul>
- * If the function fails due to an unsupported operation,
- * the RSA context stays intact and remains usable.
- *
- * \note The length parameters are ignored if the corresponding
- * buffer pointers are NULL.
- *
- * \param ctx The initialized RSA context.
- * \param N The Byte array to store the RSA modulus,
- * or \c NULL if this field need not be exported.
- * \param N_len The size of the buffer for the modulus.
- * \param P The Byte array to hold the first prime factor of \p N,
- * or \c NULL if this field need not be exported.
- * \param P_len The size of the buffer for the first prime factor.
- * \param Q The Byte array to hold the second prime factor of \p N,
- * or \c NULL if this field need not be exported.
- * \param Q_len The size of the buffer for the second prime factor.
- * \param D The Byte array to hold the private exponent,
- * or \c NULL if this field need not be exported.
- * \param D_len The size of the buffer for the private exponent.
- * \param E The Byte array to hold the public exponent,
- * or \c NULL if this field need not be exported.
- * \param E_len The size of the buffer for the public exponent.
- *
- * \return \c 0 on success.
- * \return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED if exporting the
- * requested parameters cannot be done due to missing
- * functionality or because of security policies.
- * \return A non-zero return code on any other failure.
- */
- int mbedtls_rsa_export_raw( const mbedtls_rsa_context *ctx,
- unsigned char *N, size_t N_len,
- unsigned char *P, size_t P_len,
- unsigned char *Q, size_t Q_len,
- unsigned char *D, size_t D_len,
- unsigned char *E, size_t E_len );
- /**
- * \brief This function exports CRT parameters of a private RSA key.
- *
- * \note Alternative RSA implementations not using CRT-parameters
- * internally can implement this function based on
- * mbedtls_rsa_deduce_opt().
- *
- * \param ctx The initialized RSA context.
- * \param DP The MPI to hold \c D modulo `P-1`,
- * or \c NULL if it need not be exported.
- * \param DQ The MPI to hold \c D modulo `Q-1`,
- * or \c NULL if it need not be exported.
- * \param QP The MPI to hold modular inverse of \c Q modulo \c P,
- * or \c NULL if it need not be exported.
- *
- * \return \c 0 on success.
- * \return A non-zero error code on failure.
- *
- */
- int mbedtls_rsa_export_crt( const mbedtls_rsa_context *ctx,
- mbedtls_mpi *DP, mbedtls_mpi *DQ, mbedtls_mpi *QP );
- /**
- * \brief This function sets padding for an already initialized RSA
- * context. See mbedtls_rsa_init() for details.
- *
- * \param ctx The initialized RSA context to be configured.
- * \param padding The padding mode to use. This must be either
- * #MBEDTLS_RSA_PKCS_V15 or #MBEDTLS_RSA_PKCS_V21.
- * \param hash_id The #MBEDTLS_RSA_PKCS_V21 hash identifier.
- */
- void mbedtls_rsa_set_padding( mbedtls_rsa_context *ctx, int padding,
- int hash_id );
- /**
- * \brief This function retrieves the length of RSA modulus in Bytes.
- *
- * \param ctx The initialized RSA context.
- *
- * \return The length of the RSA modulus in Bytes.
- *
- */
- size_t mbedtls_rsa_get_len( const mbedtls_rsa_context *ctx );
- /**
- * \brief This function generates an RSA keypair.
- *
- * \note mbedtls_rsa_init() must be called before this function,
- * to set up the RSA context.
- *
- * \param ctx The initialized RSA context used to hold the key.
- * \param f_rng The RNG function to be used for key generation.
- * This must not be \c NULL.
- * \param p_rng The RNG context to be passed to \p f_rng.
- * This may be \c NULL if \p f_rng doesn't need a context.
- * \param nbits The size of the public key in bits.
- * \param exponent The public exponent to use. For example, \c 65537.
- * This must be odd and greater than \c 1.
- *
- * \return \c 0 on success.
- * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
- */
- int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx,
- int (*f_rng)(void *, unsigned char *, size_t),
- void *p_rng,
- unsigned int nbits, int exponent );
- /**
- * \brief This function checks if a context contains at least an RSA
- * public key.
- *
- * If the function runs successfully, it is guaranteed that
- * enough information is present to perform an RSA public key
- * operation using mbedtls_rsa_public().
- *
- * \param ctx The initialized RSA context to check.
- *
- * \return \c 0 on success.
- * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
- *
- */
- int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx );
- /**
- * \brief This function checks if a context contains an RSA private key
- * and perform basic consistency checks.
- *
- * \note The consistency checks performed by this function not only
- * ensure that mbedtls_rsa_private() can be called successfully
- * on the given context, but that the various parameters are
- * mutually consistent with high probability, in the sense that
- * mbedtls_rsa_public() and mbedtls_rsa_private() are inverses.
- *
- * \warning This function should catch accidental misconfigurations
- * like swapping of parameters, but it cannot establish full
- * trust in neither the quality nor the consistency of the key
- * material that was used to setup the given RSA context:
- * <ul><li>Consistency: Imported parameters that are irrelevant
- * for the implementation might be silently dropped. If dropped,
- * the current function does not have access to them,
- * and therefore cannot check them. See mbedtls_rsa_complete().
- * If you want to check the consistency of the entire
- * content of an PKCS1-encoded RSA private key, for example, you
- * should use mbedtls_rsa_validate_params() before setting
- * up the RSA context.
- * Additionally, if the implementation performs empirical checks,
- * these checks substantiate but do not guarantee consistency.</li>
- * <li>Quality: This function is not expected to perform
- * extended quality assessments like checking that the prime
- * factors are safe. Additionally, it is the responsibility of the
- * user to ensure the trustworthiness of the source of his RSA
- * parameters, which goes beyond what is effectively checkable
- * by the library.</li></ul>
- *
- * \param ctx The initialized RSA context to check.
- *
- * \return \c 0 on success.
- * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
- */
- int mbedtls_rsa_check_privkey( const mbedtls_rsa_context *ctx );
- /**
- * \brief This function checks a public-private RSA key pair.
- *
- * It checks each of the contexts, and makes sure they match.
- *
- * \param pub The initialized RSA context holding the public key.
- * \param prv The initialized RSA context holding the private key.
- *
- * \return \c 0 on success.
- * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
- */
- int mbedtls_rsa_check_pub_priv( const mbedtls_rsa_context *pub,
- const mbedtls_rsa_context *prv );
- /**
- * \brief This function performs an RSA public key operation.
- *
- * \param ctx The initialized RSA context to use.
- * \param input The input buffer. This must be a readable buffer
- * of length \c ctx->len Bytes. For example, \c 256 Bytes
- * for an 2048-bit RSA modulus.
- * \param output The output buffer. This must be a writable buffer
- * of length \c ctx->len Bytes. For example, \c 256 Bytes
- * for an 2048-bit RSA modulus.
- *
- * \note This function does not handle message padding.
- *
- * \note Make sure to set \p input[0] = 0 or ensure that
- * input is smaller than \p N.
- *
- * \return \c 0 on success.
- * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
- */
- int mbedtls_rsa_public( mbedtls_rsa_context *ctx,
- const unsigned char *input,
- unsigned char *output );
- /**
- * \brief This function performs an RSA private key operation.
- *
- * \note Blinding is used if and only if a PRNG is provided.
- *
- * \note If blinding is used, both the base of exponentation
- * and the exponent are blinded, providing protection
- * against some side-channel attacks.
- *
- * \warning It is deprecated and a security risk to not provide
- * a PRNG here and thereby prevent the use of blinding.
- * Future versions of the library may enforce the presence
- * of a PRNG.
- *
- * \param ctx The initialized RSA context to use.
- * \param f_rng The RNG function, used for blinding. It is discouraged
- * and deprecated to pass \c NULL here, in which case
- * blinding will be omitted.
- * \param p_rng The RNG context to pass to \p f_rng. This may be \c NULL
- * if \p f_rng is \c NULL or if \p f_rng doesn't need a context.
- * \param input The input buffer. This must be a readable buffer
- * of length \c ctx->len Bytes. For example, \c 256 Bytes
- * for an 2048-bit RSA modulus.
- * \param output The output buffer. This must be a writable buffer
- * of length \c ctx->len Bytes. For example, \c 256 Bytes
- * for an 2048-bit RSA modulus.
- *
- * \return \c 0 on success.
- * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
- *
- */
- int mbedtls_rsa_private( mbedtls_rsa_context *ctx,
- int (*f_rng)(void *, unsigned char *, size_t),
- void *p_rng,
- const unsigned char *input,
- unsigned char *output );
- /**
- * \brief This function adds the message padding, then performs an RSA
- * operation.
- *
- * It is the generic wrapper for performing a PKCS#1 encryption
- * operation using the \p mode from the context.
- *
- * \deprecated It is deprecated and discouraged to call this function
- * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
- * are likely to remove the \p mode argument and have it
- * implicitly set to #MBEDTLS_RSA_PUBLIC.
- *
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
- * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
- *
- * \param ctx The initialized RSA context to use.
- * \param f_rng The RNG to use. It is mandatory for PKCS#1 v2.1 padding
- * encoding, and for PKCS#1 v1.5 padding encoding when used
- * with \p mode set to #MBEDTLS_RSA_PUBLIC. For PKCS#1 v1.5
- * padding encoding and \p mode set to #MBEDTLS_RSA_PRIVATE,
- * it is used for blinding and should be provided in this
- * case; see mbedtls_rsa_private() for more.
- * \param p_rng The RNG context to be passed to \p f_rng. May be
- * \c NULL if \p f_rng is \c NULL or if \p f_rng doesn't
- * need a context argument.
- * \param mode The mode of operation. This must be either
- * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
- * \param ilen The length of the plaintext in Bytes.
- * \param input The input data to encrypt. This must be a readable
- * buffer of size \p ilen Bytes. This must not be \c NULL.
- * \param output The output buffer. This must be a writable buffer
- * of length \c ctx->len Bytes. For example, \c 256 Bytes
- * for an 2048-bit RSA modulus.
- *
- * \return \c 0 on success.
- * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
- */
- int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx,
- int (*f_rng)(void *, unsigned char *, size_t),
- void *p_rng,
- int mode, size_t ilen,
- const unsigned char *input,
- unsigned char *output );
- /**
- * \brief This function performs a PKCS#1 v1.5 encryption operation
- * (RSAES-PKCS1-v1_5-ENCRYPT).
- *
- * \deprecated It is deprecated and discouraged to call this function
- * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
- * are likely to remove the \p mode argument and have it
- * implicitly set to #MBEDTLS_RSA_PUBLIC.
- *
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
- * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
- *
- * \param ctx The initialized RSA context to use.
- * \param f_rng The RNG function to use. It is needed for padding generation
- * if \p mode is #MBEDTLS_RSA_PUBLIC. If \p mode is
- * #MBEDTLS_RSA_PRIVATE (discouraged), it is used for
- * blinding and should be provided; see mbedtls_rsa_private().
- * \param p_rng The RNG context to be passed to \p f_rng. This may
- * be \c NULL if \p f_rng is \c NULL or if \p f_rng
- * doesn't need a context argument.
- * \param mode The mode of operation. This must be either
- * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
- * \param ilen The length of the plaintext in Bytes.
- * \param input The input data to encrypt. This must be a readable
- * buffer of size \p ilen Bytes. This must not be \c NULL.
- * \param output The output buffer. This must be a writable buffer
- * of length \c ctx->len Bytes. For example, \c 256 Bytes
- * for an 2048-bit RSA modulus.
- *
- * \return \c 0 on success.
- * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
- */
- int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx,
- int (*f_rng)(void *, unsigned char *, size_t),
- void *p_rng,
- int mode, size_t ilen,
- const unsigned char *input,
- unsigned char *output );
- /**
- * \brief This function performs a PKCS#1 v2.1 OAEP encryption
- * operation (RSAES-OAEP-ENCRYPT).
- *
- * \note The output buffer must be as large as the size
- * of ctx->N. For example, 128 Bytes if RSA-1024 is used.
- *
- * \deprecated It is deprecated and discouraged to call this function
- * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
- * are likely to remove the \p mode argument and have it
- * implicitly set to #MBEDTLS_RSA_PUBLIC.
- *
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
- * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
- *
- * \param ctx The initnialized RSA context to use.
- * \param f_rng The RNG function to use. This is needed for padding
- * generation and must be provided.
- * \param p_rng The RNG context to be passed to \p f_rng. This may
- * be \c NULL if \p f_rng doesn't need a context argument.
- * \param mode The mode of operation. This must be either
- * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
- * \param label The buffer holding the custom label to use.
- * This must be a readable buffer of length \p label_len
- * Bytes. It may be \c NULL if \p label_len is \c 0.
- * \param label_len The length of the label in Bytes.
- * \param ilen The length of the plaintext buffer \p input in Bytes.
- * \param input The input data to encrypt. This must be a readable
- * buffer of size \p ilen Bytes. This must not be \c NULL.
- * \param output The output buffer. This must be a writable buffer
- * of length \c ctx->len Bytes. For example, \c 256 Bytes
- * for an 2048-bit RSA modulus.
- *
- * \return \c 0 on success.
- * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
- */
- int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx,
- int (*f_rng)(void *, unsigned char *, size_t),
- void *p_rng,
- int mode,
- const unsigned char *label, size_t label_len,
- size_t ilen,
- const unsigned char *input,
- unsigned char *output );
- /**
- * \brief This function performs an RSA operation, then removes the
- * message padding.
- *
- * It is the generic wrapper for performing a PKCS#1 decryption
- * operation using the \p mode from the context.
- *
- * \note The output buffer length \c output_max_len should be
- * as large as the size \p ctx->len of \p ctx->N (for example,
- * 128 Bytes if RSA-1024 is used) to be able to hold an
- * arbitrary decrypted message. If it is not large enough to
- * hold the decryption of the particular ciphertext provided,
- * the function returns \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
- *
- * \deprecated It is deprecated and discouraged to call this function
- * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
- * are likely to remove the \p mode argument and have it
- * implicitly set to #MBEDTLS_RSA_PRIVATE.
- *
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
- * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
- *
- * \param ctx The initialized RSA context to use.
- * \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE,
- * this is used for blinding and should be provided; see
- * mbedtls_rsa_private() for more. If \p mode is
- * #MBEDTLS_RSA_PUBLIC, it is ignored.
- * \param p_rng The RNG context to be passed to \p f_rng. This may be
- * \c NULL if \p f_rng is \c NULL or doesn't need a context.
- * \param mode The mode of operation. This must be either
- * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
- * \param olen The address at which to store the length of
- * the plaintext. This must not be \c NULL.
- * \param input The ciphertext buffer. This must be a readable buffer
- * of length \c ctx->len Bytes. For example, \c 256 Bytes
- * for an 2048-bit RSA modulus.
- * \param output The buffer used to hold the plaintext. This must
- * be a writable buffer of length \p output_max_len Bytes.
- * \param output_max_len The length in Bytes of the output buffer \p output.
- *
- * \return \c 0 on success.
- * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
- */
- int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx,
- int (*f_rng)(void *, unsigned char *, size_t),
- void *p_rng,
- int mode, size_t *olen,
- const unsigned char *input,
- unsigned char *output,
- size_t output_max_len );
- /**
- * \brief This function performs a PKCS#1 v1.5 decryption
- * operation (RSAES-PKCS1-v1_5-DECRYPT).
- *
- * \note The output buffer length \c output_max_len should be
- * as large as the size \p ctx->len of \p ctx->N, for example,
- * 128 Bytes if RSA-1024 is used, to be able to hold an
- * arbitrary decrypted message. If it is not large enough to
- * hold the decryption of the particular ciphertext provided,
- * the function returns #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
- *
- * \deprecated It is deprecated and discouraged to call this function
- * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
- * are likely to remove the \p mode argument and have it
- * implicitly set to #MBEDTLS_RSA_PRIVATE.
- *
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
- * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
- *
- * \param ctx The initialized RSA context to use.
- * \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE,
- * this is used for blinding and should be provided; see
- * mbedtls_rsa_private() for more. If \p mode is
- * #MBEDTLS_RSA_PUBLIC, it is ignored.
- * \param p_rng The RNG context to be passed to \p f_rng. This may be
- * \c NULL if \p f_rng is \c NULL or doesn't need a context.
- * \param mode The mode of operation. This must be either
- * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
- * \param olen The address at which to store the length of
- * the plaintext. This must not be \c NULL.
- * \param input The ciphertext buffer. This must be a readable buffer
- * of length \c ctx->len Bytes. For example, \c 256 Bytes
- * for an 2048-bit RSA modulus.
- * \param output The buffer used to hold the plaintext. This must
- * be a writable buffer of length \p output_max_len Bytes.
- * \param output_max_len The length in Bytes of the output buffer \p output.
- *
- * \return \c 0 on success.
- * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
- *
- */
- int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx,
- int (*f_rng)(void *, unsigned char *, size_t),
- void *p_rng,
- int mode, size_t *olen,
- const unsigned char *input,
- unsigned char *output,
- size_t output_max_len );
- /**
- * \brief This function performs a PKCS#1 v2.1 OAEP decryption
- * operation (RSAES-OAEP-DECRYPT).
- *
- * \note The output buffer length \c output_max_len should be
- * as large as the size \p ctx->len of \p ctx->N, for
- * example, 128 Bytes if RSA-1024 is used, to be able to
- * hold an arbitrary decrypted message. If it is not
- * large enough to hold the decryption of the particular
- * ciphertext provided, the function returns
- * #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
- *
- * \deprecated It is deprecated and discouraged to call this function
- * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
- * are likely to remove the \p mode argument and have it
- * implicitly set to #MBEDTLS_RSA_PRIVATE.
- *
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
- * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
- *
- * \param ctx The initialized RSA context to use.
- * \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE,
- * this is used for blinding and should be provided; see
- * mbedtls_rsa_private() for more. If \p mode is
- * #MBEDTLS_RSA_PUBLIC, it is ignored.
- * \param p_rng The RNG context to be passed to \p f_rng. This may be
- * \c NULL if \p f_rng is \c NULL or doesn't need a context.
- * \param mode The mode of operation. This must be either
- * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
- * \param label The buffer holding the custom label to use.
- * This must be a readable buffer of length \p label_len
- * Bytes. It may be \c NULL if \p label_len is \c 0.
- * \param label_len The length of the label in Bytes.
- * \param olen The address at which to store the length of
- * the plaintext. This must not be \c NULL.
- * \param input The ciphertext buffer. This must be a readable buffer
- * of length \c ctx->len Bytes. For example, \c 256 Bytes
- * for an 2048-bit RSA modulus.
- * \param output The buffer used to hold the plaintext. This must
- * be a writable buffer of length \p output_max_len Bytes.
- * \param output_max_len The length in Bytes of the output buffer \p output.
- *
- * \return \c 0 on success.
- * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
- */
- int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx,
- int (*f_rng)(void *, unsigned char *, size_t),
- void *p_rng,
- int mode,
- const unsigned char *label, size_t label_len,
- size_t *olen,
- const unsigned char *input,
- unsigned char *output,
- size_t output_max_len );
- /**
- * \brief This function performs a private RSA operation to sign
- * a message digest using PKCS#1.
- *
- * It is the generic wrapper for performing a PKCS#1
- * signature using the \p mode from the context.
- *
- * \note The \p sig buffer must be as large as the size
- * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
- *
- * \note For PKCS#1 v2.1 encoding, see comments on
- * mbedtls_rsa_rsassa_pss_sign() for details on
- * \p md_alg and \p hash_id.
- *
- * \deprecated It is deprecated and discouraged to call this function
- * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
- * are likely to remove the \p mode argument and have it
- * implicitly set to #MBEDTLS_RSA_PRIVATE.
- *
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
- * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
- *
- * \param ctx The initialized RSA context to use.
- * \param f_rng The RNG function to use. If the padding mode is PKCS#1 v2.1,
- * this must be provided. If the padding mode is PKCS#1 v1.5 and
- * \p mode is #MBEDTLS_RSA_PRIVATE, it is used for blinding
- * and should be provided; see mbedtls_rsa_private() for more
- * more. It is ignored otherwise.
- * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL
- * if \p f_rng is \c NULL or doesn't need a context argument.
- * \param mode The mode of operation. This must be either
- * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
- * \param md_alg The message-digest algorithm used to hash the original data.
- * Use #MBEDTLS_MD_NONE for signing raw data.
- * \param hashlen The length of the message digest.
- * Ths is only used if \p md_alg is #MBEDTLS_MD_NONE.
- * \param hash The buffer holding the message digest or raw data.
- * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
- * buffer of length \p hashlen Bytes. If \p md_alg is not
- * #MBEDTLS_MD_NONE, it must be a readable buffer of length
- * the size of the hash corresponding to \p md_alg.
- * \param sig The buffer to hold the signature. This must be a writable
- * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
- * for an 2048-bit RSA modulus. A buffer length of
- * #MBEDTLS_MPI_MAX_SIZE is always safe.
- *
- * \return \c 0 if the signing operation was successful.
- * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
- */
- int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx,
- int (*f_rng)(void *, unsigned char *, size_t),
- void *p_rng,
- int mode,
- mbedtls_md_type_t md_alg,
- unsigned int hashlen,
- const unsigned char *hash,
- unsigned char *sig );
- /**
- * \brief This function performs a PKCS#1 v1.5 signature
- * operation (RSASSA-PKCS1-v1_5-SIGN).
- *
- * \deprecated It is deprecated and discouraged to call this function
- * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
- * are likely to remove the \p mode argument and have it
- * implicitly set to #MBEDTLS_RSA_PRIVATE.
- *
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
- * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
- *
- * \param ctx The initialized RSA context to use.
- * \param f_rng The RNG function. If \p mode is #MBEDTLS_RSA_PRIVATE,
- * this is used for blinding and should be provided; see
- * mbedtls_rsa_private() for more. If \p mode is
- * #MBEDTLS_RSA_PUBLIC, it is ignored.
- * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL
- * if \p f_rng is \c NULL or doesn't need a context argument.
- * \param mode The mode of operation. This must be either
- * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
- * \param md_alg The message-digest algorithm used to hash the original data.
- * Use #MBEDTLS_MD_NONE for signing raw data.
- * \param hashlen The length of the message digest.
- * Ths is only used if \p md_alg is #MBEDTLS_MD_NONE.
- * \param hash The buffer holding the message digest or raw data.
- * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
- * buffer of length \p hashlen Bytes. If \p md_alg is not
- * #MBEDTLS_MD_NONE, it must be a readable buffer of length
- * the size of the hash corresponding to \p md_alg.
- * \param sig The buffer to hold the signature. This must be a writable
- * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
- * for an 2048-bit RSA modulus. A buffer length of
- * #MBEDTLS_MPI_MAX_SIZE is always safe.
- *
- * \return \c 0 if the signing operation was successful.
- * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
- */
- int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx,
- int (*f_rng)(void *, unsigned char *, size_t),
- void *p_rng,
- int mode,
- mbedtls_md_type_t md_alg,
- unsigned int hashlen,
- const unsigned char *hash,
- unsigned char *sig );
- /**
- * \brief This function performs a PKCS#1 v2.1 PSS signature
- * operation (RSASSA-PSS-SIGN).
- *
- * \note The \p hash_id in the RSA context is the one used for the
- * encoding. \p md_alg in the function call is the type of hash
- * that is encoded. According to <em>RFC-3447: Public-Key
- * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
- * Specifications</em> it is advised to keep both hashes the
- * same.
- *
- * \note This function always uses the maximum possible salt size,
- * up to the length of the payload hash. This choice of salt
- * size complies with FIPS 186-4 §5.5 (e) and RFC 8017 (PKCS#1
- * v2.2) §9.1.1 step 3. Furthermore this function enforces a
- * minimum salt size which is the hash size minus 2 bytes. If
- * this minimum size is too large given the key size (the salt
- * size, plus the hash size, plus 2 bytes must be no more than
- * the key size in bytes), this function returns
- * #MBEDTLS_ERR_RSA_BAD_INPUT_DATA.
- *
- * \deprecated It is deprecated and discouraged to call this function
- * in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
- * are likely to remove the \p mode argument and have it
- * implicitly set to #MBEDTLS_RSA_PRIVATE.
- *
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
- * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
- *
- * \param ctx The initialized RSA context to use.
- * \param f_rng The RNG function. It must not be \c NULL.
- * \param p_rng The RNG context to be passed to \p f_rng. This may be \c NULL
- * if \p f_rng doesn't need a context argument.
- * \param mode The mode of operation. This must be either
- * #MBEDTLS_RSA_PRIVATE or #MBEDTLS_RSA_PUBLIC (deprecated).
- * \param md_alg The message-digest algorithm used to hash the original data.
- * Use #MBEDTLS_MD_NONE for signing raw data.
- * \param hashlen The length of the message digest.
- * Ths is only used if \p md_alg is #MBEDTLS_MD_NONE.
- * \param hash The buffer holding the message digest or raw data.
- * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
- * buffer of length \p hashlen Bytes. If \p md_alg is not
- * #MBEDTLS_MD_NONE, it must be a readable buffer of length
- * the size of the hash corresponding to \p md_alg.
- * \param sig The buffer to hold the signature. This must be a writable
- * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
- * for an 2048-bit RSA modulus. A buffer length of
- * #MBEDTLS_MPI_MAX_SIZE is always safe.
- *
- * \return \c 0 if the signing operation was successful.
- * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
- */
- int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx,
- int (*f_rng)(void *, unsigned char *, size_t),
- void *p_rng,
- int mode,
- mbedtls_md_type_t md_alg,
- unsigned int hashlen,
- const unsigned char *hash,
- unsigned char *sig );
- /**
- * \brief This function performs a public RSA operation and checks
- * the message digest.
- *
- * This is the generic wrapper for performing a PKCS#1
- * verification using the mode from the context.
- *
- * \note For PKCS#1 v2.1 encoding, see comments on
- * mbedtls_rsa_rsassa_pss_verify() about \p md_alg and
- * \p hash_id.
- *
- * \deprecated It is deprecated and discouraged to call this function
- * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
- * are likely to remove the \p mode argument and have it
- * set to #MBEDTLS_RSA_PUBLIC.
- *
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
- * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
- *
- * \param ctx The initialized RSA public key context to use.
- * \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE,
- * this is used for blinding and should be provided; see
- * mbedtls_rsa_private() for more. Otherwise, it is ignored.
- * \param p_rng The RNG context to be passed to \p f_rng. This may be
- * \c NULL if \p f_rng is \c NULL or doesn't need a context.
- * \param mode The mode of operation. This must be either
- * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
- * \param md_alg The message-digest algorithm used to hash the original data.
- * Use #MBEDTLS_MD_NONE for signing raw data.
- * \param hashlen The length of the message digest.
- * This is only used if \p md_alg is #MBEDTLS_MD_NONE.
- * \param hash The buffer holding the message digest or raw data.
- * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
- * buffer of length \p hashlen Bytes. If \p md_alg is not
- * #MBEDTLS_MD_NONE, it must be a readable buffer of length
- * the size of the hash corresponding to \p md_alg.
- * \param sig The buffer holding the signature. This must be a readable
- * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
- * for an 2048-bit RSA modulus.
- *
- * \return \c 0 if the verify operation was successful.
- * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
- */
- int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx,
- int (*f_rng)(void *, unsigned char *, size_t),
- void *p_rng,
- int mode,
- mbedtls_md_type_t md_alg,
- unsigned int hashlen,
- const unsigned char *hash,
- const unsigned char *sig );
- /**
- * \brief This function performs a PKCS#1 v1.5 verification
- * operation (RSASSA-PKCS1-v1_5-VERIFY).
- *
- * \deprecated It is deprecated and discouraged to call this function
- * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
- * are likely to remove the \p mode argument and have it
- * set to #MBEDTLS_RSA_PUBLIC.
- *
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
- * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
- *
- * \param ctx The initialized RSA public key context to use.
- * \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE,
- * this is used for blinding and should be provided; see
- * mbedtls_rsa_private() for more. Otherwise, it is ignored.
- * \param p_rng The RNG context to be passed to \p f_rng. This may be
- * \c NULL if \p f_rng is \c NULL or doesn't need a context.
- * \param mode The mode of operation. This must be either
- * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
- * \param md_alg The message-digest algorithm used to hash the original data.
- * Use #MBEDTLS_MD_NONE for signing raw data.
- * \param hashlen The length of the message digest.
- * This is only used if \p md_alg is #MBEDTLS_MD_NONE.
- * \param hash The buffer holding the message digest or raw data.
- * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
- * buffer of length \p hashlen Bytes. If \p md_alg is not
- * #MBEDTLS_MD_NONE, it must be a readable buffer of length
- * the size of the hash corresponding to \p md_alg.
- * \param sig The buffer holding the signature. This must be a readable
- * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
- * for an 2048-bit RSA modulus.
- *
- * \return \c 0 if the verify operation was successful.
- * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
- */
- int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx,
- int (*f_rng)(void *, unsigned char *, size_t),
- void *p_rng,
- int mode,
- mbedtls_md_type_t md_alg,
- unsigned int hashlen,
- const unsigned char *hash,
- const unsigned char *sig );
- /**
- * \brief This function performs a PKCS#1 v2.1 PSS verification
- * operation (RSASSA-PSS-VERIFY).
- *
- * The hash function for the MGF mask generating function
- * is that specified in the RSA context.
- *
- * \note The \p hash_id in the RSA context is the one used for the
- * verification. \p md_alg in the function call is the type of
- * hash that is verified. According to <em>RFC-3447: Public-Key
- * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
- * Specifications</em> it is advised to keep both hashes the
- * same. If \p hash_id in the RSA context is unset,
- * the \p md_alg from the function call is used.
- *
- * \deprecated It is deprecated and discouraged to call this function
- * in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
- * are likely to remove the \p mode argument and have it
- * implicitly set to #MBEDTLS_RSA_PUBLIC.
- *
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
- * return #MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED.
- *
- * \param ctx The initialized RSA public key context to use.
- * \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE,
- * this is used for blinding and should be provided; see
- * mbedtls_rsa_private() for more. Otherwise, it is ignored.
- * \param p_rng The RNG context to be passed to \p f_rng. This may be
- * \c NULL if \p f_rng is \c NULL or doesn't need a context.
- * \param mode The mode of operation. This must be either
- * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE (deprecated).
- * \param md_alg The message-digest algorithm used to hash the original data.
- * Use #MBEDTLS_MD_NONE for signing raw data.
- * \param hashlen The length of the message digest.
- * This is only used if \p md_alg is #MBEDTLS_MD_NONE.
- * \param hash The buffer holding the message digest or raw data.
- * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
- * buffer of length \p hashlen Bytes. If \p md_alg is not
- * #MBEDTLS_MD_NONE, it must be a readable buffer of length
- * the size of the hash corresponding to \p md_alg.
- * \param sig The buffer holding the signature. This must be a readable
- * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
- * for an 2048-bit RSA modulus.
- *
- * \return \c 0 if the verify operation was successful.
- * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
- */
- int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx,
- int (*f_rng)(void *, unsigned char *, size_t),
- void *p_rng,
- int mode,
- mbedtls_md_type_t md_alg,
- unsigned int hashlen,
- const unsigned char *hash,
- const unsigned char *sig );
- /**
- * \brief This function performs a PKCS#1 v2.1 PSS verification
- * operation (RSASSA-PSS-VERIFY).
- *
- * The hash function for the MGF mask generating function
- * is that specified in \p mgf1_hash_id.
- *
- * \note The \p sig buffer must be as large as the size
- * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
- *
- * \note The \p hash_id in the RSA context is ignored.
- *
- * \param ctx The initialized RSA public key context to use.
- * \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE,
- * this is used for blinding and should be provided; see
- * mbedtls_rsa_private() for more. Otherwise, it is ignored.
- * \param p_rng The RNG context to be passed to \p f_rng. This may be
- * \c NULL if \p f_rng is \c NULL or doesn't need a context.
- * \param mode The mode of operation. This must be either
- * #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
- * \param md_alg The message-digest algorithm used to hash the original data.
- * Use #MBEDTLS_MD_NONE for signing raw data.
- * \param hashlen The length of the message digest.
- * This is only used if \p md_alg is #MBEDTLS_MD_NONE.
- * \param hash The buffer holding the message digest or raw data.
- * If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
- * buffer of length \p hashlen Bytes. If \p md_alg is not
- * #MBEDTLS_MD_NONE, it must be a readable buffer of length
- * the size of the hash corresponding to \p md_alg.
- * \param mgf1_hash_id The message digest used for mask generation.
- * \param expected_salt_len The length of the salt used in padding. Use
- * #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length.
- * \param sig The buffer holding the signature. This must be a readable
- * buffer of length \c ctx->len Bytes. For example, \c 256 Bytes
- * for an 2048-bit RSA modulus.
- *
- * \return \c 0 if the verify operation was successful.
- * \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
- */
- int mbedtls_rsa_rsassa_pss_verify_ext( mbedtls_rsa_context *ctx,
- int (*f_rng)(void *, unsigned char *, size_t),
- void *p_rng,
- int mode,
- mbedtls_md_type_t md_alg,
- unsigned int hashlen,
- const unsigned char *hash,
- mbedtls_md_type_t mgf1_hash_id,
- int expected_salt_len,
- const unsigned char *sig );
- /**
- * \brief This function copies the components of an RSA context.
- *
- * \param dst The destination context. This must be initialized.
- * \param src The source context. This must be initialized.
- *
- * \return \c 0 on success.
- * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure.
- */
- int mbedtls_rsa_copy( mbedtls_rsa_context *dst, const mbedtls_rsa_context *src );
- /**
- * \brief This function frees the components of an RSA key.
- *
- * \param ctx The RSA context to free. May be \c NULL, in which case
- * this function is a no-op. If it is not \c NULL, it must
- * point to an initialized RSA context.
- */
- void mbedtls_rsa_free( mbedtls_rsa_context *ctx );
- #if defined(MBEDTLS_SELF_TEST)
- /**
- * \brief The RSA checkup routine.
- *
- * \return \c 0 on success.
- * \return \c 1 on failure.
- */
- int mbedtls_rsa_self_test( int verbose );
- #endif /* MBEDTLS_SELF_TEST */
- #ifdef __cplusplus
- }
- #endif
- #endif /* rsa.h */
|