From 9dbbc297a393bb129cf2653c2e36501f91d425e2 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 22 Jun 2021 18:28:13 +0200 Subject: [PATCH] PK signature function: require exact hash length Signed-off-by: Gilles Peskine --- ChangeLog.d/require-matching-hashlen-rsa.txt | 7 +++--- .../require-matching-hashlen-rsa.md | 25 +++++++++++++------ include/mbedtls/pk.h | 24 +++++++++--------- 3 files changed, 34 insertions(+), 22 deletions(-) diff --git a/ChangeLog.d/require-matching-hashlen-rsa.txt b/ChangeLog.d/require-matching-hashlen-rsa.txt index d1420d1f9..096b577b5 100644 --- a/ChangeLog.d/require-matching-hashlen-rsa.txt +++ b/ChangeLog.d/require-matching-hashlen-rsa.txt @@ -1,4 +1,5 @@ API changes - * Functions in the RSA module that accept a hashlen parameter now require - it to match the output size of the hash algorithm used, except when - signing raw data. + * Signature functions in the RSA and PK modules now require the hash + length parameter to be the size of the hash input. For RSA signatures + other than raw PKCS#1 v1.5, this must match the output size of the + specified hash algorithm. diff --git a/docs/3.0-migration-guide.d/require-matching-hashlen-rsa.md b/docs/3.0-migration-guide.d/require-matching-hashlen-rsa.md index 75fadd878..d59a8d397 100644 --- a/docs/3.0-migration-guide.d/require-matching-hashlen-rsa.md +++ b/docs/3.0-migration-guide.d/require-matching-hashlen-rsa.md @@ -1,13 +1,24 @@ -RSA signature functions now require `hashlen` to match the expected value -------------------------------------------------------------------------- +Signature functions now require the hash length to match the expected value +--------------------------------------------------------------------------- -This only affects users of the low-level RSA API; users of the high-level PK -API or of the PSA Crypto API are not affected. +This affects users of the PK API as well as users of the low-level API in the RSA module. Users of the PSA API or of the ECDSA module are unaffected. All the functions in the RSA module that accept a `hashlen` parameter used to ignore it unless the `md_alg` parameter was `MBEDTLS_MD_NONE`, indicating raw -data was signed. They now require this parameter's value to be equal to the -output size of the hash algorithm used when signing a hash. (The requirements -when signing raw data are unchanged.) +data was signed. The `hashlen` parameter is now always the size that is read +from the `hash` input buffer. This length must be equal to the output size of +the hash algorithm used when signing a hash. (The requirements when signing +raw data are unchanged.) This affects the following functions: + +* `mbedtls_rsa_pkcs1_sign`, `mbedtls_rsa_pkcs1_verify` +* `mbedtls_rsa_rsassa_pkcs1_v15_sign`, `mbedtls_rsa_rsassa_pkcs1_v15_verify` +* `mbedtls_rsa_rsassa_pss_sign`, `mbedtls_rsa_rsassa_pss_verify` +* `mbedtls_rsa_rsassa_pss_sign_ext`, `mbedtls_rsa_rsassa_pss_verify_ext` + +The signature functions in the PK module no longer accept 0 as the `hash_len` parameter. The `hash_len` parameter is now always the size that is read from the `hash` input buffer. This affects the following functions: + +* `mbedtls_pk_sign`, `mbedtls_pk_verify` +* `mbedtls_pk_sign_restartable`, `mbedtls_pk_verify_restartable` +* `mbedtls_pk_verify_ext` The migration path is to pass the correct value to those functions. diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h index 85bf7c906..d29059dbe 100644 --- a/include/mbedtls/pk.h +++ b/include/mbedtls/pk.h @@ -399,9 +399,17 @@ int mbedtls_pk_can_do( const mbedtls_pk_context *ctx, mbedtls_pk_type_t type ); * \brief Verify signature (including padding if relevant). * * \param ctx The PK context to use. It must have been set up. - * \param md_alg Hash algorithm used (see notes) + * \param md_alg Hash algorithm used. + * This can be #MBEDTLS_MD_NONE if the signature algorithm + * does not rely on a hash algorithm (non-deterministic + * ECDSA, RSA PKCS#1 v1.5). + * For PKCS#1 v1.5, if \p md_alg is #MBEDTLS_MD_NONE, then + * \p hash is the DigestInfo structure used by RFC 8017 + * §9.2 steps 3–6. If \p md_alg is a valid hash + * algorithm then \p hash is the digest itself, and this + * function calculates the DigestInfo encoding internally. * \param hash Hash of the message to sign - * \param hash_len Hash length or 0 (see notes) + * \param hash_len Hash length * \param sig Signature to verify * \param sig_len Signature length * @@ -413,11 +421,6 @@ int mbedtls_pk_can_do( const mbedtls_pk_context *ctx, mbedtls_pk_type_t type ); * \note For RSA keys, the default padding type is PKCS#1 v1.5. * Use \c mbedtls_pk_verify_ext( MBEDTLS_PK_RSASSA_PSS, ... ) * to verify RSASSA_PSS signatures. - * - * \note If hash_len is 0, then the length associated with md_alg - * is used instead, or an error returned if it is invalid. - * - * \note md_alg may be MBEDTLS_MD_NONE, only if hash_len != 0 */ int mbedtls_pk_verify( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hash_len, @@ -490,7 +493,7 @@ int mbedtls_pk_verify_ext( mbedtls_pk_type_t type, const void *options, * with a private key. * \param md_alg Hash algorithm used (see notes) * \param hash Hash of the message to sign - * \param hash_len Hash length or 0 (see notes) + * \param hash_len Hash length * \param sig Place to write the signature. * It must have enough room for the signature. * #MBEDTLS_PK_SIGNATURE_MAX_SIZE is always enough. @@ -507,9 +510,6 @@ int mbedtls_pk_verify_ext( mbedtls_pk_type_t type, const void *options, * There is no interface in the PK module to make RSASSA-PSS * signatures yet. * - * \note If hash_len is 0, then the length associated with md_alg - * is used instead, or an error returned if it is invalid. - * * \note For RSA, md_alg may be MBEDTLS_MD_NONE if hash_len != 0. * For ECDSA, md_alg may never be MBEDTLS_MD_NONE. */ @@ -530,7 +530,7 @@ int mbedtls_pk_sign( mbedtls_pk_context *ctx, mbedtls_md_type_t md_alg, * with a private key. * \param md_alg Hash algorithm used (see notes for mbedtls_pk_sign()) * \param hash Hash of the message to sign - * \param hash_len Hash length or 0 (see notes for mbedtls_pk_sign()) + * \param hash_len Hash length * \param sig Place to write the signature. * It must have enough room for the signature. * #MBEDTLS_PK_SIGNATURE_MAX_SIZE is always enough.