diff --git a/include/mbedtls/rsa.h b/include/mbedtls/rsa.h index 752105822..fb2f77f94 100644 --- a/include/mbedtls/rsa.h +++ b/include/mbedtls/rsa.h @@ -1,10 +1,15 @@ /** * \file rsa.h * - * \brief The RSA public-key cryptosystem + * \brief The RSA public-key cryptosystem. + * + * For more information, see Public-Key Cryptography Standards (PKCS) + * #1 v1.5: RSA Encryption and Public-Key Cryptography Standards + * (PKCS) #1 v2.1: RSA Cryptography Specifications. + * */ /* - * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved + * 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 @@ -19,7 +24,7 @@ * 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) + * This file is part of Mbed TLS (https://tls.mbed.org) */ #ifndef MBEDTLS_RSA_H #define MBEDTLS_RSA_H @@ -43,26 +48,26 @@ #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_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. */ -#define MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION -0x4500 /**< The implementation doesn't offer the requested operation, e.g. because of security violations or lack of functionality */ +#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. */ #define MBEDTLS_ERR_RSA_HW_ACCEL_FAILED -0x4580 /**< RSA hardware accelerator failed. */ /* * RSA constants */ -#define MBEDTLS_RSA_PUBLIC 0 -#define MBEDTLS_RSA_PRIVATE 1 +#define MBEDTLS_RSA_PUBLIC 0 /**< Request private key operation. */ +#define MBEDTLS_RSA_PRIVATE 1 /**< Request public key operation. */ -#define MBEDTLS_RSA_PKCS_V15 0 -#define MBEDTLS_RSA_PKCS_V21 1 +#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 -#define MBEDTLS_RSA_CRYPT 2 +#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 @@ -80,103 +85,106 @@ extern "C" { #endif /** - * \brief RSA context structure + * \brief The 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. - * + * is deprecated. All manipulation should instead be done through + * the public interface functions. */ typedef struct { - int ver; /*!< always 0 */ - size_t len; /*!< size(N) in chars */ + int ver; /*!< Always 0.*/ + size_t len; /*!< The size of \p N in Bytes. */ - mbedtls_mpi N; /*!< public modulus */ - mbedtls_mpi E; /*!< public exponent */ + mbedtls_mpi N; /*!< The public modulus. */ + mbedtls_mpi E; /*!< The public exponent. */ - mbedtls_mpi D; /*!< private exponent */ - mbedtls_mpi P; /*!< 1st prime factor */ - mbedtls_mpi Q; /*!< 2nd prime factor */ + mbedtls_mpi D; /*!< The private exponent. */ + mbedtls_mpi P; /*!< The first prime factor. */ + mbedtls_mpi Q; /*!< The second prime factor. */ - mbedtls_mpi DP; /*!< D % (P - 1) */ - mbedtls_mpi DQ; /*!< D % (Q - 1) */ + mbedtls_mpi DP; /*!< \p D % (P - 1) */ + mbedtls_mpi DQ; /*!< \p D % (Q - 1) */ mbedtls_mpi QP; /*!< 1 / (Q % P) */ - mbedtls_mpi RN; /*!< cached R^2 mod N */ + mbedtls_mpi RN; /*!< cached R^2 mod \p N */ - mbedtls_mpi RP; /*!< cached R^2 mod P */ - mbedtls_mpi RQ; /*!< cached R^2 mod Q */ + mbedtls_mpi RP; /*!< cached R^2 mod \p P */ + mbedtls_mpi RQ; /*!< cached R^2 mod \p Q */ - mbedtls_mpi Vi; /*!< cached blinding value */ - mbedtls_mpi Vf; /*!< cached un-blinding value */ + mbedtls_mpi Vi; /*!< The cached blinding value. */ + mbedtls_mpi Vf; /*!< The 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 */ + 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 */ + mbedtls_threading_mutex_t mutex; /*!< Thread-safety mutex. */ #endif } mbedtls_rsa_context; /** - * \brief Initialize an RSA context + * \brief This function initializes an RSA context. * - * Note: Set padding to \c MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP + * \note Set padding to #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 + * \param ctx The RSA context to initialize. + * \param padding Selects padding mode: #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. * - * \note The hash_id parameter is actually ignored - * when using \c MBEDTLS_RSA_PKCS_V15 padding. + * \note The \p hash_id parameter is ignored when using + * #MBEDTLS_RSA_PKCS_V15 padding. * - * \note Choice of padding mode is strictly enforced for private key + * \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's merely + * mixing padding modes. For public key operations it is * a default value, which can be overriden by calling specific - * rsa_rsaes_xxx or rsa_rsassa_xxx functions. + * \c rsa_rsaes_xxx or \c 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. + * \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 overriden for verifying them. + * If set to #MBEDTLS_MD_NONE, it is always overriden. */ void mbedtls_rsa_init( mbedtls_rsa_context *ctx, int padding, int hash_id); /** - * \brief Import a set of core parameters into an RSA context + * \brief This function imports 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 + * \param ctx The initialized RSA context to store the parameters in. + * \param N The RSA modulus, or NULL. + * \param P The first prime factor of \p N, or NULL. + * \param Q The second prime factor of \p N, or NULL. + * \param D The private exponent, or NULL. + * \param E The public exponent, or NULL. * * \note This function can be called multiple times for successive - * imports if the parameters are not simultaneously present. + * 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 + * 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 the documentation of \c mbedtls_rsa_complete for more - * information on which parameters are necessary to setup - * a private or public 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. * - * \return 0 if successful, non-zero error code on failure. + * \return \c 0 on success, or a non-zero error code on failure. */ int mbedtls_rsa_import( mbedtls_rsa_context *ctx, const mbedtls_mpi *N, @@ -184,36 +192,37 @@ int mbedtls_rsa_import( mbedtls_rsa_context *ctx, const mbedtls_mpi *D, const mbedtls_mpi *E ); /** - * \brief Import core RSA parameters in raw big-endian - * binary format into an RSA context + * \brief This function imports 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 + * \param ctx The initialized RSA context to store the parameters in. + * \param N The RSA modulus, or NULL. + * \param N_len The Byte length of \p N, ignored if \p N == NULL. + * \param P The first prime factor of \p N, or NULL. + * \param P_len The Byte length of \p P, ignored if \p P == NULL. + * \param Q The second prime factor of \p N, or NULL. + * \param Q_len The Byte length of \p Q, ignored if \p Q == NULL. + * \param D The private exponent, or NULL. + * \param D_len The Byte length of \p D, ignored if \p D == NULL. + * \param E The public exponent, or NULL. + * \param E_len The Byte length of \p E, ignored if \p E == NULL. * * \note This function can be called multiple times for successive - * imports if the parameters are not simultaneously present. + * 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 + * 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 the documentation of \c mbedtls_rsa_complete for more - * information on which parameters are necessary to setup - * a private or public 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. * - * \return 0 if successful, non-zero error code on failure. + * \return \c 0 on success, or a non-zero error code on failure. */ int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx, unsigned char const *N, size_t N_len, @@ -223,71 +232,71 @@ int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx, unsigned char const *E, size_t E_len ); /** - * \brief Attempt to complete an RSA context from + * \brief This function completes an RSA context from * a set of imported core parameters. * - * \param ctx Initialized RSA context to store parameters + * To setup an RSA public key, precisely \p N and \p E + * must have been imported. * - * \note - * - To setup an RSA public key, precisely N and E - * must have been imported. + * To setup an RSA private key, sufficient information must + * be present for the other parameters to be derivable. * - * - To setup an RSA private key, enough information must be - * present for the other parameters to be derivable. + * The default implementation supports the following: + * + * Alternative implementations need not support these. * - * The default implementation supports the following: - * - Derive P, Q from N, D, E - * - Derive N, D from P, Q, E. + * If this function runs successfully, it guarantees that + * the RSA context can be used for RSA operations without + * the risk of failure or crash. * - * - Alternative implementations need not support these - * and may return \c MBEDTLS_ERR_RSA_BAD_INPUT_DATA instead. + * \param ctx The initialized RSA context holding imported parameters. * - * \return - * - 0 if successful. In this case, it is guaranteed - * that the RSA context can be used for RSA operations - * without the risk of failure or crash. - * - \c MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted - * derivations failed. + * \return \c 0 on success, or #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the + * attempted derivations failed. * * \warning This function need not perform consistency checks - * for the imported parameters! In particular, parameters that - * are not needed by the implementation may be silently discarded - * and left unchecked. For the purpose of checking the consistency - * of the key material, see \c mbedtls_rsa_check_privkey. + * 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(). * */ int mbedtls_rsa_complete( mbedtls_rsa_context *ctx ); /** - * \brief Export core parameters of an RSA key + * \brief This function exports the 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 + * 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. * - * \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_UNSUPPORTED_OPERATION is returned. - * In this case, the RSA context stays intact and can - * be continued to be used. + * Possible reasons for returning + * #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION: * - * \note Reasons for returning \c MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION - * 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. + * 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, or NULL. + * \param P The MPI to hold the first prime factor of \p N, or NULL. + * \param Q The MPI to hold the second prime factor of \p N, or NULL. + * \param D The MPI to hold the private exponent, or NULL. + * \param E The MPI to hold the public exponent, or NULL. + * + * \return \c 0 on success, + * #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the + * requested parameters cannot be done due to missing + * functionality or because of security policies, + * or a non-zero return code on any other failure. * */ int mbedtls_rsa_export( const mbedtls_rsa_context *ctx, @@ -295,46 +304,48 @@ int mbedtls_rsa_export( const mbedtls_rsa_context *ctx, mbedtls_mpi *D, mbedtls_mpi *E ); /** - * \brief Export core parameters of an RSA key - * in raw big-endian binary format + * \brief This function exports 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 + * 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_RSA_UNSUPPORTED_OPERATION: + * 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 Byte array to store the RSA modulus, or NULL. + * \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 + * NULL. + * \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 + NULL. + * \param Q_len The size of the buffer for the second prime factor. + * \param D The Byte array to hold the private exponent, or NULL. + * \param D_len The size of the buffer for the private exponent. + * \param E The Byte array to hold the public exponent, or NULL. + * \param E_len The size of the buffer for the 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_UNSUPPORTED_OPERATION 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_UNSUPPORTED_OPERATION - * 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. - * - * + * \return \c 0 on success, + * #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the + * requested parameters cannot be done due to missing + * functionality or because of security policies, + * or 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, @@ -344,57 +355,59 @@ int mbedtls_rsa_export_raw( const mbedtls_rsa_context *ctx, unsigned char *E, size_t E_len ); /** - * \brief Export CRT parameters of a private RSA key + * \brief This function exports 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 + * \param ctx The initialized RSA context. + * \param DP The MPI to hold D modulo P-1, or NULL. + * \param DQ The MPI to hold D modulo Q-1, or NULL. + * \param QP The MPI to hold modular inverse of Q modulo P, or NULL. * - * \return 0 if successful, non-zero error code otherwise. + * \return \c 0 on success, 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. + * internally can implement this function based on + * 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. + * \brief This function sets padding for an already initialized RSA + * context. See 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 + * \param ctx The RSA context to be set. + * \param padding Selects padding mode: #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 Get length of RSA modulus in bytes + * \brief This function retrieves the length of RSA modulus in Bytes. * - * \param ctx Initialized RSA context + * \param ctx The initialized RSA context. * - * \return Length of RSA modulus, in bytes. + * \return The length of the RSA modulus in Bytes. * */ size_t mbedtls_rsa_get_len( const mbedtls_rsa_context *ctx ); /** - * \brief Generate an RSA keypair + * \brief This function generates 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) + * \param ctx The RSA context used to hold the key. + * \param f_rng The RNG function. + * \param p_rng The RNG parameter. + * \param nbits The size of the public key in bits. + * \param exponent The public exponent. For example, 65537. * - * \note mbedtls_rsa_init() must be called beforehand to setup - * the RSA context. + * \note mbedtls_rsa_init() must be called before this function, + * to set up the RSA context. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code + * \return \c 0 on success, or 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), @@ -402,101 +415,109 @@ int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx, unsigned int nbits, int exponent ); /** - * \brief Check if a context contains (at least) an RSA public key + * \brief This function checks if a context contains at least an RSA + * public key. * - * \param ctx RSA context to be checked + * If the function runs successfully, it is guaranteed that + * enough information is present to perform an RSA public key + * operation using mbedtls_rsa_public(). * - * \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. + * \param ctx The RSA context to check. + * + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * */ int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx ); /** - * \brief Check if a context contains an RSA private key + * \brief This function checks if a context contains an RSA private key * and perform basic consistency checks. * - * \param ctx RSA context to be checked + * \param ctx The RSA context to check. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code. + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code on + * failure. * * \note The consistency checks performed by this function not only - * ensure that \c mbedtls_rsa_private can be called successfully + * 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 - * \c mbedtls_rsa_public and \c mbedtls_rsa_private are inverses. + * 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: - * - Regarding consistency, note (see \c mbedtls_rsa_complete) - * that imported parameters irrelevant for the implementation - * might be silently dropped, in which case the present - * function doesn't have access to and hence cannot check them. - * If you want to check the consistency of the entire - * content of, say, an PKCS1-encoded RSA private key, you - * should use \c mbedtls_rsa_validate_params before setting - * up the RSA context. - * Further, if the implementation performs empirical checks, - * these checks will substantiate but not guarantee consistency. - * - Regarding quality, this function is not expected to perform - * extended quality assessments like checking that the prime - * factors are safe. Further, it is the user's responsibility to - * ensure trustworthiness of the source of his RSA parameters, - * a question going beyond what's effectively checkable - * by the library. - * + * */ 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. + * \brief This function checks a public-private RSA key pair. * - * \param pub RSA context holding the public key - * \param prv RSA context holding the private key + * It checks each of the contexts, and makes sure they match. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code + * \param pub The RSA context holding the public key. + * \param prv The RSA context holding the private key. + * + * \return \c 0 on success, or 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 Do an RSA public key operation + * \brief This function performs an RSA public key operation. * - * \param ctx RSA context - * \param input input buffer - * \param output output buffer + * \param ctx The RSA context. + * \param input The input buffer. + * \param output The output buffer. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * - * \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 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. * * \note The input and output buffers must be large - * enough (eg. 128 bytes if RSA-1024 is used). + * enough. For example, 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 + * \brief This function performs 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 + * \param ctx The RSA context. + * \param f_rng The RNG function. Needed for blinding. + * \param p_rng The RNG parameter. + * \param input The input buffer. + * \param output The output buffer. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * * \note The input and output buffers must be large - * enough (eg. 128 bytes if RSA-1024 is used). + * enough. For example, 128 Bytes if RSA-1024 is used. */ int mbedtls_rsa_private( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -505,32 +526,36 @@ int mbedtls_rsa_private( mbedtls_rsa_context *ctx, 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. + * \brief This function adds the message padding, then performs 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 + * It is the generic wrapper for performing a PKCS#1 encryption + * operation using the \p mode from the context. + * + * + * \param ctx The RSA context. + * \param f_rng The RNG function. Needed for padding, PKCS#1 v2.1 + * encoding, and #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. + * \param ilen The length of the plaintext. + * \param input The buffer holding the data to encrypt. + * \param output The buffer used to hold the ciphertext. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PUBLIC. + * 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 may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PRIVATE and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * - * \note The output buffer must be as large as the size - * of ctx->N (eg. 128 bytes if RSA-1024 is used). + * \note The input and output buffers must be as large as the size + * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. */ int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -540,29 +565,32 @@ int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx, unsigned char *output ); /** - * \brief Perform a PKCS#1 v1.5 encryption (RSAES-PKCS1-v1_5-ENCRYPT) + * \brief This function performs a PKCS#1 v1.5 encryption operation + * (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 + * \param ctx The RSA context. + * \param f_rng The RNG function. Needed for padding and + * #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. + * \param ilen The length of the plaintext. + * \param input The buffer holding the data to encrypt. + * \param output The buffer used to hold the ciphertext. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PUBLIC. + * 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 may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PRIVATE and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * * \note The output buffer must be as large as the size - * of ctx->N (eg. 128 bytes if RSA-1024 is used). + * of \p ctx->N. For example, 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), @@ -572,32 +600,34 @@ int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx, unsigned char *output ); /** - * \brief Perform a PKCS#1 v2.1 OAEP encryption (RSAES-OAEP-ENCRYPT) + * \brief This function performs a PKCS#1 v2.1 OAEP encryption + * operation (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 + * \param ctx The RSA context. + * \param f_rng The RNG function. Needed for padding and PKCS#1 v2.1 + * encoding and #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. + * \param label The buffer holding the custom label to use. + * \param label_len The length of the label. + * \param ilen The length of the plaintext. + * \param input The buffer holding the data to encrypt. + * \param output The buffer used to hold the ciphertext. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PUBLIC. + * 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 may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PRIVATE and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * * \note The output buffer must be as large as the size - * of ctx->N (eg. 128 bytes if RSA-1024 is used). + * of ctx->N. For example, 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), @@ -609,39 +639,42 @@ int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx, 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 + * \brief This function performs an RSA operation, then removes 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 + * It is the generic wrapper for performing a PKCS#1 decryption + * operation using the \p mode from the context. + * + * \param ctx The RSA context. + * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. + * \param olen The length of the plaintext. + * \param input The buffer holding the encrypted data. + * \param output The buffer used to hold the plaintext. + * \param output_max_len The maximum length of the output buffer. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PRIVATE. + * 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 may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PUBLIC and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * * \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. + * 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. * * \note The input buffer must be as large as the size - * of \c ctx->N (eg. 128 bytes if RSA-1024 is used). + * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. */ int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -652,37 +685,39 @@ int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx, size_t output_max_len ); /** - * \brief Perform a PKCS#1 v1.5 decryption (RSAES-PKCS1-v1_5-DECRYPT) + * \brief This function performs a PKCS#1 v1.5 decryption + * operation (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 + * \param ctx The RSA context. + * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. + * \param olen The length of the plaintext. + * \param input The buffer holding the encrypted data. + * \param output The buffer to hold the plaintext. + * \param output_max_len The maximum length of the output buffer. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PRIVATE. + * 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 may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PUBLIC and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * * \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. + * 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. * * \note The input buffer must be as large as the size - * of \c ctx->N (eg. 128 bytes if RSA-1024 is used). + * of \p ctx->N. For example, 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), @@ -693,40 +728,42 @@ int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx, size_t output_max_len ); /** - * \brief Perform a PKCS#1 v2.1 OAEP decryption (RSAES-OAEP-DECRYPT) + * \brief This function performs a PKCS#1 v2.1 OAEP decryption + * operation (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 + * \param ctx The RSA context. + * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE. + * \param label The buffer holding the custom label to use. + * \param label_len The length of the label. + * \param olen The length of the plaintext. + * \param input The buffer holding the encrypted data. + * \param output The buffer to hold the plaintext. + * \param output_max_len The maximum length of the output buffer. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PRIVATE. + * 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 may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PUBLIC and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code + * \return \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * * \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. + * 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. * * \note The input buffer must be as large as the size - * of \c ctx->N (eg. 128 bytes if RSA-1024 is used). - * + * of \p ctx->N. For example, 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), @@ -739,39 +776,41 @@ int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx, 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 + * \brief This function performs a private RSA operation to sign + * a message digest using PKCS#1. * - * \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 + * It is the generic wrapper for performing a PKCS#1 + * signature using the \p mode from the context. + * + * \param ctx The RSA context. + * \param f_rng The RNG function. Needed for PKCS#1 v2.1 encoding and for + * #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #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. Only used if \p md_alg is #MBEDTLS_MD_NONE. + * \param hash The buffer holding the message digest. + * \param sig The buffer to hold the ciphertext. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PRIVATE. + * 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 may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PUBLIC and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if the signing operation was successful, - * or an \c MBEDTLS_ERR_RSA_XXX error code + * \return \c 0 if the signing operation was successful, + * or an \c MBEDTLS_ERR_RSA_XXX error code on failure. * - * \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 \p sig buffer must be as large as the size + * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used. * - * \note In case of PKCS#1 v2.1 encoding, see comments on - * \c mbedtls_rsa_rsassa_pss_sign() for details on - * \c md_alg and \c hash_id. + * \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. */ int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -783,32 +822,34 @@ int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx, unsigned char *sig ); /** - * \brief Perform a PKCS#1 v1.5 signature (RSASSA-PKCS1-v1_5-SIGN) + * \brief This function performs a PKCS#1 v1.5 signature + * operation (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 + * \param ctx The RSA context. + * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #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. Only used if \p md_alg is #MBEDTLS_MD_NONE. + * \param hash The buffer holding the message digest. + * \param sig The buffer to hold the ciphertext. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PRIVATE. + * 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 may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PUBLIC and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if the signing operation was successful, + * \return \c 0 if the signing operation was successful, * or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * - * \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 \p sig buffer must be as large as the size + * of \p ctx->N. For example, 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), @@ -820,38 +861,42 @@ int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx, unsigned char *sig ); /** - * \brief Perform a PKCS#1 v2.1 PSS signature (RSASSA-PSS-SIGN) + * \brief This function performs a PKCS#1 v2.1 PSS signature + * operation (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 + * \param ctx The RSA context. + * \param f_rng The RNG function. Needed for PKCS#1 v2.1 encoding and for + * #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #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. Only used if \p md_alg is #MBEDTLS_MD_NONE. + * \param hash The buffer holding the message digest. + * \param sig The buffer to hold the ciphertext. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PRIVATE. + * 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 may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PUBLIC and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if the signing operation was successful, + * \return \c 0 if the signing operation was successful, * or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * - * \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 \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 \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. + * \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 RFC-3447: Public-Key + * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography + * Specifications 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), @@ -863,36 +908,41 @@ int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx, 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 + * \brief This function performs a public RSA operation and checks + * 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 + * This is the generic wrapper for performing a PKCS#1 + * verification using the mode from the context. + * + * \param ctx The RSA public key context. + * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #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. Only used if \p md_alg is #MBEDTLS_MD_NONE. + * \param hash The buffer holding the message digest. + * \param sig The buffer holding the ciphertext. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PUBLIC. + * 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 may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PRIVATE and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if the verify operation was successful, + * \return \c 0 if the verify operation was successful, * or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * - * \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 \p sig buffer must be as large as the size + * of \p ctx->N. For example, 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. + * \note For PKCS#1 v2.1 encoding, see comments on + * mbedtls_rsa_rsassa_pss_verify() about \p md_alg and + * \p hash_id. */ int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -904,32 +954,34 @@ int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx, const unsigned char *sig ); /** - * \brief Perform a PKCS#1 v1.5 verification (RSASSA-PKCS1-v1_5-VERIFY) + * \brief This function performs a PKCS#1 v1.5 verification + * operation (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 + * \param ctx The RSA public key context. + * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #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. Only used if \p md_alg is #MBEDTLS_MD_NONE. + * \param hash The buffer holding the message digest. + * \param sig The buffer holding the ciphertext. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PUBLIC. + * 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 may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PRIVATE and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if the verify operation was successful, + * \return \c 0 if the verify operation was successful, * or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * - * \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 \p sig buffer must be as large as the size + * of \p ctx->N. For example, 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), @@ -941,38 +993,45 @@ int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx, const unsigned char *sig ); /** - * \brief Perform a PKCS#1 v2.1 PSS verification (RSASSA-PSS-VERIFY) - * (This is the "simple" version.) + * \brief This function performs a PKCS#1 v2.1 PSS verification + * operation (RSASSA-PSS-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 + * The hash function for the MGF mask generating function + * is that specified in the RSA context. + * + * \param ctx The RSA public key context. + * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #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. Only used if \p md_alg is #MBEDTLS_MD_NONE. + * \param hash The buffer holding the message digest. + * \param sig The buffer holding the ciphertext. * * \deprecated It is deprecated and discouraged to call this function - * in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary - * are likely to remove the mode argument and have it implicitly - * set to MBEDTLS_RSA_PUBLIC. + * 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 may instead - * return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. + * mode being set to #MBEDTLS_RSA_PRIVATE and might instead + * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION. * - * \return 0 if the verify operation was successful, + * \return \c 0 if the verify operation was successful, * or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * - * \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 \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 \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. + * \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 RFC-3447: Public-Key + * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography + * Specifications 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. */ int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx, int (*f_rng)(void *, unsigned char *, size_t), @@ -984,28 +1043,33 @@ int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx, const unsigned char *sig ); /** - * \brief Perform a PKCS#1 v2.1 PSS verification (RSASSA-PSS-VERIFY) - * (This is the version with "full" options.) + * \brief This function performs a PKCS#1 v2.1 PSS verification + * operation (RSASSA-PSS-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 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 + * The hash function for the MGF mask generating function + * is that specified in \p mgf1_hash_id. * - * \return 0 if the verify operation was successful, + * \param ctx The RSA public key context. + * \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE. + * \param p_rng The RNG parameter. + * \param mode #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. Only used if \p md_alg is #MBEDTLS_MD_NONE. + * \param hash The buffer holding the message digest. + * \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 ciphertext. + * + * \return \c 0 if the verify operation was successful, * or an \c MBEDTLS_ERR_RSA_XXX error code + * on failure. * - * \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 \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 \c hash_id in the RSA context is ignored. + * \note The \p 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), @@ -1019,20 +1083,20 @@ int mbedtls_rsa_rsassa_pss_verify_ext( mbedtls_rsa_context *ctx, const unsigned char *sig ); /** - * \brief Copy the components of an RSA context + * \brief This function copies the components of an RSA context. * - * \param dst Destination context - * \param src Source context + * \param dst The destination context. + * \param src The source context. * - * \return 0 on success, - * \c MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure + * \return \c 0 on success, + * #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 + * \brief This function frees the components of an RSA key. * - * \param ctx RSA Context to free + * \param ctx The RSA Context to free. */ void mbedtls_rsa_free( mbedtls_rsa_context *ctx ); @@ -1049,9 +1113,9 @@ extern "C" { #endif /** - * \brief Checkup routine + * \brief The RSA checkup routine. * - * \return 0 if successful, or 1 if the test failed + * \return \c 0 on success, or \c 1 on failure. */ int mbedtls_rsa_self_test( int verbose ); diff --git a/library/error.c b/library/error.c index d9ad6384a..eaf75adb1 100644 --- a/library/error.c +++ b/library/error.c @@ -366,7 +366,7 @@ void mbedtls_strerror( int ret, char *buf, size_t buflen ) if( use_ret == -(MBEDTLS_ERR_RSA_KEY_GEN_FAILED) ) mbedtls_snprintf( buf, buflen, "RSA - Something failed during generation of a key" ); if( use_ret == -(MBEDTLS_ERR_RSA_KEY_CHECK_FAILED) ) - mbedtls_snprintf( buf, buflen, "RSA - Key failed to pass the library's validity check" ); + mbedtls_snprintf( buf, buflen, "RSA - Key failed to pass the validity check of the library" ); if( use_ret == -(MBEDTLS_ERR_RSA_PUBLIC_FAILED) ) mbedtls_snprintf( buf, buflen, "RSA - The public key operation failed" ); if( use_ret == -(MBEDTLS_ERR_RSA_PRIVATE_FAILED) ) @@ -378,7 +378,7 @@ void mbedtls_strerror( int ret, char *buf, size_t buflen ) if( use_ret == -(MBEDTLS_ERR_RSA_RNG_FAILED) ) mbedtls_snprintf( buf, buflen, "RSA - The random generator failed to generate non-zeros" ); if( use_ret == -(MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION) ) - mbedtls_snprintf( buf, buflen, "RSA - The implementation doesn't offer the requested operation, e.g. because of security violations or lack of functionality" ); + mbedtls_snprintf( buf, buflen, "RSA - The implementation does not offer the requested operation, for example, because of security violations or lack of functionality" ); if( use_ret == -(MBEDTLS_ERR_RSA_HW_ACCEL_FAILED) ) mbedtls_snprintf( buf, buflen, "RSA - RSA hardware accelerator failed" ); #endif /* MBEDTLS_RSA_C */