Key derivation algorithm definitions for the PSA Crypto API. More...

Detailed Description

Key derivation algorithm definitions for the PSA Crypto API.

Author: Armin Wolf wolf..nosp@m.armi.nosp@m.n@mai.nosp@m.lbox.nosp@m..tu-d.nosp@m.resd.nosp@m.en.de; Lena Boeckmann lena..nosp@m.boec.nosp@m.kmann.nosp@m.@haw.nosp@m.-hamb.nosp@m.urg..nosp@m.de

Definition in file algorithm.h.

#include "psa/algorithm.h"

Include dependency graph for algorithm.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

#define	PSA_ALG_CATEGORY_KEY_DERIVATION ((psa_algorithm_t)0x08000000)
	Category for key derivation algorithms.

#define	PSA_ALG_IS_KEY_DERIVATION(alg) (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_DERIVATION)
	Whether the specified algorithm is a key derivation algorithm.

#define	PSA_ALG_IS_KEY_DERIVATION_STRETCHING(alg) (((alg) & 0x7f800000) == 0x08800000)
	Whether the specified algorithm is a key-stretching or password-hashing algorithm.

#define	PSA_ALG_IS_HKDF(alg) (((alg) & ~0x000000ff) == 0x08000100)
	Whether the specified algorithm is an HKDF algorithm.

#define	PSA_ALG_IS_HKDF_EXTRACT(alg) (((alg) & ~0x000000ff) == 0x08000400)
	Whether the specified algorithm is an HKDF-Extract algorithm.

#define	PSA_ALG_IS_HKDF_EXPAND(alg) (((alg) & ~0x000000ff) == 0x08000500)
	Whether the specified algorithm is an HKDF-Expand algorithm.

#define	PSA_ALG_IS_TLS12_PRF(alg) (((alg) & ~0x000000ff) == 0x08000200)
	Whether the specified algorithm is a TLS-1.2 PRF algorithm.

#define	PSA_ALG_IS_TLS12_PSK_TO_MS(alg) (((alg) & ~0x000000ff) == 0x08000300)
	Whether the specified algorithm is a TLS-1.2 PSK to MS algorithm.

#define	PSA_ALG_IS_PBKDF2_HMAC(alg) (((alg) & ~0x000000ff) == 0x08800100)
	Whether the specified algorithm is a PBKDF2-HMAC algorithm.

#define	PSA_ALG_HKDF(hash_alg) ((psa_algorithm_t)(0x08000100 \| ((hash_alg) & 0x000000ff)))
	Macro to build an HKDF algorithm.

#define	PSA_ALG_HKDF_EXTRACT(hash_alg) ((psa_algorithm_t)(0x08000400 \| ((hash_alg) & 0x000000ff)))
	Macro to build an HKDF-Extract algorithm.

#define	PSA_ALG_HKDF_EXPAND(hash_alg) ((psa_algorithm_t)(0x08000500 \| ((hash_alg) & 0x000000ff)))
	Macro to build an HKDF-Expand algorithm.

#define	PSA_ALG_TLS12_PRF(hash_alg) ((psa_algorithm_t)(0x08000200 \| ((hash_alg) & 0x000000ff)))
	Macro to build a TLS-1.2 PRF algorithm.

#define	PSA_ALG_TLS12_PSK_TO_MS(hash_alg) ((psa_algorithm_t)(0x08000300 \| ((hash_alg) & 0x000000ff)))
	Macro to build a TLS-1.2 PSK-to-MasterSecret algorithm.

#define	PSA_ALG_PBKDF2_HMAC(hash_alg) ((psa_algorithm_t)(0x08800100 \| ((hash_alg) & 0x000000ff)))
	Macro to build a PBKDF2-HMAC password-hashing or key-stretching algorithm.

#define	PSA_ALG_PBKDF2_AES_CMAC_PRF_128 ((psa_algorithm_t)0x08800200)
	The PBKDF2-AES-CMAC-PRF-128 password-hashing or key-stretching algorithm.

Macro Definition Documentation

◆ PSA_ALG_CATEGORY_KEY_DERIVATION

#define PSA_ALG_CATEGORY_KEY_DERIVATION ((psa_algorithm_t)0x08000000)

Category for key derivation algorithms.

Definition at line 34 of file algorithm.h.

