Remove dependency on the associated hash from the definition of HMAC keys

doc/crypto/api/keys/management.rst

@@ -549,23 +549,14 @@ This section defines the format of the key data that an implementation is requir
 
             The key data is the concatenation of the two or three DES keys.
 
-    *   -   HMAC
-        -   :code:`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 :scterm:`implementation defined` choice between the following:
-
-            1.  The raw bytes of the key.
-            #.  The raw bytes of the hash of the key, using ``hash_alg``.
-
     *   -   Other symmetric keys
 
             *   AES
             *   ARC4
             *   ARIA
             *   CAMELLIA
             *   ChaCha20
+            *   HMAC
             *   SM4
             *   Secrets for derivation
             *   Password hashes
@@ -580,6 +571,8 @@ This section defines the format of the key data that an implementation is requir
 
             `PSA_KEY_TYPE_CHACHA20`
 
+            `PSA_KEY_TYPE_HMAC`
+
             `PSA_KEY_TYPE_SM4`
 
             `PSA_KEY_TYPE_DERIVE`

doc/crypto/api/keys/types.rst

@@ -117,11 +117,18 @@ Symmetric keys
     .. summary::
         HMAC key.
 
-    The key policy determines which underlying hash algorithm the key can be used for.
+    HMAC keys can be used in HMAC, or HMAC-based, algorithms.
+    Although HMAC is parameterized by a specific hash algorithm, for example SHA-256, the hash algorithm is not specified in the key type.
+    The permitted-algorithm policy for the key must specify a particular hash algorithm.
 
-    The bit size of an HMAC key must be a non-zero multiple of 8. An HMAC key is typically the same size as the output of the underlying hash algorithm. An HMAC key that is longer than the block size of the underlying hash algorithm will be hashed before use.
+    The bit size of an HMAC key must be a non-zero multiple of 8.
+    An HMAC key is typically the same size as the output of the underlying hash algorithm.
+    An HMAC key that is longer than the block size of the underlying hash algorithm will be hashed before use, see :RFC-title:`2104#2`.
 
-    When an HMAC key is created that is longer than the block size, it is :scterm:`implementation defined` whether the implementation stores the original HMAC key, or the hash of the HMAC key. If the hash of the key is stored, the key size reported by `psa_get_key_attributes()` will be the size of the hashed key.
+    It is recommended that an application does not construct HMAC keys that are longer than the block size of the hash algorithm that will be used.
+    It is :scterm:`implementation defined` whether an HMAC key that is longer than the hash block size is supported.
+
+    If the application does not control the length of the data used to construct the HMAC key, it is recommended that the application hashes the key data, when it exceeds the hash block length, before constructing the HMAC key.
 
     .. note::
 

doc/crypto/appendix/history.rst

@@ -18,6 +18,9 @@ Clarifications and fixes
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 *   Fix the example implementation of `PSA_ALG_KEY_AGREEMENT_GET_BASE()` and `PSA_ALG_KEY_AGREEMENT_GET_KDF()` in :secref:`appendix-specdef-values`, to give correct results for key agreements combined with PBKDF2.
+*   Remove the dependency on the underlying hash algorithm in definition of HMAC keys, and their behavior on import and export.
+    Transferred the responsibility for truncating over-sized HMAC keys to the application.
+    See `PSA_KEY_TYPE_HMAC`.
 
 Other changes
 ~~~~~~~~~~~~~