From e713b3d863bbef7180644d390aa73e3a2d7dfa7d Mon Sep 17 00:00:00 2001 From: Armin Wolf Date: Thu, 3 Oct 2024 23:16:25 +0200 Subject: [PATCH] sys/psa_crypto: Add HKDF-Extract/-Expand key derivation algorithms The PSA crypto API specification 1.1.1 introduced two new algorithms for HKDF. Add support for those. Signed-off-by: Armin Wolf --- .../psa_crypto/psa/key_derivation/algorithm.h | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) diff --git a/sys/include/psa_crypto/psa/key_derivation/algorithm.h b/sys/include/psa_crypto/psa/key_derivation/algorithm.h index fadc925f9f..730b235b3d 100644 --- a/sys/include/psa_crypto/psa/key_derivation/algorithm.h +++ b/sys/include/psa_crypto/psa/key_derivation/algorithm.h @@ -73,6 +73,28 @@ extern "C" { #define PSA_ALG_IS_HKDF(alg) \ (((alg) & ~0x000000ff) == 0x08000100) +/** + * @brief Whether the specified algorithm is an HKDF-Extract algorithm. + * + * @param alg An algorithm identifier: a value of type @ref psa_algorithm_t. + * + * @return 1 if alg is an HKDF-Extract algorithm + * 0 otherwise + */ +#define PSA_ALG_IS_HKDF_EXTRACT(alg) \ + (((alg) & ~0x000000ff) == 0x08000400) + +/** + * @brief Whether the specified algorithm is an HKDF-Expand algorithm. + * + * @param alg An algorithm identifier: a value of type @ref psa_algorithm_t. + * + * @return 1 if alg is an HKDF-Expand algorithm + * 0 otherwise + */ +#define PSA_ALG_IS_HKDF_EXPAND(alg) \ + (((alg) & ~0x000000ff) == 0x08000500) + /** * @brief Whether the specified algorithm is a TLS-1.2 PRF algorithm. * @@ -137,6 +159,59 @@ extern "C" { */ #define PSA_ALG_HKDF(hash_alg) ((psa_algorithm_t)(0x08000100 | ((hash_alg) & 0x000000ff))) +/** + * @brief Macro to build an HKDF-Extract algorithm. + * + * @details This is the Extract step of HKDF as specified by + * HMAC-based Extract-and-Expand Key Derivation Function (HKDF) [RFC5869] §2.2. + * + * This key derivation algorithm uses the following inputs: + * - @ref PSA_KEY_DERIVATION_INPUT_SALT is the salt. + * - @ref PSA_KEY_DERIVATION_INPUT_SECRET is the input keying material used + * in the “extract” step. + * + * The inputs are mandatory and must be passed in the order above. + * Each input may only be passed once. + * + * @b Compatible @b key @b types + * - @ref PSA_KEY_TYPE_DERIVE (for the input keying material) + * - @ref PSA_KEY_TYPE_RAW_DATA (for the salt) + * + * @param hash_alg A hash algorithm: a value of type @ref psa_algorithm_t such that + * @ref PSA_ALG_IS_HASH(@p hash_alg) is true. + * + * @return The corresponding HKDF-Extract algorithm. For example, + * @ref PSA_ALG_HKDF_EXTRACT(@ref PSA_ALG_SHA_256) is HKDF-Extract using HMAC-SHA-256. + * Unspecified if @c hash_alg is not a supported hash algorithm. + */ +#define PSA_ALG_HKDF_EXTRACT(hash_alg) ((psa_algorithm_t)(0x08000400 | ((hash_alg) & 0x000000ff))) + +/** + * @brief Macro to build an HKDF-Expand algorithm. + * + * @details This is the Expand step of HKDF as specified by + * HMAC-based Extract-and-Expand Key Derivation Function (HKDF) [RFC5869] §2.3. + * + * This key derivation algorithm uses the following inputs: + * - @ref PSA_KEY_DERIVATION_INPUT_SECRET is the pseudoramdom key (PRK). + * - @ref PSA_KEY_DERIVATION_INPUT_INFO is the info string. + * + * The inputs are mandatory and must be passed in the order above. + * Each input may only be passed once. + * + * @b Compatible @b key @b types + * - @ref PSA_KEY_TYPE_DERIVE (for the pseudorandom key) + * - @ref PSA_KEY_TYPE_RAW_DATA (for the info string) + * + * @param hash_alg A hash algorithm: a value of type @ref psa_algorithm_t such that + * @ref PSA_ALG_IS_HASH(@p hash_alg) is true. + * + * @return The corresponding HKDF-Expand algorithm. For example, + * @ref PSA_ALG_HKDF_EXPAND(@ref PSA_ALG_SHA_256) is HKDF-Expand using HMAC-SHA-256. + * Unspecified if @c hash_alg is not a supported hash algorithm. + */ +#define PSA_ALG_HKDF_EXPAND(hash_alg) ((psa_algorithm_t)(0x08000500 | ((hash_alg) & 0x000000ff))) + /** * @brief Macro to build a TLS-1.2 PRF algorithm. *