lib/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-07-29 11:41:15 +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

2
include/psa/crypto_config.h
View File

@ -67,6 +67,8 @@
#define PSA_WANT_ALG_ECDSA 1
#define PSA_WANT_ALG_GCM 1
#define PSA_WANT_ALG_HKDF 1
#define PSA_WANT_ALG_HKDF_EXTRACT 1
#define PSA_WANT_ALG_HKDF_EXPAND 1
#define PSA_WANT_ALG_HMAC 1
#define PSA_WANT_ALG_MD5 1
#define PSA_WANT_ALG_OFB 1

12
include/psa/crypto_struct.h
View File

@ -181,7 +181,9 @@ static inline struct psa_aead_operation_s psa_aead_operation_init( void )
return( v );
}
#if defined(MBEDTLS_PSA_BUILTIN_ALG_HKDF)
#if defined(MBEDTLS_PSA_BUILTIN_ALG_HKDF) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_HKDF_EXTRACT) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_HKDF_EXPAND)
typedef struct
{
uint8_t *MBEDTLS_PRIVATE(info);
@ -197,7 +199,9 @@ typedef struct
uint8_t MBEDTLS_PRIVATE(prk)[PSA_HASH_MAX_SIZE];
struct psa_mac_operation_s MBEDTLS_PRIVATE(hmac);
} psa_hkdf_key_derivation_t;
#endif /* MBEDTLS_PSA_BUILTIN_ALG_HKDF */
#endif /* MBEDTLS_PSA_BUILTIN_ALG_HKDF ||
MBEDTLS_PSA_BUILTIN_ALG_HKDF_EXTRACT ||
MBEDTLS_PSA_BUILTIN_ALG_HKDF_EXPAND */
#if defined(MBEDTLS_PSA_BUILTIN_ALG_TLS12_PRF) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_TLS12_PSK_TO_MS)
@ -254,7 +258,9 @@ struct psa_key_derivation_s
{
/* Make the union non-empty even with no supported algorithms. */
uint8_t MBEDTLS_PRIVATE(dummy);
#if defined(MBEDTLS_PSA_BUILTIN_ALG_HKDF)
#if defined(MBEDTLS_PSA_BUILTIN_ALG_HKDF) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_HKDF_EXTRACT) || \
defined(MBEDTLS_PSA_BUILTIN_ALG_HKDF_EXPAND)
psa_hkdf_key_derivation_t MBEDTLS_PRIVATE(hkdf);
#endif
#if defined(MBEDTLS_PSA_BUILTIN_ALG_TLS12_PRF) || \

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.
*