mbedtls_rsa_rsassa_pss_*: improve documentation
Hashes used in RSA-PSS encoding (EMSA-PSS-ENCODE, see §9.1.1 in RFC
8017):
- H1: Hashing the message (step 2)
- H2: Hashing in the salt (step 6)
- H3: Mask generation function (step 9)
According to the standard:
- H1 and H2 MUST be done by the same hash function
- H3 is RECOMMENDED to be the same as the hash used for H1 and H2.
According to the implementation:
- H1 happens outside of the function call. It might or might not happen
and the implementation might or might not be aware of the hash used.
- H2 happens inside the function call, consistency with H1 is not
enforced and might not even be possible to detect.
- H3 is done with the same hash as H2 (with the exception of
mbedtls_rsassa_pss_verify_ext(), which takes a dedicated parameter for
the hash used in the MGF).
Issues with the documentation:
- The comments weren't always clear about the three hashes involved and
often only mentioned two of them (which two varied from function to
function).
- The documentation was giving the impression that the standard
recommends aligning H2 and H1 (which is not a recommendation but a
must).
Signed-off-by: Janos Follath <janos.follath@arm.com>
diff --git a/include/mbedtls/rsa.h b/include/mbedtls/rsa.h
index b4c9a04..21432c0 100644
--- a/include/mbedtls/rsa.h
+++ b/include/mbedtls/rsa.h
@@ -976,12 +976,13 @@
* \brief This function performs a PKCS#1 v2.1 PSS signature
* operation (RSASSA-PSS-SIGN).
*
- * \note The \p hash_id in the RSA context is the one used for the
- * encoding. \p md_alg in the function call is the type of hash
- * that is encoded. According to <em>RFC-3447: Public-Key
+ * \note The \c hash_id set in \p ctx by calling
+ * mbedtls_rsa_set_padding() selects the hash used for the
+ * encoding operation and for the mask generation function
+ * (MGF1). For more details on the encoding operation and the
+ * mask generation function, consult <em>RFC-3447: Public-Key
* Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
- * Specifications</em> it is advised to keep both hashes the
- * same.
+ * Specifications</em>.
*
* \note This function enforces that the provided salt length complies
* with FIPS 186-4 §5.5 (e) and RFC 8017 (PKCS#1 v2.2) §9.1.1
@@ -1029,12 +1030,13 @@
* \brief This function performs a PKCS#1 v2.1 PSS signature
* operation (RSASSA-PSS-SIGN).
*
- * \note The \p hash_id in the RSA context is the one used for the
- * encoding. \p md_alg in the function call is the type of hash
- * that is encoded. According to <em>RFC-3447: Public-Key
+ * \note The \c hash_id set in \p ctx by calling
+ * mbedtls_rsa_set_padding() selects the hash used for the
+ * encoding operation and for the mask generation function
+ * (MGF1). For more details on the encoding operation and the
+ * mask generation function, consult <em>RFC-3447: Public-Key
* Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
- * Specifications</em> it is advised to keep both hashes the
- * same.
+ * Specifications</em>.
*
* \note This function always uses the maximum possible salt size,
* up to the length of the payload hash. This choice of salt
@@ -1064,7 +1066,7 @@
* \param md_alg The message-digest algorithm used to hash the original data.
* Use #MBEDTLS_MD_NONE for signing raw data.
* \param hashlen The length of the message digest.
- * Ths is only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * This is only used if \p md_alg is #MBEDTLS_MD_NONE.
* \param hash The buffer holding the message digest or raw data.
* If \p md_alg is #MBEDTLS_MD_NONE, this must be a readable
* buffer of length \p hashlen Bytes. If \p md_alg is not
@@ -1190,16 +1192,15 @@
* \brief This function performs a PKCS#1 v2.1 PSS verification
* operation (RSASSA-PSS-VERIFY).
*
- * The hash function for the MGF mask generating function
- * is that specified in the RSA context.
- *
- * \note The \p hash_id in the RSA context is the one used for the
- * verification. \p md_alg in the function call is the type of
- * hash that is verified. According to <em>RFC-3447: Public-Key
+ * \note The \c hash_id set in \p ctx by calling
+ * mbedtls_rsa_set_padding() selects the hash used for the
+ * encoding operation and for the mask generation function
+ * (MGF1). For more details on the encoding operation and the
+ * mask generation function, consult <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.
+ * Specifications</em>. If the \c hash_id set in \p ctx by
+ * mbedtls_rsa_set_padding() is #MBEDTLS_MD_NONE, the \p md_alg
+ * parameter is used.
*
* \deprecated It is deprecated and discouraged to call this function
* in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
@@ -1247,13 +1248,11 @@
* \brief This function performs a PKCS#1 v2.1 PSS verification
* operation (RSASSA-PSS-VERIFY).
*
- * The hash function for the MGF mask generating function
- * is that specified in \p mgf1_hash_id.
- *
* \note The \p sig buffer must be as large as the size
* of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
*
- * \note The \p hash_id in the RSA context is ignored.
+ * \note The \c hash_id set in \p ctx by mbedtls_rsa_set_padding() is
+ * ignored.
*
* \param ctx The initialized RSA public key context to use.
* \param f_rng The RNG function to use. If \p mode is #MBEDTLS_RSA_PRIVATE,
@@ -1272,7 +1271,13 @@
* buffer of length \p hashlen Bytes. If \p md_alg is not
* #MBEDTLS_MD_NONE, it must be a readable buffer of length
* the size of the hash corresponding to \p md_alg.
- * \param mgf1_hash_id The message digest used for mask generation.
+ * \param mgf1_hash_id The message digest algorithm used for the
+ * verification operation and the mask generation
+ * function (MGF1). For more details on the encoding
+ * operation and the mask generation function, consult
+ * <em>RFC-3447: Public-Key Cryptography Standards
+ * (PKCS) #1 v2.1: RSA Cryptography
+ * Specifications</em>.
* \param expected_salt_len The length of the salt used in padding. Use
* #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length.
* \param sig The buffer holding the signature. This must be a readable