PK signature function: require exact hash length

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

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.

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.

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.