◆ PSA_ALG_HKDF

#define PSA_ALG_HKDF ( hash_alg ) ((psa_algorithm_t)(0x08000100 | ((hash_alg) & 0x000000ff)))

Macro to build an HKDF algorithm.

This is the HMAC-based Extract-and-Expand Key Derivation Function (HKDF) specified by HMAC-based Extract-and-Expand Key Derivation Function (HKDF) [RFC5869].

This key derivation algorithm uses the following inputs:

PSA_KEY_DERIVATION_INPUT_SALT is the salt used in the “extract” step. It is optional; if omitted, the derivation uses an empty salt.
PSA_KEY_DERIVATION_INPUT_INFO is the info string used in the “expand” step.
PSA_KEY_DERIVATION_INPUT_SECRET is the secret key used in the “extract” step.

If PSA_KEY_DERIVATION_INPUT_SALT is provided, it must be before PSA_KEY_DERIVATION_INPUT_SECRET. PSA_KEY_DERIVATION_INPUT_INFO can be provided at any time after setup and before starting to generate output.

Each input may only be passed once.

Compatible key types

PSA_KEY_TYPE_DERIVE (for the secret key)
PSA_KEY_TYPE_RAW_DATA (for the other inputs)

Parameters

hash_alg A hash algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_HASH(hash_alg) is true.

Returns: The corresponding HKDF algorithm. For example, PSA_ALG_HKDF(PSA_ALG_SHA_256) is HKDF using HMAC-SHA-256. Unspecified if hash_alg is not a supported hash algorithm.

Definition at line 160 of file algorithm.h.

◆ PSA_ALG_HKDF_EXPAND

#define PSA_ALG_HKDF_EXPAND ( hash_alg ) ((psa_algorithm_t)(0x08000500 | ((hash_alg) & 0x000000ff)))

Macro to build an HKDF-Expand algorithm.

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:

PSA_KEY_DERIVATION_INPUT_SECRET is the pseudoramdom 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.

Compatible key types

PSA_KEY_TYPE_DERIVE (for the pseudorandom key)
PSA_KEY_TYPE_RAW_DATA (for the info string)

Parameters

hash_alg A hash algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_HASH(hash_alg) is true.

Returns: The corresponding HKDF-Expand algorithm. For example, PSA_ALG_HKDF_EXPAND(PSA_ALG_SHA_256) is HKDF-Expand using HMAC-SHA-256. Unspecified if hash_alg is not a supported hash algorithm.

Definition at line 213 of file algorithm.h.

◆ PSA_ALG_HKDF_EXTRACT

#define PSA_ALG_HKDF_EXTRACT ( hash_alg ) ((psa_algorithm_t)(0x08000400 | ((hash_alg) & 0x000000ff)))

Macro to build an HKDF-Extract algorithm.

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:

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.

Compatible key types

PSA_KEY_TYPE_DERIVE (for the input keying material)
PSA_KEY_TYPE_RAW_DATA (for the salt)

Parameters

hash_alg A hash algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_HASH(hash_alg) is true.

Returns: The corresponding HKDF-Extract algorithm. For example, PSA_ALG_HKDF_EXTRACT(PSA_ALG_SHA_256) is HKDF-Extract using HMAC-SHA-256. Unspecified if hash_alg is not a supported hash algorithm.

Definition at line 187 of file algorithm.h.

◆ PSA_ALG_IS_HKDF

#define PSA_ALG_IS_HKDF ( alg ) (((alg) & ~0x000000ff) == 0x08000100)

Whether the specified algorithm is an HKDF algorithm.

HKDF is a family of key derivation algorithms that are based on a hash function and the HMAC construction.

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns: 1 if alg is an HKDF algorithm 0 otherwise

Definition at line 73 of file algorithm.h.

◆ PSA_ALG_IS_HKDF_EXPAND

#define PSA_ALG_IS_HKDF_EXPAND ( alg ) (((alg) & ~0x000000ff) == 0x08000500)

Whether the specified algorithm is an HKDF-Expand algorithm.

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns: 1 if alg is an HKDF-Expand algorithm 0 otherwise

Definition at line 95 of file algorithm.h.

◆ PSA_ALG_IS_HKDF_EXTRACT

