lib/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-08-07 06:42:56 +03:00
Code Activity

Merge pull request #5834 from mprse/HKDF_1

Browse Source 
HKDF 1: PSA: implement HKDF_Expand and HKDF_Extract algorithms
This commit is contained in:
Gilles Peskine
2022-06-20 15:27:46 +02:00
committed by GitHub
parent ca3c6a5698 6c9fd61565
commit 36aeb7f163
12 changed files with 636 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
include/psa/crypto_values.h
View File

@@ -1741,6 +1741,12 @@
* You may pass #PSA_KEY_DERIVATION_INPUT_INFO at any time after steup and before
* starting to generate output.
*
* \warning HKDF processes the salt as follows: first hash it with hash_alg
* if the salt is longer than the block size of the hash algorithm; then
* pad with null bytes up to the block size. As a result, it is possible
* for distinct salt inputs to result in the same outputs. To ensure
* unique outputs, it is recommended to use a fixed length for salt values.
*
* \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_HASH(\p hash_alg) is true).
*
@@ -1766,6 +1772,112 @@
#define PSA_ALG_HKDF_GET_HASH(hkdf_alg) \
(PSA_ALG_CATEGORY_HASH | ((hkdf_alg) & PSA_ALG_HASH_MASK))
#define PSA_ALG_HKDF_EXTRACT_BASE ((psa_algorithm_t)0x08000400)
/** Macro to build an HKDF-Extract algorithm.
*
* For example, `PSA_ALG_HKDF_EXTRACT(PSA_ALG_SHA256)` is
* HKDF-Extract using HMAC-SHA-256.
*
* This key derivation algorithm uses the following inputs:
* - PSA_KEY_DERIVATION_INPUT_SALT is the salt.
* - 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.
*
* \warning HKDF-Extract is not meant to be used on its own. PSA_ALG_HKDF
* should be used instead if possible. PSA_ALG_HKDF_EXTRACT is provided
* as a separate algorithm for the sake of protocols that use it as a
* building block. It may also be a slight performance optimization
* in applications that use HKDF with the same salt and key but many
* different info strings.
*
* \warning HKDF processes the salt as follows: first hash it with hash_alg
* if the salt is longer than the block size of the hash algorithm; then
* pad with null bytes up to the block size. As a result, it is possible
* for distinct salt inputs to result in the same outputs. To ensure
* unique outputs, it is recommended to use a fixed length for salt values.
*
* \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_HASH(\p hash_alg) is true).
*
* \return The corresponding HKDF-Extract algorithm.
* \return Unspecified if \p hash_alg is not a supported
* hash algorithm.
*/
#define PSA_ALG_HKDF_EXTRACT(hash_alg) \
(PSA_ALG_HKDF_EXTRACT_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
/** Whether the specified algorithm is an HKDF-Extract algorithm.
*
* HKDF-Extract is a family of key derivation algorithms that are based
* on a hash function and the HMAC construction.
*
* \param alg An algorithm identifier (value of type #psa_algorithm_t).
*
* \return 1 if \c alg is an HKDF-Extract algorithm, 0 otherwise.
* This macro may return either 0 or 1 if \c alg is not a supported
* key derivation algorithm identifier.
*/
#define PSA_ALG_IS_HKDF_EXTRACT(alg) \
(((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_EXTRACT_BASE)
#define PSA_ALG_HKDF_EXPAND_BASE ((psa_algorithm_t)0x08000500)
/** Macro to build an HKDF-Expand algorithm.
*
* For example, `PSA_ALG_HKDF_EXPAND(PSA_ALG_SHA256)` is
* HKDF-Expand using HMAC-SHA-256.
*
* This key derivation algorithm uses the following inputs:
* - PSA_KEY_DERIVATION_INPUT_SECRET is the pseudorandom key (PRK).
* - 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.
*
* \warning HKDF-Expand is not meant to be used on its own. `PSA_ALG_HKDF`
* should be used instead if possible. `PSA_ALG_HKDF_EXPAND` is provided as
* a separate algorithm for the sake of protocols that use it as a building
* block. It may also be a slight performance optimization in applications
* that use HKDF with the same salt and key but many different info strings.
*
* \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_HASH(\p hash_alg) is true).
*
* \return The corresponding HKDF-Expand algorithm.
* \return Unspecified if \p hash_alg is not a supported
* hash algorithm.
*/
#define PSA_ALG_HKDF_EXPAND(hash_alg) \
(PSA_ALG_HKDF_EXPAND_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
/** Whether the specified algorithm is an HKDF-Expand algorithm.
*
* HKDF-Expand is a family of key derivation algorithms that are based
* on a hash function and the HMAC construction.
*
* \param alg An algorithm identifier (value of type #psa_algorithm_t).
*
* \return 1 if \c alg is an HKDF-Expand algorithm, 0 otherwise.
* This macro may return either 0 or 1 if \c alg is not a supported
* key derivation algorithm identifier.
*/
#define PSA_ALG_IS_HKDF_EXPAND(alg) \
(((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_EXPAND_BASE)
/** Whether the specified algorithm is an HKDF or HKDF-Extract or
* HKDF-Expand algorithm.
*
*
* \param alg An algorithm identifier (value of type #psa_algorithm_t).
*
* \return 1 if \c alg is any HKDF type algorithm, 0 otherwise.
* This macro may return either 0 or 1 if \c alg is not a supported
* key derivation algorithm identifier.
*/
#define PSA_ALG_IS_ANY_HKDF(alg) \
(((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_BASE || \
((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_EXTRACT_BASE || \
((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_EXPAND_BASE)
#define PSA_ALG_TLS12_PRF_BASE ((psa_algorithm_t)0x08000200)
/** Macro to build a TLS-1.2 PRF algorithm.
*