Update rsa.h
Changes based on review comments.
diff --git a/include/mbedtls/rsa.h b/include/mbedtls/rsa.h
index 711329c..033e580 100644
--- a/include/mbedtls/rsa.h
+++ b/include/mbedtls/rsa.h
@@ -1,7 +1,7 @@
/**
* \file rsa.h
*
- * \brief This file contains RSA definitions and functions.
+ * \brief This file defines the RSA public-key cryptosystem.
*
* The RSA public-key cryptosystem is defined in <em>Public-Key
* Cryptography Standards (PKCS) #1 v1.5: RSA Encryption</em>
@@ -104,14 +104,14 @@
mbedtls_mpi P; /*!< The first prime factor. */
mbedtls_mpi Q; /*!< The second prime factor. */
- mbedtls_mpi DP; /*!< \p D % (P - 1) */
- mbedtls_mpi DQ; /*!< \p D % (Q - 1) */
- mbedtls_mpi QP; /*!< 1 / (Q % P) */
+ mbedtls_mpi DP; /*!< <code>D % (P - 1)</code>. */
+ mbedtls_mpi DQ; /*!< <code>D % (Q - 1)</code>. */
+ mbedtls_mpi QP; /*!< <code>1 / (Q % P)</code>. */
- mbedtls_mpi RN; /*!< cached R^2 mod \p N */
+ mbedtls_mpi RN; /*!< cached <code>R^2 mod N</code>. */
- mbedtls_mpi RP; /*!< cached R^2 mod \p P */
- mbedtls_mpi RQ; /*!< cached R^2 mod \p Q */
+ mbedtls_mpi RP; /*!< cached <code>R^2 mod P</code>. */
+ mbedtls_mpi RQ; /*!< cached <code>R^2 mod Q</code>. */
mbedtls_mpi Vi; /*!< The cached blinding value. */
mbedtls_mpi Vf; /*!< The cached un-blinding value. */
@@ -328,7 +328,7 @@
* If the function fails due to an unsupported operation,
* the RSA context stays intact and remains usable.
*
- * \note The length fields are ignored if the corresponding
+ * \note The length parameters are ignored if the corresponding
* buffer pointers are NULL.
*
* \param ctx The initialized RSA context.
@@ -338,7 +338,7 @@
* 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.
+ * 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.
@@ -549,10 +549,6 @@
* It is the generic wrapper for performing a PKCS#1 encryption
* operation using the \p mode from the context.
*
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
- * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
- *
* \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.
*
@@ -561,6 +557,10 @@
* are likely to remove the \p mode argument and have it
* implicitly set to #MBEDTLS_RSA_PUBLIC.
*
+ * \note Alternative implementations of RSA need not support
+ * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *
* \param ctx The RSA context.
* \param f_rng The RNG function. Needed for padding, PKCS#1 v2.1
* encoding, and #MBEDTLS_RSA_PRIVATE.
@@ -584,10 +584,6 @@
* \brief This function performs a PKCS#1 v1.5 encryption operation
* (RSAES-PKCS1-v1_5-ENCRYPT).
*
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
- * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
- *
* \note The output buffer must be as large as the size
* of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
*
@@ -596,6 +592,10 @@
* are likely to remove the \p mode argument and have it
* implicitly set to #MBEDTLS_RSA_PUBLIC.
*
+ * \note Alternative implementations of RSA need not support
+ * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *
* \param ctx The RSA context.
* \param f_rng The RNG function. Needed for padding and
* #MBEDTLS_RSA_PRIVATE.
@@ -619,10 +619,6 @@
* \brief This function performs a PKCS#1 v2.1 OAEP encryption
* operation (RSAES-OAEP-ENCRYPT).
*
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
- * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
- *
* \note The output buffer must be as large as the size
* of ctx->N. For example, 128 Bytes if RSA-1024 is used.
*
@@ -631,6 +627,10 @@
* are likely to remove the \p mode argument and have it
* implicitly set to #MBEDTLS_RSA_PUBLIC.
*
+ * \note Alternative implementations of RSA need not support
+ * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *
* \param ctx The RSA context.
* \param f_rng The RNG function. Needed for padding and PKCS#1 v2.1
* encoding and #MBEDTLS_RSA_PRIVATE.
@@ -671,15 +671,15 @@
* \note The input buffer must be as large as the size
* of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
*
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
- * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
- *
* \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
* are likely to remove the \p mode argument and have it
* implicitly set to #MBEDTLS_RSA_PRIVATE.
*
+ * \note Alternative implementations of RSA need not support
+ * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *
* \param ctx The RSA context.
* \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
* \param p_rng The RNG context.
@@ -691,7 +691,6 @@
*
* \return \c 0 on success.
* \return An \c MBEDTLS_ERR_RSA_XXX error code on failure.
-
*/
int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx,
int (*f_rng)(void *, unsigned char *, size_t),
@@ -705,10 +704,6 @@
* \brief This function performs a PKCS#1 v1.5 decryption
* operation (RSAES-PKCS1-v1_5-DECRYPT).
*
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
- * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
- *
* \note The output buffer length \c output_max_len should be
* as large as the size \p ctx->len of \p ctx->N, for example,
* 128 Bytes if RSA-1024 is used, to be able to hold an
@@ -724,6 +719,10 @@
* are likely to remove the \p mode argument and have it
* implicitly set to #MBEDTLS_RSA_PRIVATE.
*
+ * \note Alternative implementations of RSA need not support
+ * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *
* \param ctx The RSA context.
* \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
* \param p_rng The RNG context.
@@ -749,26 +748,26 @@
* \brief This function performs a PKCS#1 v2.1 OAEP decryption
* operation (RSAES-OAEP-DECRYPT).
*
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
- * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ * \note The output buffer length \c output_max_len should be
+ * as large as the size \p ctx->len of \p ctx->N, for
+ * example, 128 Bytes if RSA-1024 is used, to be able to
+ * hold an arbitrary decrypted message. If it is not
+ * large enough to hold the decryption of the particular
+ * ciphertext provided, the function returns
+ * #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
*
- * \note The output buffer length \c output_max_len should be
- * as large as the size \p ctx->len of \p ctx->N, for
- * example, 128 Bytes if RSA-1024 is used, to be able to
- * hold an arbitrary decrypted message. If it is not
- * large enough to hold the decryption of the particular
- * ciphertext provided, the function returns
- * #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
- *
- * \note The input buffer must be as large as the size
- * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
+ * \note The input buffer must be as large as the size
+ * of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
*
* \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
* are likely to remove the \p mode argument and have it
* implicitly set to #MBEDTLS_RSA_PRIVATE.
*
+ * \note Alternative implementations of RSA need not support
+ * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *
* \param ctx The RSA context.
* \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
* \param p_rng The RNG context.
@@ -800,10 +799,6 @@
* It is the generic wrapper for performing a PKCS#1
* signature using the \p mode from the context.
*
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
- * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
- *
* \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.
*
@@ -816,6 +811,10 @@
* are likely to remove the \p mode argument and have it
* implicitly set to #MBEDTLS_RSA_PRIVATE.
*
+ * \note Alternative implementations of RSA need not support
+ * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *
* \param ctx The RSA context.
* \param f_rng The RNG function. Needed for PKCS#1 v2.1 encoding and for
* #MBEDTLS_RSA_PRIVATE.
@@ -843,10 +842,6 @@
* \brief This function performs a PKCS#1 v1.5 signature
* operation (RSASSA-PKCS1-v1_5-SIGN).
*
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
- * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
- *
* \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.
*
@@ -855,6 +850,10 @@
* are likely to remove the \p mode argument and have it
* implicitly set to #MBEDTLS_RSA_PRIVATE.
*
+ * \note Alternative implementations of RSA need not support
+ * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *
* \param ctx The RSA context.
* \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
* \param p_rng The RNG context.
@@ -881,10 +880,6 @@
* \brief This function performs a PKCS#1 v2.1 PSS signature
* operation (RSASSA-PSS-SIGN).
*
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
- * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
- *
* \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.
*
@@ -900,6 +895,10 @@
* are likely to remove the \p mode argument and have it
* implicitly set to #MBEDTLS_RSA_PRIVATE.
*
+ * \note Alternative implementations of RSA need not support
+ * mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *
* \param ctx The RSA context.
* \param f_rng The RNG function. Needed for PKCS#1 v2.1 encoding and for
* #MBEDTLS_RSA_PRIVATE.
@@ -930,10 +929,6 @@
* This is the generic wrapper for performing a PKCS#1
* verification using the mode from the context.
*
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
- * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
- *
* \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.
*
@@ -946,6 +941,10 @@
* are likely to remove the \p mode argument and have it
* set to #MBEDTLS_RSA_PUBLIC.
*
+ * \note Alternative implementations of RSA need not support
+ * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *
* \param ctx The RSA public key context.
* \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
* \param p_rng The RNG context.
@@ -972,10 +971,6 @@
* \brief This function performs a PKCS#1 v1.5 verification
* operation (RSASSA-PKCS1-v1_5-VERIFY).
*
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
- * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
- *
* \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.
*
@@ -984,6 +979,10 @@
* are likely to remove the \p mode argument and have it
* set to #MBEDTLS_RSA_PUBLIC.
*
+ * \note Alternative implementations of RSA need not support
+ * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *
* \param ctx The RSA public key context.
* \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
* \param p_rng The RNG context.
@@ -1013,10 +1012,6 @@
* The hash function for the MGF mask generating function
* is that specified in the RSA context.
*
- * \note Alternative implementations of RSA need not support
- * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
- * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
- *
* \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.
*
@@ -1033,6 +1028,10 @@
* are likely to remove the \p mode argument and have it
* implicitly set to #MBEDTLS_RSA_PUBLIC.
*
+ * \note Alternative implementations of RSA need not support
+ * mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ * return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *
* \param ctx The RSA public key context.
* \param f_rng The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
* \param p_rng The RNG context.