From 042e97fa7555528a7293611dce55c50eea757ed5 Mon Sep 17 00:00:00 2001
From: Rose Zadik <rose.zadik@arm.com>
Date: Fri, 26 Jan 2018 16:35:10 +0000
Subject: [PATCH] Improve RSA documentation
- Rephrase file/function/parameter/enum/define/error descriptions into full
and clear sentences.
- Make sure to adhere to the Arm writing guidelines.
- Fix missing/incorrect Doxygen tags.
- Standardize terminology used within the file.
- Rephrase the descriptions of all md_alg and hashlen parameters.
GitHub PR: #1327
---
include/mbedtls/rsa.h | 1098 ++++++++++++++++++++++-------------------
library/error.c | 4 +-
2 files changed, 583 insertions(+), 519 deletions(-)
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 <em>Public-Key Cryptography Standards (PKCS)
+ * #1 v1.5: RSA Encryption</em> and <em>Public-Key Cryptography Standards
+ * (PKCS) #1 v2.1: RSA Cryptography Specifications</em>.
+ *
*/
/*
- * Copyright (C) 2006-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:
+ * <ul><li>Derive \p P, \p Q from \p N, \p D, \p E.</li>
+ * <li>Derive \p N, \p D from \p P, \p Q, \p E.</li></ul>
+ * Alternative implementations need not support these.
*
- * 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:<ul>
+ * <li>An alternative RSA implementation is in use, which
+ * stores the key externally, and either cannot or should
+ * not export it into RAM.</li>
+ * <li>A SW or HW implementation might not support a certain
+ * deduction. For example, \p P, \p Q from \p N, \p D,
+ * and \p E if the former are not part of the
+ * implementation.</li></ul>
*
- * \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:<ul>
+ * <li>An alternative RSA implementation is in use, which
+ * stores the key externally, and either cannot or should
+ * not export it into RAM.</li>
+ * <li>A SW or HW implementation might not support a certain
+ * deduction. For example, \p P, \p Q from \p N, \p D,
+ * and \p E if the former are not part of the
+ * implementation.</li></ul>
+ * If the function fails due to an unsupported operation,
+ * the RSA context stays intact and remains usable.
+ *
+ * \param ctx The initialized RSA context.
+ * \param N The 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.
- *
+ * <ul><li>Consistency: Imported parameters that are irrelevant
+ * for the implementation might be silently dropped. If dropped,
+ * the current function does not have access to them,
+ * and therefore cannot check them. See mbedtls_rsa_complete().
+ * If you want to check the consistency of the entire
+ * content of an PKCS1-encoded RSA private key, for example, you
+ * should use mbedtls_rsa_validate_params() before setting
+ * up the RSA context.
+ * Additionally, if the implementation performs empirical checks,
+ * these checks substantiate but do not guarantee consistency.</li>
+ * <li>Quality: This function is not expected to perform
+ * extended quality assessments like checking that the prime
+ * factors are safe. Additionally, it is the responsibility of the
+ * user to ensure the trustworthiness of the source of his RSA
+ * parameters, which goes beyond what is effectively checkable
+ * by the library.</li></ul>
*/
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 <em>RFC-3447: Public-Key
+ * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
+ * Specifications</em> 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 <em>RFC-3447: Public-Key
+ * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
+ * Specifications</em> it is advised to keep both hashes the
+ * same. If \p hash_id in the RSA context is unset,
+ * the \p md_alg from the function call is used.
*/
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 */