#define PSA_ALG_IS_HKDF_EXTRACT ( alg ) (((alg) & ~0x000000ff) == 0x08000400)

Whether the specified algorithm is an HKDF-Extract algorithm.

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns: 1 if alg is an HKDF-Extract algorithm 0 otherwise

Definition at line 84 of file algorithm.h.

◆ PSA_ALG_IS_KEY_DERIVATION

#define PSA_ALG_IS_KEY_DERIVATION ( alg ) (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_DERIVATION)

Whether the specified algorithm is a key derivation algorithm.

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns: 1 if alg is a key derivation algorithm 0 otherwise

Definition at line 44 of file algorithm.h.

◆ PSA_ALG_IS_KEY_DERIVATION_STRETCHING

#define PSA_ALG_IS_KEY_DERIVATION_STRETCHING ( alg ) (((alg) & 0x7f800000) == 0x08800000)

Whether the specified algorithm is a key-stretching or password-hashing algorithm.

A key-stretching or password-hashing algorithm is a key derivation algorithm that is suitable for use with a low-entropy secret such as a password. Equivalently, it’s a key derivation algorithm that uses a PSA_KEY_DERIVATION_INPUT_PASSWORD input step.

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns: 1 if alg is a key-stretching or password-hashing algorithm 0 otherwise

Definition at line 59 of file algorithm.h.

◆ PSA_ALG_IS_PBKDF2_HMAC

#define PSA_ALG_IS_PBKDF2_HMAC ( alg ) (((alg) & ~0x000000ff) == 0x08800100)

Whether the specified algorithm is a PBKDF2-HMAC algorithm.

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns: 1 if alg is a PBKDF2-HMAC algorithm 0 otherwise

Definition at line 128 of file algorithm.h.

◆ PSA_ALG_IS_TLS12_PRF

#define PSA_ALG_IS_TLS12_PRF ( alg ) (((alg) & ~0x000000ff) == 0x08000200)

Whether the specified algorithm is a TLS-1.2 PRF algorithm.

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns: 1 if alg is a TLS-1.2 PRF algorithm 0 otherwise

Definition at line 106 of file algorithm.h.

◆ PSA_ALG_IS_TLS12_PSK_TO_MS

#define PSA_ALG_IS_TLS12_PSK_TO_MS ( alg ) (((alg) & ~0x000000ff) == 0x08000300)

Whether the specified algorithm is a TLS-1.2 PSK to MS algorithm.

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns: 1 if alg is a TLS-1.2 PSK to MS algorithm 0 otherwise

Definition at line 117 of file algorithm.h.

◆ PSA_ALG_PBKDF2_AES_CMAC_PRF_128

#define PSA_ALG_PBKDF2_AES_CMAC_PRF_128 ((psa_algorithm_t)0x08800200)

The PBKDF2-AES-CMAC-PRF-128 password-hashing or key-stretching algorithm.

PBKDF2 is specified by PKCS #5: Password-Based Cryptography Specification Version 2.1 RFC8018 §5.2. This algorithm specifies the PBKDF2 algorithm using the AES-CMAC-PRF-128 pseudo-random function specified by RFC4615.

This key derivation algorithm uses the same inputs as PSA_ALG_PBKDF2_HMAC() with the same constraints.

Compatible key types

PSA_KEY_TYPE_DERIVE (for password input)
PSA_KEY_TYPE_PASSWORD (for password input)
PSA_KEY_TYPE_PEPPER (for salt input)
PSA_KEY_TYPE_RAW_DATA (for salt input)
PSA_KEY_TYPE_PASSWORD_HASH (for key verification)

Definition at line 335 of file algorithm.h.

◆ PSA_ALG_PBKDF2_HMAC

#define PSA_ALG_PBKDF2_HMAC ( hash_alg ) ((psa_algorithm_t)(0x08800100 | ((hash_alg) & 0x000000ff)))

Macro to build a PBKDF2-HMAC password-hashing or key-stretching algorithm.

PBKDF2 is specified by PKCS #5: Password-Based Cryptography Specification Version 2.1 RFC8018 §5.2. This macro constructs a PBKDF2 algorithm that uses a pseudo-random function based on HMAC with the specified hash.

This key derivation algorithm uses the following inputs, which must be provided in the following order:

