tree 8ba7fb4cbebaf41b64cc7ed83cb8f415d89125f0
parent 8cad2e22fcfe0154f8f9d648cbec81e9fbd0d885
author Janos Follath <janos.follath@arm.com> 1617284657 +0100
committer Janos Follath <janos.follath@arm.com> 1624268344 +0100

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>