yuzu-emu/mbedtls
1
0
Fork 0
mirror of https://github.com/yuzu-emu/mbedtls.git synced 2024-12-02 23:54:21 +01:00
Code Issues Packages Projects Releases Wiki Activity
68b4d58bd8
mbedtls/include/mbedtls/rsa.h
Hanno Becker 68b4d58bd8 Remove PRNG argument from mbedtls_rsa_deduce_moduli 
It is not necessary to pass a CSPRNG to `mbedtls_rsa_deduce_moduli`, as there
exist well-working static strategies, and even if a PRNG is preferred, a
non-secure one would be sufficient.

Further, the implementation is changed to use a static strategy for the choice
of candidates which according to some benchmarks even performs better than the
previous one using random candidate choices.
2017-10-10 16:39:10 +01:00

1096 lines
47 KiB
C
Raw Blame History

/**
* \file rsa.h
*
* \brief The RSA public-key cryptosystem
*
* Copyright (C) 2006-2015, ARM Limited, 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 library's validity check. */
#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. */
#define MBEDTLS_ERR_RSA_EXPORT_UNSUPPORTED -0x4500 /**< The requested parameter export is not possible/allowed. */
/*
* RSA constants
*/
#define MBEDTLS_RSA_PUBLIC 0
#define MBEDTLS_RSA_PRIVATE 1
#define MBEDTLS_RSA_PKCS_V15 0
#define MBEDTLS_RSA_PKCS_V21 1
#define MBEDTLS_RSA_SIGN 1
#define MBEDTLS_RSA_CRYPT 2
#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.
*/
#if defined(MBEDTLS_RSA_C)
#ifdef __cplusplus
extern "C" {
#endif
/**
* Helper functions for RSA-related operations on MPI's.
*/
/**
* \brief Compute RSA prime moduli P, Q from public modulus N=PQ
* and a pair of private and public key.
*
* \note This is a 'static' helper function not operating on
* an RSA context. Alternative implementations need not
* overwrite it.
*
* \param N RSA modulus N = PQ, with P, Q to be found
* \param D RSA private exponent
* \param E RSA public exponent
* \param P Pointer to MPI holding first prime factor of N on success
* \param Q Pointer to MPI holding second prime factor of N on success
*
* \return
* - 0 if successful. In this case, P and Q constitute a
* factorization of N.
* - A non-zero error code otherwise.
*
* \note It is neither checked that P, Q are prime nor that
* D, E are modular inverses wrt. P-1 and Q-1. For that,
* use the helper function \c mbedtls_rsa_validate_params.
*
*/
int mbedtls_rsa_deduce_primes( mbedtls_mpi const *N, mbedtls_mpi const *D,
mbedtls_mpi const *E,
mbedtls_mpi *P, mbedtls_mpi *Q );
/**
* \brief Compute RSA private exponent from
* prime moduli and public key.
*
* \note This is a 'static' helper function not operating on
* an RSA context. Alternative implementations need not
* overwrite it.
*
* \param P First prime factor of RSA modulus
* \param Q Second prime factor of RSA modulus
* \param E RSA public exponent
* \param D Pointer to MPI holding the private exponent on success.
*
* \return
* - 0 if successful. In this case, D is set to a simultaneous
* modular inverse of E modulo both P-1 and Q-1.
* - A non-zero error code otherwise.
*
* \note This function does not check whether P and Q are primes.
*
*/
int mbedtls_rsa_deduce_private_exponent( mbedtls_mpi const *P,
mbedtls_mpi const *Q,
mbedtls_mpi const *E,
mbedtls_mpi *D );
/**
* \brief Generate RSA-CRT parameters
*
* \note This is a 'static' helper function not operating on
* an RSA context. Alternative implementations need not
* overwrite it.
*
* \param P First prime factor of N
* \param Q Second prime factor of N
* \param D RSA private exponent
* \param DP Output variable for D modulo P-1
* \param DQ Output variable for D modulo Q-1
* \param QP Output variable for the modular inverse of Q modulo P.
*
* \return 0 on success, non-zero error code otherwise.
*
* \note This function does not check whether P, Q are
* prime and whether D is a valid private exponent.
*
*/
int mbedtls_rsa_deduce_crt( const mbedtls_mpi *P, const mbedtls_mpi *Q,
const mbedtls_mpi *D, mbedtls_mpi *DP,
mbedtls_mpi *DQ, mbedtls_mpi *QP );
/**
* \brief Check validity of core RSA parameters
*
* \note This is a 'static' helper function not operating on
* an RSA context. Alternative implementations need not
* overwrite it.
*
* \param N RSA modulus N = PQ
* \param P First prime factor of N
* \param Q Second prime factor of N
* \param D RSA private exponent
* \param E RSA public exponent
* \param f_rng PRNG to be used for primality check, or NULL
* \param p_rng PRNG context for f_rng, or NULL
*
* \return
* - 0 if the following conditions are satisfied
* if all relevant parameters are provided:
* - P prime if f_rng != NULL
* - Q prime if f_rng != NULL
* - 1 < N = PQ
* - 1 < D, E < N
* - D and E are modular inverses modulo P-1 and Q-1
* - A non-zero error code otherwise.
*
* \note The function can be used with a restricted set of arguments
* to perform specific checks only. E.g., calling it with
* (-,P,-,-,-) and a PRNG amounts to a primality check for P.
*/
int mbedtls_rsa_validate_params( const mbedtls_mpi *N, const mbedtls_mpi *P,
const mbedtls_mpi *Q, const mbedtls_mpi *D,
const mbedtls_mpi *E,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng );
/**
* \brief Check validity of RSA CRT parameters
*
* \note This is a 'static' helper function not operating on
* an RSA context. Alternative implementations need not
* overwrite it.
*
* \param P First prime factor of RSA modulus
* \param Q Second prime factor of RSA modulus
* \param D RSA private exponent
* \param DP MPI to check for D modulo P-1
* \param DQ MPI to check for D modulo P-1
* \param QP MPI to check for the modular inverse of Q modulo P.
*
* \return
* - 0 if the following conditions are satisfied:
* - D = DP mod P-1 if P, D, DP != NULL
* - Q = DQ mod P-1 if P, D, DQ != NULL
* - QP = Q^-1 mod P if P, Q, QP != NULL
* - \c MBEDTLS_ERR_RSA_KEY_CHECK_FAILED if check failed,
* potentially including \c MBEDTLS_ERR_MPI_XXX if some
* MPI calculations failed.
* - \c MBEDTLS_ERR_RSA_BAD_INPUT_DATA if insufficient
* data was provided to check DP, DQ or QP.
*
* \note The function can be used with a restricted set of arguments
* to perform specific checks only. E.g., calling it with the
* parameters (P, -, D, DP, -, -) will check DP = D mod P-1.
*/
int mbedtls_rsa_validate_crt( const mbedtls_mpi *P, const mbedtls_mpi *Q,
const mbedtls_mpi *D, const mbedtls_mpi *DP,
const mbedtls_mpi *DQ, const mbedtls_mpi *QP );
/**
* Implementation of RSA interface
*/
#if !defined(MBEDTLS_RSA_ALT)
/**
* \brief RSA context structure
*
* \note Direct manipulation of the members of this structure
* is deprecated and will no longer be supported starting
* from the next major release. All manipulation should instead
* be done through the public interface functions.
*
*/
typedef struct
{
int ver; /*!< always 0 */
size_t len; /*!< size(N) in chars */
mbedtls_mpi N; /*!< public modulus */
mbedtls_mpi E; /*!< public exponent */
mbedtls_mpi D; /*!< private exponent */
mbedtls_mpi P; /*!< 1st prime factor */
mbedtls_mpi Q; /*!< 2nd prime factor */
#if !defined(MBEDTLS_RSA_NO_CRT)
mbedtls_mpi DP; /*!< D % (P - 1) */
mbedtls_mpi DQ; /*!< D % (Q - 1) */
mbedtls_mpi QP; /*!< 1 / (Q % P) */
#endif /* MBEDTLS_RSA_NO_CRT */
mbedtls_mpi RN; /*!< cached R^2 mod N */
#if !defined(MBEDTLS_RSA_NO_CRT)
mbedtls_mpi RP; /*!< cached R^2 mod P */
mbedtls_mpi RQ; /*!< cached R^2 mod Q */
#endif /* MBEDTLS_RSA_NO_CRT */
mbedtls_mpi Vi; /*!< cached blinding value */
mbedtls_mpi Vf; /*!< cached un-blinding value */
int padding; /*!< \c MBEDTLS_RSA_PKCS_V15 for 1.5 padding and
\c MBEDTLS_RSA_PKCS_v21 for OAEP/PSS */
int hash_id; /*!< Hash identifier of mbedtls_md_type_t as
specified in the mbedtls_md.h header file
for the EME-OAEP and EMSA-PSS
encoding */
#if defined(MBEDTLS_THREADING_C)
mbedtls_threading_mutex_t mutex; /*!< Thread-safety mutex */
#endif
}
mbedtls_rsa_context;
#else
#include "rsa_alt.h"
#endif /* MBEDTLS_RSA_ALT */
/**
* \brief Initialize an RSA context
*
* Note: Set padding to \c MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP
* encryption scheme and the RSASSA-PSS signature scheme.
*
* \param ctx RSA context to be initialized
* \param padding \c MBEDTLS_RSA_PKCS_V15 or \c MBEDTLS_RSA_PKCS_V21
* \param hash_id \c MBEDTLS_RSA_PKCS_V21 hash identifier
*
* \note The hash_id parameter is actually ignored
* when using \c MBEDTLS_RSA_PKCS_V15 padding.
*
* \note 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's merely
* a default value, which can be overriden by calling specific
* rsa_rsaes_xxx or rsa_rsassa_xxx functions.
*
* \note The chosen hash is always used for OEAP encryption.
* For PSS signatures, it's always used for making signatures,
* but can be overriden (and always is, if set to
* \c MBEDTLS_MD_NONE) for verifying them.
*/
void mbedtls_rsa_init( mbedtls_rsa_context *ctx,
int padding,
int hash_id);
/**
* \brief Import a set of core parameters into an RSA context
*
* \param ctx Initialized RSA context to store parameters
* \param N RSA modulus, or NULL
* \param P First prime factor of N, or NULL
* \param Q Second prime factor of N, or NULL
* \param D Private exponent, or NULL
* \param E Public exponent, or NULL
*
* \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 \c mbedtls_rsa_complete which will check
* and complete the provided information to a ready-for-use
* public or private RSA key.
*
* \note The imported parameters are copied and need not be preserved
* for the lifetime of the RSA context being set up.
*
* \return 0 if successful, 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 Import core RSA parameters in raw big-endian
* binary format into an RSA context
*
* \param ctx Initialized RSA context to store parameters
* \param N RSA modulus, or NULL
* \param N_len Byte length of N, ignored if N == NULL
* \param P First prime factor of N, or NULL
* \param P_len Byte length of P, ignored if P == NULL
* \param Q Second prime factor of N, or NULL
* \param Q_len Byte length of Q, ignored if Q == NULL
* \param D Private exponent, or NULL
* \param D_len Byte length of D, ignored if D == NULL
* \param E Public exponent, or NULL
* \param E_len Byte length of E, ignored if E == NULL
*
* \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 \c mbedtls_rsa_complete which will check
* and complete the provided information to a ready-for-use
* public or private RSA key.
*
* \note The imported parameters are copied and need not be preserved
* for the lifetime of the RSA context being set up.
*
* \return 0 if successful, 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 Attempt to complete an RSA context from
* a set of imported core parameters.
*
* \param ctx Initialized RSA context to store parameters
* \param f_rng RNG function, or NULL
* \param p_rng RNG parameter, or NULL
*
* \note
* - To setup an RSA public key, precisely N and E
* must have been imported.
*
* - To setup an RSA private key, enough information must be
* present for the other parameters to be derivable.
*
* The default implementation supports the following:
* - Derive P, Q from N, D, E
* - Derive N, D from P, Q, E.
*
* - Alternative implementations need not support these
* and may return \c MBEDTLS_ERR_RSA_BAD_INPUT_DATA instead.
*
* \note The PRNG is used for the probabilistic algorithm
* used in the derivation of P, Q from N, D, E. If it
* not present, a deterministic heuristic is used.
*
* \return
* - 0 if successful. In this case, it is guaranteed
* the functions \c mbedtls_rsa_check_pubkey resp.
* \c mbedtls_rsa_check_privkey pass in case of a
* public resp. private key.
* - \c MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted
* derivations failed.
*
* \warning Implementations are *not* obliged to perform exhaustive
* validation of the imported parameters!
* In particular, parameters that are not needed by the
* implementation may be silently discarded and left unchecked.
* If the user mistrusts the given key material, he should
* employ other means for verification like the helper functions
* \c mbedtls_rsa_validate_params, \c mbedtls_rsa_validate_crt.
*
*/
int mbedtls_rsa_complete( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
void *p_rng );
/**
* \brief Export core parameters of an RSA key
*
* \param ctx Initialized RSA context
* \param N MPI to hold the RSA modulus, or NULL
* \param P MPI to hold the first prime factor of N, or NULL
* \param Q MPI to hold the second prime factor of N, or NULL
* \param D MPI to hold the private exponent, or NULL
* \param E MPI to hold the public exponent, or NULL
*
* \return
* - 0 if successful. In this case, the non-NULL buffers
* pointed to by N, P, Q, D, E are fully written, with
* additional unused space filled leading by 0-bytes.
* - Non-zero return code otherwise. In particular, if
* exporting the requested parameters
* cannot be done because of a lack of functionality
* or because of security policies, the error code
* \c MBEDTLS_ERR_RSA_EXPORT_UNSUPPORTED is returned.
* In this case, the RSA context stays intact and can
* be continued to be used.
*
* \note Reasons for returning \c MBEDTLS_ERR_RSA_EXPORT_UNSUPPORTED
* would be the following: Firstly, it might be that an
* alternative RSA implementation is in use which stores
* the key externally, and which either cannot or should not
* export it into RAM. Alternatively, an implementation
* (regardless of SW or HW) might not support deducing e.g.
* P, Q from N, D, E if the former are not part of the
* implementation.
*
*/
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 Export core parameters of an RSA key
* in raw big-endian binary format
*
* \param ctx Initialized RSA context
* \param N Byte array to store the RSA modulus, or NULL
* \param N_len Size of buffer for modulus
* \param P Byte array to hold the first prime factor of N, or NULL
* \param P_len Size of buffer for first prime factor
* \param Q Byte array to hold the second prime factor of N, or NULL
* \param Q_len Size of buffer for second prime factor
* \param D Byte array to hold the private exponent, or NULL
* \param D_len Size of buffer for private exponent
* \param E Byte array to hold the public exponent, or NULL
* \param E_len Size of buffer for public exponent
*
* \note The length fields are ignored if the corresponding
* buffer pointers are NULL.
*
* \return
* - 0 if successful. In this case, the non-NULL buffers
* pointed to by N, P, Q, D, E are fully written, with
* additional unused space filled leading by 0-bytes.
* - Non-zero return code otherwise. In particular, if
* exporting the requested parameters
* cannot be done because of a lack of functionality
* or because of security policies, the error code
* \c MBEDTLS_ERR_RSA_EXPORT_UNSUPPORTED is returned.
* In this case, the RSA context stays intact and can
* be continued to be used.
*
* \note Reasons for returning \c MBEDTLS_ERR_RSA_EXPORT_UNSUPPORTED
* would be the following: Firstly, it might be that an
* alternative RSA implementation is in use which stores
* the key externally, and which either cannot or should not
* export it into RAM. Alternatively, an implementation
* (regardless of SW or HW) might not support deducing e.g.
* P, Q from N, D, E if the former are not part of the
* implementation.
*
*
*/
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 Export CRT parameters of a private RSA key
*
* \param ctx Initialized RSA context
* \param DP MPI to hold D modulo P-1, or NULL
* \param DQ MPI to hold D modulo Q-1, or NULL
* \param QP MPI to hold modular inverse of Q modulo P, or NULL
*
* \return 0 if successful, non-zero error code otherwise.
*
* \note Alternative RSA implementations not using CRT-parameters
* internally can implement this function using based on
* \c mbedtls_rsa_deduce_opt.
*
*/
int mbedtls_rsa_export_crt( const mbedtls_rsa_context *ctx,
mbedtls_mpi *DP, mbedtls_mpi *DQ, mbedtls_mpi *QP );
/**
* \brief Set padding for an already initialized RSA context
* See \c mbedtls_rsa_init() for details.
*
* \param ctx RSA context to be set
* \param padding \c MBEDTLS_RSA_PKCS_V15 or \c MBEDTLS_RSA_PKCS_V21
* \param hash_id \c MBEDTLS_RSA_PKCS_V21 hash identifier
*/
void mbedtls_rsa_set_padding( mbedtls_rsa_context *ctx, int padding,
int hash_id);
/**
* \brief Get length of RSA modulus in bytes
*
* \param ctx Initialized RSA context
*
* \return Length of RSA modulus, in bytes.
*
*/
size_t mbedtls_rsa_get_len( const mbedtls_rsa_context *ctx );
/**
* \brief Generate an RSA keypair
*
* \param ctx RSA context that will hold the key
* \param f_rng RNG function
* \param p_rng RNG parameter
* \param nbits size of the public key in bits
* \param exponent public exponent (e.g., 65537)
*
* \note mbedtls_rsa_init() must be called beforehand to setup
* the RSA context.
*
* \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
*/
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 Check if a context contains (at least) an RSA public key
*
* \param ctx RSA context to be checked
*
* \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code.
* On success, it is guaranteed that enough information is
* present to perform an RSA public key operation
* \c mbedtls_rsa_public.
*
*/
int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx );
/**
* \brief Check if a context contains an RSA private key
* and perform basic sanity checks.
*
* \param ctx RSA context to be checked
*
* \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code.
* On success, it is guaranteed that enough information is
* present to perform RSA private and public key operations.
*
* \warning This function is *not* obliged to perform an exhaustive
* sanity check what would guarantee the internal parameters
* to match and \c mbedtls_rsa_private and \c mbedtls_rsa_public
* to be mutually inverse to each other.
* The reason is that for minimal non-CRT implementations
* using only N, D, E, for example, checking the validity
* would be computationally expensive.
* Users mistrusting their key material should use other
* means for verification; see the documentation of
* \c mbedtls_rsa_complete.
*
*/
int mbedtls_rsa_check_privkey( const mbedtls_rsa_context *ctx );
/**
* \brief Check a public-private RSA key pair.
* Check each of the contexts, and make sure they match.
*
* \param pub RSA context holding the public key
* \param prv RSA context holding the private key
*
* \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
*/
int mbedtls_rsa_check_pub_priv( const mbedtls_rsa_context *pub,
const mbedtls_rsa_context *prv );
/**
* \brief Do an RSA public key operation
*
* \param ctx RSA context
* \param input input buffer
* \param output output buffer
*
* \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
*
* \note This function does NOT take care of message
* padding. Also, be sure to set input[0] = 0 or ensure that
* input is smaller than N.
*
* \note The input and output buffers must be large
* enough (eg. 128 bytes if RSA-1024 is used).
*/
int mbedtls_rsa_public( mbedtls_rsa_context *ctx,
const unsigned char *input,
unsigned char *output );
/**
* \brief Do an RSA private key operation
*
* \param ctx RSA context
* \param f_rng RNG function (Needed for blinding)
* \param p_rng RNG parameter
* \param input input buffer
* \param output output buffer
*
* \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
*
* \note The input and output buffers must be large
* enough (eg. 128 bytes if RSA-1024 is used).
*/
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 Generic wrapper to perform a PKCS#1 encryption using the
* mode from the context. Add the message padding, then do an
* RSA operation.
*
* \param ctx RSA context
* \param f_rng RNG function (Needed for padding and PKCS#1 v2.1 encoding
* and \c MBEDTLS_RSA_PRIVATE)
* \param p_rng RNG parameter
* \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
* \param ilen contains the plaintext length
* \param input buffer holding the data to be encrypted
* \param output buffer that will hold the ciphertext
*
* \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
*
* \note The output buffer must be as large as the size
* of ctx->N (eg. 128 bytes if RSA-1024 is used).
*/
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 Perform a PKCS#1 v1.5 encryption (RSAES-PKCS1-v1_5-ENCRYPT)
*
* \param ctx RSA context
* \param f_rng RNG function (Needed for padding and \c MBEDTLS_RSA_PRIVATE)
* \param p_rng RNG parameter
* \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
* \param ilen contains the plaintext length
* \param input buffer holding the data to be encrypted
* \param output buffer that will hold the ciphertext
*
* \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
*
* \note The output buffer must be as large as the size
* of ctx->N (eg. 128 bytes if RSA-1024 is used).
*/
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 Perform a PKCS#1 v2.1 OAEP encryption (RSAES-OAEP-ENCRYPT)
*
* \param ctx RSA context
* \param f_rng RNG function (Needed for padding and PKCS#1 v2.1 encoding
* and \c MBEDTLS_RSA_PRIVATE)
* \param p_rng RNG parameter
* \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
* \param label buffer holding the custom label to use
* \param label_len contains the label length
* \param ilen contains the plaintext length
* \param input buffer holding the data to be encrypted
* \param output buffer that will hold the ciphertext
*
* \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
*
* \note The output buffer must be as large as the size
* of ctx->N (eg. 128 bytes if RSA-1024 is used).
*/
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 Generic wrapper to perform a PKCS#1 decryption using the
* mode from the context. Do an RSA operation, then remove
* the message padding
*
* \param ctx RSA context
* \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
* \param p_rng RNG parameter
* \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
* \param olen will contain the plaintext length
* \param input buffer holding the encrypted data
* \param output buffer that will hold the plaintext
* \param output_max_len maximum length of the output buffer
*
* \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
*
* \note The output buffer length \c output_max_len should be
* as large as the size \c ctx->len of \c ctx->N (eg. 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 will return \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
*
* \note The input buffer must be as large as the size
* of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
*/
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 Perform a PKCS#1 v1.5 decryption (RSAES-PKCS1-v1_5-DECRYPT)
*
* \param ctx RSA context
* \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
* \param p_rng RNG parameter
* \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
* \param olen will contain the plaintext length
* \param input buffer holding the encrypted data
* \param output buffer that will hold the plaintext
* \param output_max_len maximum length of the output buffer
*
* \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
*
* \note The output buffer length \c output_max_len should be
* as large as the size \c ctx->len of \c ctx->N (eg. 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 will return \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
*
* \note The input buffer must be as large as the size
* of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
*/
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 Perform a PKCS#1 v2.1 OAEP decryption (RSAES-OAEP-DECRYPT)
*
* \param ctx RSA context
* \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
* \param p_rng RNG parameter
* \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
* \param label buffer holding the custom label to use
* \param label_len contains the label length
* \param olen will contain the plaintext length
* \param input buffer holding the encrypted data
* \param output buffer that will hold the plaintext
* \param output_max_len maximum length of the output buffer
*
* \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
*
* \note The output buffer length \c output_max_len should be
* as large as the size \c ctx->len of \c ctx->N (eg. 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 will return \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
*
* \note The input buffer must be as large as the size
* of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
*/
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 Generic wrapper to perform a PKCS#1 signature using the
* mode from the context. Do a private RSA operation to sign
* a message digest
*
* \param ctx RSA context
* \param f_rng RNG function (Needed for PKCS#1 v2.1 encoding and for
* \c MBEDTLS_RSA_PRIVATE)
* \param p_rng RNG parameter
* \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
* \param md_alg a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE for
* signing raw data)
* \param hashlen message digest length (for \c MBEDTLS_MD_NONE only)
* \param hash buffer holding the message digest
* \param sig buffer that will hold the ciphertext
*
* \return 0 if the signing operation was successful,
* or an \c MBEDTLS_ERR_RSA_XXX error code
*
* \note The \c sig buffer must be as large as the size
* of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
*
* \note In case of PKCS#1 v2.1 encoding, see comments on
* \note \c mbedtls_rsa_rsassa_pss_sign() for details on
* \c md_alg and \c hash_id.
*/
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 Perform a PKCS#1 v1.5 signature (RSASSA-PKCS1-v1_5-SIGN)
*
* \param ctx RSA context
* \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
* \param p_rng RNG parameter
* \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
* \param md_alg a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE
* for signing raw data)
* \param hashlen message digest length (for \c MBEDTLS_MD_NONE only)
* \param hash buffer holding the message digest
* \param sig buffer that will hold the ciphertext
*
* \return 0 if the signing operation was successful,
* or an \c MBEDTLS_ERR_RSA_XXX error code
*
* \note The \c sig buffer must be as large as the size
* of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
*/
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 Perform a PKCS#1 v2.1 PSS signature (RSASSA-PSS-SIGN)
*
* \param ctx RSA context
* \param f_rng RNG function (Needed for PKCS#1 v2.1 encoding and for
* \c MBEDTLS_RSA_PRIVATE)
* \param p_rng RNG parameter
* \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
* \param md_alg a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE
* for signing raw data)
* \param hashlen message digest length (for \c MBEDTLS_MD_NONE only)
* \param hash buffer holding the message digest
* \param sig buffer that will hold the ciphertext
*
* \return 0 if the signing operation was successful,
* or an \c MBEDTLS_ERR_RSA_XXX error code
*
* \note The \c sig buffer must be as large as the size
* of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
*
* \note The \c hash_id in the RSA context is the one used for the
* encoding. \c md_alg in the function call is the type of hash
* that is encoded. According to RFC 3447 it is advised to
* keep both hashes the same.
*/
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 Generic wrapper to perform a PKCS#1 verification using the
* mode from the context. Do a public RSA operation and check
* the message digest
*
* \param ctx points to an RSA public key
* \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
* \param p_rng RNG parameter
* \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
* \param md_alg a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE for signing raw data)
* \param hashlen message digest length (for \c MBEDTLS_MD_NONE only)
* \param hash buffer holding the message digest
* \param sig buffer holding the ciphertext
*
* \return 0 if the verify operation was successful,
* or an \c MBEDTLS_ERR_RSA_XXX error code
*
* \note The \c sig buffer must be as large as the size
* of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
*
* \note In case of PKCS#1 v2.1 encoding, see comments on
* \c mbedtls_rsa_rsassa_pss_verify() about md_alg and hash_id.
*/
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 Perform a PKCS#1 v1.5 verification (RSASSA-PKCS1-v1_5-VERIFY)
*
* \param ctx points to an RSA public key
* \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
* \param p_rng RNG parameter
* \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
* \param md_alg a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE
* for signing raw data)
* \param hashlen message digest length (for \c MBEDTLS_MD_NONE only)
* \param hash buffer holding the message digest
* \param sig buffer holding the ciphertext
*
* \return 0 if the verify operation was successful,
* or an \c MBEDTLS_ERR_RSA_XXX error code
*
* \note The \c sig buffer must be as large as the size
* of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
*/
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 Perform a PKCS#1 v2.1 PSS verification (RSASSA-PSS-VERIFY)
* (This is the "simple" version.)
*
* \param ctx points to an RSA public key
* \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
* \param p_rng RNG parameter
* \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
* \param md_alg a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE for signing raw data)
* \param hashlen message digest length (for \c MBEDTLS_MD_NONE only)
* \param hash buffer holding the message digest
* \param sig buffer holding the ciphertext
*
* \return 0 if the verify operation was successful,
* or an \c MBEDTLS_ERR_RSA_XXX error code
*
* \note The \c sig buffer must be as large as the size
* of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
*
* \note The \c hash_id in the RSA context is the one used for the
* verification. \c md_alg in the function call is the type of
* hash that is verified. According to RFC 3447 it is advised to
* keep both hashes the same. If \c hash_id in the RSA context is
* unset, the \c md_alg from the function call is used.
*/
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 Perform a PKCS#1 v2.1 PSS verification (RSASSA-PSS-VERIFY)
* (This is the version with "full" options.)
*
* \param ctx points to an RSA public key
* \param f_rng RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
* \param p_rng RNG parameter
* \param mode \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
* \param md_alg a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE for signing raw data)
* \param hashlen message digest length (for \c MBEDTLS_MD_NONE only)
* \param hash buffer holding the message digest
* \param mgf1_hash_id message digest used for mask generation
* \param expected_salt_len Length of the salt used in padding, use
* \c MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length
* \param sig buffer holding the ciphertext
*
* \return 0 if the verify operation was successful,
* or an \c MBEDTLS_ERR_RSA_XXX error code
*
* \note The \c sig buffer must be as large as the size
* of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
*
* \note The \c hash_id in the RSA context is ignored.
*/
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 Copy the components of an RSA context
*
* \param dst Destination context
* \param src Source context
*
* \return 0 on success,
* \c MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure
*/
int mbedtls_rsa_copy( mbedtls_rsa_context *dst, const mbedtls_rsa_context *src );
/**
* \brief Free the components of an RSA key
*
* \param ctx RSA Context to free
*/
void mbedtls_rsa_free( mbedtls_rsa_context *ctx );
/**
* \brief Checkup routine
*
* \return 0 if successful, or 1 if the test failed
*/
int mbedtls_rsa_self_test( int verbose );
#ifdef __cplusplus
}
#endif
#endif /* MBEDTLS_RSA_C */
#endif /* rsa.h */
Reference in New Issue View Git Blame Copy Permalink