search

ARM-software / psa-api

Documentation source and development of the PSA Certified API
https://arm-software.github.io/psa-api/
Other
56 stars 27 forks source link

Mistaken assumption in HMAC key definition and export format #183

Closed athoelke closed 6 months ago

athoelke commented 6 months ago

While reworking the key formats and derivation methods (see the open issue in #177), I have noticed a long-term anomaly in the specification. HMAC keys describe being truncated on import, based on the block size of the associated hash algorithm. See PSA_KEY_TYPE_HMAC, and also the entry for HMAC keys in Key formats.

The latter is written as if the HMAC key is parameterised:

PSA_KEY_TYPE_HMAC (hash_alg)

For HMAC keys that are shorter than, or equal in size to, the block size of hash_alg, the format is the raw bytes of the key.

HMAC keys that are longer than the block size of hash_alg, are permitted in a call to psa_import_key(). For such a key, the output of psa_export_key() is an implementation defined choice between the following:

  • The raw bytes of the key.
  • The raw bytes of the hash of the key, using hash_alg.

This is clearly wrong. Only the HMAC algorithm is parameterised.

athoelke commented 6 months ago

At the time an HMAC key is constructed, the implementation does not know which Hash will parameterise the algorithm that the key is used with.

Technically, this has to be the same algorithm as the permitted algorithm policy, but up to now, we have only used the policy for authorising use, not for modifying key construction. I do not propose to change this approach for HMAC keys.

We need to revise the documentation about HMAC keys. My suggestion is:

  1. Recommend that applications do not construct long HMAC keys (i.e. longer than the associated hash input block size, due to equivalence with the hash of the key).
  2. Recommend that applications apply the Hash to a key prior to importing it, if it does not control the length of the data used to construct the key.

While providing such guidance, we should also recommend against using keys that are shorter than the associated hash output size.

athoelke commented 6 months ago

I will include a fix for this as part of the reorganisation of the key format and derivation material in v1.3.

Is it important to also fix this as a patch to earlier versions of the specification (e.g. v1.2)?