From ecf65fb2748f60f8107f21377b2e111b80d322e2 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Thu, 14 Mar 2024 09:45:15 +0000 Subject: [PATCH 1/2] Remove dependency on the associated hash from the definition of HMAC keys --- doc/crypto/api/keys/management.rst | 13 +++---------- doc/crypto/api/keys/types.rst | 15 +++++++++++---- doc/crypto/appendix/history.rst | 3 +++ 3 files changed, 17 insertions(+), 14 deletions(-) diff --git a/doc/crypto/api/keys/management.rst b/doc/crypto/api/keys/management.rst index eb907e60..18c68458 100644 --- a/doc/crypto/api/keys/management.rst +++ b/doc/crypto/api/keys/management.rst @@ -549,16 +549,6 @@ 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 @@ -566,6 +556,7 @@ This section defines the format of the key data that an implementation is requir * 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` diff --git a/doc/crypto/api/keys/types.rst b/doc/crypto/api/keys/types.rst index 23c58dca..59162b39 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -117,17 +117,24 @@ 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 input-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 input block size of the hash algorithm that will be used. + + 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 input-block length, before constructing the HMAC key. + This will reduce the size of the stored HMAC key. .. note:: :code:`PSA_HASH_LENGTH(alg)` provides the output size of hash algorithm ``alg``, in bytes. - :code:`PSA_HASH_BLOCK_LENGTH(alg)` provides the block size of hash algorithm ``alg``, in bytes. + :code:`PSA_HASH_BLOCK_LENGTH(alg)` provides the input-block size of hash algorithm ``alg``, in bytes. .. subsection:: Compatible algorithms diff --git a/doc/crypto/appendix/history.rst b/doc/crypto/appendix/history.rst index 8e831c44..2961c84d 100644 --- a/doc/crypto/appendix/history.rst +++ b/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 ~~~~~~~~~~~~~ From 7952f5424e0586d395f7c87467a667885b3fae2b Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Tue, 19 Mar 2024 11:47:41 +0000 Subject: [PATCH 2/2] HMAC key clarifications * Use standard terminology for hash block-size * Indicate that an implementation might not support long HMAC keys --- doc/crypto/api/keys/types.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/crypto/api/keys/types.rst b/doc/crypto/api/keys/types.rst index 59162b39..9eef6fbb 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -123,18 +123,18 @@ Symmetric keys 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 input-block size of the underlying hash algorithm will be hashed before use, see :RFC-title:`2104#2`. + 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`. - It is recommended that an application does not construct HMAC keys that are longer than the input block size of the hash algorithm that will be used. + 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 input-block length, before constructing the HMAC key. - This will reduce the size of the stored HMAC key. + 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:: :code:`PSA_HASH_LENGTH(alg)` provides the output size of hash algorithm ``alg``, in bytes. - :code:`PSA_HASH_BLOCK_LENGTH(alg)` provides the input-block size of hash algorithm ``alg``, in bytes. + :code:`PSA_HASH_BLOCK_LENGTH(alg)` provides the block size of hash algorithm ``alg``, in bytes. .. subsection:: Compatible algorithms