PSA_KEY_DERIVATION_INPUT_COST is the iteration count. This input step must be used exactly once.
PSA_KEY_DERIVATION_INPUT_SALT is the salt. This input step must be used one or more times; if used several times, the inputs will be concatenated. This can be used to build the final salt from multiple sources, both public and secret (also known as pepper).
PSA_KEY_DERIVATION_INPUT_PASSWORD is the password to be hashed. This input step must be used exactly once.

Compatible key types

PSA_KEY_TYPE_DERIVE (for password input)
PSA_KEY_TYPE_PASSWORD (for password input)
PSA_KEY_TYPE_PEPPER (for salt input)
PSA_KEY_TYPE_RAW_DATA (for salt input)
PSA_KEY_TYPE_PASSWORD_HASH (for key verification)

Parameters

hash_alg A hash algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_HASH(hash_alg) is true.

Returns: The corresponding PBKDF2-HMAC-XXX algorithm. For example, PSA_ALG_PBKDF2_HMAC(PSA_ALG_SHA_256) is the algorithm identifier for PBKDF2-HMAC-SHA-256. Unspecified if hash_alg is not a supported hash algorithm.

Definition at line 314 of file algorithm.h.

◆ PSA_ALG_TLS12_PRF

#define PSA_ALG_TLS12_PRF ( hash_alg ) ((psa_algorithm_t)(0x08000200 | ((hash_alg) & 0x000000ff)))

Macro to build a TLS-1.2 PRF algorithm.

TLS 1.2 uses a custom pseudorandom function (PRF) for key schedule, specified in The Transport Layer Security (TLS) Protocol Version 1.2 RFC5246 §5. It is based on HMAC and can be used with either SHA-256 or SHA-384.

This key derivation algorithm uses the following inputs, which must be passed in the order given here:

PSA_KEY_DERIVATION_INPUT_SEED is the seed.
PSA_KEY_DERIVATION_INPUT_SECRET is the secret key.
PSA_KEY_DERIVATION_INPUT_LABEL is the label.

Each input may only be passed once.

For the application to TLS-1.2 key expansion:

The seed is the concatenation of ServerHello.Random + ClientHello.Random.
The label is key expansion.

Compatible key types

PSA_KEY_TYPE_DERIVE (for the secret key)
PSA_KEY_TYPE_RAW_DATA (for the other inputs)

Parameters

hash_alg A hash algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_HASH(hash_alg) is true.

Returns: The corresponding TLS-1.2 PRF algorithm. For example, PSA_ALG_TLS12_PRF(PSA_ALG_SHA_256) represents the TLS 1.2 PRF using HMAC-SHA-256. Unspecified if hash_alg is not a supported hash algorithm.

Definition at line 247 of file algorithm.h.

◆ PSA_ALG_TLS12_PSK_TO_MS

#define PSA_ALG_TLS12_PSK_TO_MS ( hash_alg ) ((psa_algorithm_t)(0x08000300 | ((hash_alg) & 0x000000ff)))

Macro to build a TLS-1.2 PSK-to-MasterSecret algorithm.

In a pure-PSK handshake in TLS 1.2, the master secret (MS) is derived from the pre-shared key (PSK) through the application of padding (Pre-Shared Key Ciphersuites for Transport Layer Security (TLS) RFC4279 §2) and the TLS-1.2 PRF (The Transport Layer Security (TLS) Protocol Version 1.2 RFC5246 §5). The latter is based on HMAC and can be used with either SHA-256 or SHA-384.

This key derivation algorithm uses the following inputs, which must be passed in the order given here:

PSA_KEY_DERIVATION_INPUT_SEED is the seed.
PSA_KEY_DERIVATION_INPUT_SECRET is the PSK. The PSK must not be larger than PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE.
PSA_KEY_DERIVATION_INPUT_LABEL is the label.

Each input may only be passed once.

For the application to TLS-1.2:

The seed, which is forwarded to the TLS-1.2 PRF, is the concatenation of the ClientHello.Random + ServerHello.Random.
The label is "master secret" or "extended master secret".

Compatible key types

PSA_KEY_TYPE_DERIVE (for the PSK)
PSA_KEY_TYPE_RAW_DATA (for the other inputs)

Definition at line 277 of file algorithm.h.