From 456d7e055fef7393dcda4183a9151f197724f685 Mon Sep 17 00:00:00 2001 From: Janos Follath Date: Thu, 1 Apr 2021 14:44:17 +0100 Subject: [PATCH] mbedtls_rsa_rsassa_pss_*: improve documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- include/mbedtls/rsa.h | 55 +++++++++++++++++++++++-------------------- 1 file changed, 30 insertions(+), 25 deletions(-) diff --git a/include/mbedtls/rsa.h b/include/mbedtls/rsa.h index b4c9a042a6..21432c0090 100644 --- a/include/mbedtls/rsa.h +++ b/include/mbedtls/rsa.h @@ -976,12 +976,13 @@ int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx, * \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 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 RFC-3447: Public-Key * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography - * Specifications it is advised to keep both hashes the - * same. + * Specifications. * * \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 @@ int mbedtls_rsa_rsassa_pss_sign_ext( mbedtls_rsa_context *ctx, * \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 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 RFC-3447: Public-Key * Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography - * Specifications it is advised to keep both hashes the - * same. + * Specifications. * * \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 @@ int mbedtls_rsa_rsassa_pss_sign_ext( mbedtls_rsa_context *ctx, * \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 @@ int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx, * \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 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 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. + * Specifications. 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 @@ int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx, * \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 @@ int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx, * 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 + * RFC-3447: Public-Key Cryptography Standards + * (PKCS) #1 v2.1: RSA Cryptography + * Specifications. * \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