10.6. Key derivation

A key derivation encodes a deterministic method to generate a finite stream of bytes. This data stream is computed by the cryptoprocessor and extracted in chunks. If two key derivation operations are constructed with the same parameters, then they produce the same output.

A key derivation consists of two phases:

  1. Input collection. This is sometimes known as extraction: the operation “extracts” information from the inputs to generate a pseudorandom intermediate secret value.

  2. Output generation. This is sometimes known as expansion: the operation “expands” the intermediate secret value to the desired output length.

The specification defines a multi-part operation API for key derivation that allows:

  • Multiple key and non-key outputs to be produced from a single derivation operation object.

  • Key and non-key outputs can be extracted from the key derivation object, or compared with existing key and non-key values.

  • Algorithms that require high-entropy secret inputs. For example PSA_ALG_HKDF.

  • Algorithms that work with low-entropy secret inputs, or passwords. For example PSA_ALG_PBKDF2_HMAC().

An implementation with isolation has the following properties:

  • The intermediate state of the key derivation is not visible to the caller.

  • If an output of the derivation is a non-exportable key, then this key cannot be recovered outside the isolation boundary.

  • If an output of the derivation is compared using psa_key_derivation_verify_bytes() or psa_key_derivation_verify_key(), then the output is not visible to the caller.

Applications use the psa_key_derivation_operation_t type to create key derivation operations. The operation object is used as follows:

  1. Initialize a psa_key_derivation_operation_t object to zero or to PSA_KEY_DERIVATION_OPERATION_INIT.

  2. Call psa_key_derivation_setup() to select a key derivation algorithm.

  3. Call the functions psa_key_derivation_input_key() or psa_key_derivation_key_agreement() to provide the secret inputs, and psa_key_derivation_input_bytes() or psa_key_derivation_input_integer() to provide the non-secret inputs, to the key derivation algorithm. Many key derivation algorithms take multiple inputs; the step parameter to these functions indicates which input is being provided. The documentation for each key derivation algorithm describes the expected inputs for that algorithm and in what order to pass them.

  4. Optionally, call psa_key_derivation_set_capacity() to set a limit on the amount of data that can be output from the key derivation operation.

  5. Call an output or verification function:

    These functions can be called multiple times to read successive output from the key derivation, until the stream is exhausted when its capacity has been reached.

  6. Key derivation does not finish in the same way as other multi-part operations. Call psa_key_derivation_abort() to release the key derivation operation memory when the object is no longer required.

To recover from an error, call psa_key_derivation_abort() to release the key derivation operation memory.

A key derivation operation cannot be rewound. Once a part of the stream has been output, it cannot be output again. This ensures that the same part of the output will not be used for different purposes.

10.6.1. Key derivation algorithms

PSA_ALG_HKDF (macro)

Macro to build an HKDF algorithm.

#define PSA_ALG_HKDF(hash_alg) /* specification-defined value */

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.

Description

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:

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.

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.

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)

PSA_ALG_HKDF_EXTRACT (macro)

Macro to build an HKDF-Extract algorithm.

#define PSA_ALG_HKDF_EXTRACT(hash_alg) /* specification-defined value */

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.

Description

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:

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.

Compatible key types

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

PSA_ALG_HKDF_EXPAND (macro)

Macro to build an HKDF-Expand algorithm.

#define PSA_ALG_HKDF_EXPAND(hash_alg) /* specification-defined value */

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.

Description

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:

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.

Compatible key types

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

PSA_ALG_TLS12_PRF (macro)

Macro to build a TLS-1.2 PRF algorithm.

#define PSA_ALG_TLS12_PRF(hash_alg) /* specification-defined value */

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.

Description

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:

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)

PSA_ALG_TLS12_PSK_TO_MS (macro)

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

#define PSA_ALG_TLS12_PSK_TO_MS(hash_alg) /* specification-defined value */

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 PSK to MS algorithm. For example, PSA_ALG_TLS12_PSK_TO_MS(PSA_ALG_SHA_256) represents the TLS-1.2 PSK to MasterSecret derivation PRF using HMAC-SHA-256.

Unspecified if hash_alg is not a supported hash algorithm.

Description

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:

Each input may only be passed once.

For the application to TLS-1.2:

Compatible key types

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

PSA_ALG_PBKDF2_HMAC (macro)

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

#define PSA_ALG_PBKDF2_HMAC(hash_alg) /* specification-defined value */

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.

Description

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)

PSA_ALG_PBKDF2_AES_CMAC_PRF_128 (macro)

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

#define PSA_ALG_PBKDF2_AES_CMAC_PRF_128 ((psa_algorithm_t)0x08800200)

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)

10.6.2. Input step types

psa_key_derivation_step_t (typedef)

Encoding of the step of a key derivation.

typedef uint16_t psa_key_derivation_step_t;

PSA_KEY_DERIVATION_INPUT_SECRET (macro)

A high-entropy secret input for key derivation.

#define PSA_KEY_DERIVATION_INPUT_SECRET /* implementation-defined value */

This is typically a key of type PSA_KEY_TYPE_DERIVE passed to psa_key_derivation_input_key(), or the shared secret resulting from a key agreement obtained via psa_key_derivation_key_agreement().

The secret can also be a direct input passed to psa_key_derivation_input_bytes(). In this case, the derivation operation cannot be used to derive keys: the operation will not permit a call to psa_key_derivation_output_key().

PSA_KEY_DERIVATION_INPUT_OTHER_SECRET (macro)

A high-entropy additional secret input for key derivation.

#define PSA_KEY_DERIVATION_INPUT_OTHER_SECRET \
    /* implementation-defined value */

This is typically the shared secret resulting from a key agreement obtained via psa_key_derivation_key_agreement(). It may alternatively be a key of type PSA_KEY_TYPE_DERIVE passed to psa_key_derivation_input_key(), or a direct input passed to psa_key_derivation_input_bytes().

PSA_KEY_DERIVATION_INPUT_PASSWORD (macro)

A low-entropy secret input for password hashing or key stretching.

#define PSA_KEY_DERIVATION_INPUT_PASSWORD /* implementation-defined value */

This is usually a key of type PSA_KEY_TYPE_PASSWORD passed to psa_key_derivation_input_key() or a direct input passed to psa_key_derivation_input_bytes() that is a password or passphrase. It can also be high-entropy secret, for example, a key of type PSA_KEY_TYPE_DERIVE, or the shared secret resulting from a key agreement.

If the secret is a direct input, the derivation operation cannot be used to derive keys: the operation will not permit a call to psa_key_derivation_output_key().

PSA_KEY_DERIVATION_INPUT_LABEL (macro)

A label for key derivation.

#define PSA_KEY_DERIVATION_INPUT_LABEL /* implementation-defined value */

This is typically a direct input. It can also be a key of type PSA_KEY_TYPE_RAW_DATA.

PSA_KEY_DERIVATION_INPUT_CONTEXT (macro)

A context for key derivation.

#define PSA_KEY_DERIVATION_INPUT_CONTEXT /* implementation-defined value */

This is typically a direct input. It can also be a key of type PSA_KEY_TYPE_RAW_DATA.

PSA_KEY_DERIVATION_INPUT_SALT (macro)

A salt for key derivation.

#define PSA_KEY_DERIVATION_INPUT_SALT /* implementation-defined value */

This is typically a direct input. It can also be a key of type PSA_KEY_TYPE_RAW_DATA or PSA_KEY_TYPE_PEPPER.

PSA_KEY_DERIVATION_INPUT_INFO (macro)

An information string for key derivation.

#define PSA_KEY_DERIVATION_INPUT_INFO /* implementation-defined value */

This is typically a direct input. It can also be a key of type PSA_KEY_TYPE_RAW_DATA.

PSA_KEY_DERIVATION_INPUT_SEED (macro)

A seed for key derivation.

#define PSA_KEY_DERIVATION_INPUT_SEED /* implementation-defined value */

This is typically a direct input. It can also be a key of type PSA_KEY_TYPE_RAW_DATA.

PSA_KEY_DERIVATION_INPUT_COST (macro)

A cost parameter for password hashing or key stretching.

#define PSA_KEY_DERIVATION_INPUT_COST /* implementation-defined value */

This must be a direct input, passed to psa_key_derivation_input_integer().

10.6.3. Key derivation functions

psa_key_derivation_operation_t (typedef)

The type of the state object for key derivation operations.

typedef /* implementation-defined type */ psa_key_derivation_operation_t;

Before calling any function on a key derivation operation object, the application must initialize it by any of the following means:

This is an implementation-defined type. Applications that make assumptions about the content of this object will result in in implementation-specific behavior, and are non-portable.

PSA_KEY_DERIVATION_OPERATION_INIT (macro)

This macro returns a suitable initializer for a key derivation operation object of type psa_key_derivation_operation_t.

#define PSA_KEY_DERIVATION_OPERATION_INIT /* implementation-defined value */

psa_key_derivation_operation_init (function)

Return an initial value for a key derivation operation object.

psa_key_derivation_operation_t psa_key_derivation_operation_init(void);

Returns: psa_key_derivation_operation_t

psa_key_derivation_setup (function)

Set up a key derivation operation.

psa_status_t psa_key_derivation_setup(psa_key_derivation_operation_t * operation,
                                      psa_algorithm_t alg);

Parameters

operation

The key derivation operation object to set up. It must have been initialized but not set up yet.

alg

The algorithm to compute. This must be one of the following:

Returns: psa_status_t

PSA_SUCCESS

Success. The operation is now active.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

  • The operation state is not valid: it must be inactive.

  • The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT

alg is neither a key derivation algorithm, nor a key agreement and derivation algorithm.

PSA_ERROR_NOT_SUPPORTED

alg is not supported or is not a key derivation algorithm, or a key agreement and derivation algorithm.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

Description

A key derivation algorithm takes some inputs and uses them to generate a byte stream in a deterministic way. This byte stream can be used to produce keys and other cryptographic material.

A key agreement and derivation algorithm uses a key agreement protocol to provide a shared secret which is used for the key derivation. See psa_key_derivation_key_agreement().

The sequence of operations to derive a key is as follows:

  1. Allocate a key derivation operation object which will be passed to all the functions listed here.

  2. Initialize the operation object with one of the methods described in the documentation for psa_key_derivation_operation_t, e.g. PSA_KEY_DERIVATION_OPERATION_INIT.

  3. Call psa_key_derivation_setup() to specify the algorithm.

  4. Provide the inputs for the key derivation by calling psa_key_derivation_input_bytes() or psa_key_derivation_input_key() as appropriate. Which inputs are needed, in what order, whether keys are permitted, and what type of keys depends on the algorithm.

  5. Optionally set the operation’s maximum capacity with psa_key_derivation_set_capacity(). This can be done before, in the middle of, or after providing inputs. For some algorithms, this step is mandatory because the output depends on the maximum capacity.

  6. To derive a key, call psa_key_derivation_output_key(). To derive a byte string for a different purpose, call psa_key_derivation_output_bytes(). Successive calls to these functions use successive output bytes calculated by the key derivation algorithm.

  7. Clean up the key derivation operation object with psa_key_derivation_abort().

After a successful call to psa_key_derivation_setup(), the operation is active, and the application must eventually terminate the operation with a call to psa_key_derivation_abort().

If psa_key_derivation_setup() returns an error, the operation object is unchanged. If a subsequent function call with an active operation returns an error, the operation enters an error state.

To abandon an active operation, or reset an operation in an error state, call psa_key_derivation_abort().

See Multi-part operations.

psa_key_derivation_get_capacity (function)

Retrieve the current capacity of a key derivation operation.

psa_status_t psa_key_derivation_get_capacity(const psa_key_derivation_operation_t * operation,
                                             size_t * capacity);

Parameters

operation

The operation to query.

capacity

On success, the capacity of the operation.

Returns: psa_status_t

PSA_SUCCESS

Success. The maximum number of bytes that this key derivation can return is (*capacity).

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

  • The operation state is not valid: it must be active.

  • The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

Description

The capacity of a key derivation is the maximum number of bytes that it can return. Reading N bytes of output from a key derivation operation reduces its capacity by at least N. The capacity can be reduced by more than N in the following situations:

psa_key_derivation_set_capacity (function)

Set the maximum capacity of a key derivation operation.

psa_status_t psa_key_derivation_set_capacity(psa_key_derivation_operation_t * operation,
                                             size_t capacity);

Parameters

operation

The key derivation operation object to modify.

capacity

The new capacity of the operation. It must be less or equal to the operation’s current capacity.

Returns: psa_status_t

PSA_SUCCESS

Success.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

  • The operation state is not valid: it must be active.

  • The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT

capacity is larger than the operation’s current capacity. In this case, the operation object remains valid and its capacity remains unchanged.

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

Description

The capacity of a key derivation operation is the maximum number of bytes that the key derivation operation can return from this point onwards.

psa_key_derivation_input_bytes (function)

Provide an input for key derivation or key agreement.

psa_status_t psa_key_derivation_input_bytes(psa_key_derivation_operation_t * operation,
                                            psa_key_derivation_step_t step,
                                            const uint8_t * data,
                                            size_t data_length);

Parameters

operation

The key derivation operation object to use. It must have been set up with psa_key_derivation_setup() and must not have produced any output yet.

step

Which step the input data is for.

data

Input data to use.

data_length

Size of the data buffer in bytes.

Returns: psa_status_t

PSA_SUCCESS

Success.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

  • The operation state is not valid for this input step. This can happen if the application provides a step out of order or repeats a step that may not be repeated.

  • The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

  • step is not compatible with the operation’s algorithm.

  • step does not permit direct inputs.

  • data_length is too small or too large for step in this particular algorithm.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

  • step is not supported with the operation’s algorithm.

  • data_length is is not supported for step in this particular algorithm.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

Which inputs are required and in what order depends on the algorithm. Refer to the documentation of each key derivation or key agreement algorithm for information.

This function passes direct inputs, which is usually correct for non-secret inputs. To pass a secret input, which is normally in a key object, call psa_key_derivation_input_key() instead of this function. Refer to the documentation of individual step types (PSA_KEY_DERIVATION_INPUT_xxx values of type psa_key_derivation_step_t) for more information.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

psa_key_derivation_input_integer (function)

Provide a numeric input for key derivation or key agreement.

psa_status_t psa_key_derivation_input_integer(psa_key_derivation_operation_t * operation,
                                              psa_key_derivation_step_t step,
                                              uint64_t value);

Parameters

operation

The key derivation operation object to use. It must have been set up with psa_key_derivation_setup() and must not have produced any output yet.

step

Which step the input data is for.

value

The value of the numeric input.

Returns: psa_status_t

PSA_SUCCESS

Success.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

  • The operation state is not valid for this input step. This can happen if the application provides a step out of order or repeats a step that may not be repeated.

  • The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

  • step is not compatible with the operation’s algorithm.

  • step does not permit numerical inputs.

  • value is not valid for step in the operation’s algorithm.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

  • step is not supported with the operation’s algorithm.

  • value is not supported for step in the operation’s algorithm.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

Which inputs are required and in what order depends on the algorithm. However, when an algorithm requires a particular order, numeric inputs usually come first as they tend to be configuration parameters. Refer to the documentation of each key derivation or key agreement algorithm for information.

This function is used for inputs which are fixed-size non-negative integers.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

psa_key_derivation_input_key (function)

Provide an input for key derivation in the form of a key.

psa_status_t psa_key_derivation_input_key(psa_key_derivation_operation_t * operation,
                                          psa_key_derivation_step_t step,
                                          psa_key_id_t key);

Parameters

operation

The key derivation operation object to use. It must have been set up with psa_key_derivation_setup() and must not have produced any output yet.

step

Which step the input data is for.

key

Identifier of the key. The key must have an appropriate type for step, it must permit the usage PSA_KEY_USAGE_DERIVE or PSA_KEY_USAGE_VERIFY_DERIVATION (see note), and it must permit the algorithm used by the operation.

Returns: psa_status_t

PSA_SUCCESS

Success.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

  • The operation state is not valid for this input step. This can happen if the application provides a step out of order or repeats a step that may not be repeated.

  • The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE

key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED

The key has neither the PSA_KEY_USAGE_DERIVE nor the PSA_KEY_USAGE_VERIFY_DERIVATION usage flag, or it does not permit the operation’s algorithm.

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

  • step is not compatible with the operation’s algorithm.

  • step does not permit key inputs of the given type, or does not permit key inputs at all.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

  • step is not supported with the operation’s algorithm.

  • Key inputs of the given type are not supported for step in the operation’s algorithm.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

Which inputs are required and in what order depends on the algorithm. Refer to the documentation of each key derivation or key agreement algorithm for information.

This function obtains input from a key object, which is usually correct for secret inputs or for non-secret personalization strings kept in the key store. To pass a non-secret parameter which is not in the key store, call psa_key_derivation_input_bytes() instead of this function. Refer to the documentation of individual step types (PSA_KEY_DERIVATION_INPUT_xxx values of type psa_key_derivation_step_t) for more information.

Note

Once all inputs steps are completed, the following operations are permitted:

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

psa_key_derivation_output_bytes (function)

Read some data from a key derivation operation.

psa_status_t psa_key_derivation_output_bytes(psa_key_derivation_operation_t * operation,
                                             uint8_t * output,
                                             size_t output_length);

Parameters

operation

The key derivation operation object to read from.

output

Buffer where the output will be written.

output_length

Number of bytes to output.

Returns: psa_status_t

PSA_SUCCESS

Success. The first output_length bytes of output contain the derived data.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

  • The operation state is not valid: it must be active, with all required input steps complete.

  • The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_NOT_PERMITTED

One of the inputs was a key whose policy did not permit PSA_KEY_USAGE_DERIVE.

PSA_ERROR_INSUFFICIENT_DATA

The operation’s capacity was less than output_length bytes. In this case, the following occurs:

  • No output is written to the output buffer.

  • The operation’s capacity is set to zero — subsequent calls to this function will not succeed, even with a smaller output buffer.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

This function calculates output bytes from a key derivation algorithm and returns those bytes. If the key derivation’s output is viewed as a stream of bytes, this function consumes the requested number of bytes from the stream and returns them to the caller. The operation’s capacity decreases by the number of bytes read.

If this function returns an error status other than PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

psa_key_derivation_output_key (function)

Derive a key from an ongoing key derivation operation.

psa_status_t psa_key_derivation_output_key(const psa_key_attributes_t * attributes,
                                           psa_key_derivation_operation_t * operation,
                                           psa_key_id_t * key);

Parameters

attributes

The attributes for the new key. This function uses the attributes as follows:

  • The key type is required. It cannot be an asymmetric public key.

  • The key size is required. It must be a valid size for the key type.

  • The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation, see Permitted algorithms.

    If the key type to be created is PSA_KEY_TYPE_PASSWORD_HASH, then the permitted-algorithm policy must be the same as the current operation’s algorithm.

  • The key usage flags define what operations are permitted with the key, see Key usage flags.

  • The key lifetime and identifier are required for a persistent key.

Note

This is an input parameter: it is not updated with the final key attributes. The final attributes of the new key can be queried by calling psa_get_key_attributes() with the key’s identifier.

operation

The key derivation operation object to read from.

key

On success, an identifier for the newly created key. PSA_KEY_ID_NULL on failure.

Returns: psa_status_t

PSA_SUCCESS

Success. If the key is persistent, the key material and the key’s metadata have been saved to persistent storage.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

  • The operation state is not valid: it must be active, with all required input steps complete.

  • The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_NOT_PERMITTED

The following conditions can result in this error:

  • The PSA_KEY_DERIVATION_INPUT_SECRET input step was neither provided through a key, nor the result of a key agreement.

  • One of the inputs was a key whose policy did not permit PSA_KEY_USAGE_DERIVE.

  • The implementation does not permit creating a key with the specified attributes due to some implementation-specific policy.

PSA_ERROR_ALREADY_EXISTS

This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.

PSA_ERROR_INSUFFICIENT_DATA

There was not enough data to create the desired key. In this case, the following occurs:

  • No key is generated.

  • The operation’s capacity is set to zero — subsequent calls to this function will not succeed, even if they require less data.

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

  • The key type is invalid, or is an asymmetric public key type.

  • The key type is PSA_KEY_TYPE_PASSWORD_HASH, and the permitted-algorithm policy is not the same as the current operation’s algorithm.

  • The key size is not valid for the key type. Implementations must reject an attempt to derive a key of size 0.

  • The key lifetime is invalid.

  • The key identifier is not valid for the key lifetime.

  • The key usage flags include invalid values.

  • The key’s permitted-usage algorithm is invalid.

  • The key attributes, as a whole, are invalid.

PSA_ERROR_NOT_SUPPORTED

The key attributes, as a whole, are not supported, either by the implementation in general or in the specified storage location.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_INSUFFICIENT_STORAGE

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

This function calculates output bytes from a key derivation algorithm and uses those bytes to generate a key deterministically. The key’s location, policy, type and size are taken from attributes.

If the key derivation’s output is viewed as a stream of bytes, this function consumes the required number of bytes from the stream. The operation’s capacity decreases by the number of bytes used to derive the key.

If this function returns an error status other than PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

How much output is produced and consumed from the operation, and how the key is derived, depends on the key type. Table 8 describes the required key derivation procedures for standard key derivation algorithms. Implementations can use other methods for implementation-specific algorithms.

In all cases, the data that is read is discarded from the operation. The operation’s capacity is decreased by the number of bytes read.

Table 8 Standard key derivation process

Key type

Key type details and derivation procedure

AES

ARC4

ARIA

CAMELLIA

ChaCha20

SM4

Secrets for derivation

HMAC

Password hashes

PSA_KEY_TYPE_AES

PSA_KEY_TYPE_ARC4

PSA_KEY_TYPE_ARIA

PSA_KEY_TYPE_CAMELLIA

PSA_KEY_TYPE_CHACHA20

PSA_KEY_TYPE_SM4

PSA_KEY_TYPE_DERIVE

PSA_KEY_TYPE_HMAC

PSA_KEY_TYPE_PASSWORD_HASH

For key types for which the key is an arbitrary sequence of bytes of a given size, this function is functionally equivalent to calling psa_key_derivation_output_bytes() and passing the resulting output to psa_import_key(). However, this function has a security benefit: if the implementation provides an isolation boundary then the key material is not exposed outside the isolation boundary. As a consequence, for these key types, this function always consumes exactly (bits/8) bytes from the operation.

DES

PSA_KEY_TYPE_DES, 64 bits.

This function generates a key using the following process:

  1. Draw an 8-byte string.

  2. Set/clear the parity bits in each byte.

  3. If the result is a forbidden weak key, discard the result and return to step 1.

  4. Output the string.

2-key 3DES

3-key 3DES

PSA_KEY_TYPE_DES, 192 bits.

PSA_KEY_TYPE_DES, 128 bits.

The two or three keys are generated by repeated application of the process used to generate a DES key.

For example, for 3-key 3DES, if the first 8 bytes specify a weak key and the next 8 bytes do not, discard the first 8 bytes, use the next 8 bytes as the first key, and continue reading output from the operation to derive the other two keys.

Finite-field Diffie-Hellman keys

ECC keys on a Weierstrass elliptic curve

PSA_KEY_TYPE_DH_KEY_PAIR(dh_family) where dh_family designates any Diffie-Hellman family.

PSA_KEY_TYPE_ECC_KEY_PAIR(ecc_family) where ecc_family designates a Weierstrass curve family.

These key types require the generation of a private key which is an integer in the range [1, N - 1], where N is the boundary of the private key domain: N is the prime p for Diffie-Hellman, or the order of the curve’s base point for ECC.

Let m be the bit size of N, such that 2^m > N >= 2^(m-1). This function generates the private key using the following process:

  1. Draw a byte string of length ceiling(m/8) bytes.

  2. If m is not a multiple of 8, set the most significant (8 * ceiling(m/8) - m) bits of the first byte in the string to zero.

  3. Convert the string to integer k by decoding it as a big-endian byte string.

  4. If k > N - 2, discard the result and return to step 1.

  5. Output k + 1 as the private key.

This method allows compliance to NIST standards, specifically the methods titled Key-Pair Generation by Testing Candidates in the following publications:

  • NIST Special Publication 800-56A: Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography [SP800-56A] §5.6.1.1.4 for Diffie-Hellman keys.

  • [SP800-56A] §5.6.1.2.2 or FIPS Publication 186-4: Digital Signature Standard (DSS) [FIPS186-4] §B.4.2 for elliptic curve keys.

ECC keys on a Montgomery elliptic curve

PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_MONTGOMERY)

This function always draws a byte string whose length is determined by the curve, and sets the mandatory bits accordingly. That is:

Other key types

This includes PSA_KEY_TYPE_RSA_KEY_PAIR.

The way in which the operation output is consumed is implementation-defined.

For algorithms that take an input step PSA_KEY_DERIVATION_INPUT_SECRET, the input to that step must be provided with psa_key_derivation_input_key(). Future versions of this specification might include additional restrictions on the derived key based on the attributes and strength of the secret key.

psa_key_derivation_verify_bytes (function)

Compare output data from a key derivation operation to an expected value.

psa_status_t psa_key_derivation_verify_bytes(psa_key_derivation_operation_t * operation,
                                             const uint8_t *expected_output,
                                             size_t output_length);

Parameters

operation

The key derivation operation object to read from.

expected_output

Buffer containing the expected derivation output.

output_length

Length ot the expected output. This is also the number of bytes that will be read.

Returns: psa_status_t

PSA_SUCCESS

Success. The output of the key derivation operation matches expected_output.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

  • The operation state is not valid: it must be active, with all required input steps complete.

  • The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_NOT_PERMITTED

One of the inputs is a key whose policy does not permit PSA_KEY_USAGE_VERIFY_DERIVATION.

PSA_ERROR_INVALID_SIGNATURE

The output of the key derivation operation does not match the value in expected_output.

PSA_ERROR_INSUFFICIENT_DATA

The operation’s capacity was less than output_length bytes. In this case, the operation’s capacity is set to zero — subsequent calls to this function will not succeed, even with a smaller expected output length.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

This function calculates output bytes from a key derivation algorithm and compares those bytes to an expected value. If the key derivation’s output is viewed as a stream of bytes, this function destructively reads output_length bytes from the stream before comparing them with expected_output. The operation’s capacity decreases by the number of bytes read.

This is functionally equivalent to the following code:

uint8_t tmp[output_length];
psa_key_derivation_output_bytes(operation, tmp, output_length);
if (memcmp(expected_output, tmp, output_length) != 0)
    return PSA_ERROR_INVALID_SIGNATURE;

However, calling psa_key_derivation_verify_bytes() works even if the key’s policy does not permit output of the bytes.

If this function returns an error status other than PSA_ERROR_INSUFFICIENT_DATA or PSA_ERROR_INVALID_SIGNATURE, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

Note

Implementations must make the best effort to ensure that the comparison between the actual key derivation output and the expected output is performed in constant time.

psa_key_derivation_verify_key (function)

Compare output data from a key derivation operation to an expected value stored in a key.

psa_status_t psa_key_derivation_verify_key(psa_key_derivation_operation_t * operation,
                                           psa_key_id_t expected);

Parameters

operation

The key derivation operation object to read from.

expected

A key of type PSA_KEY_TYPE_PASSWORD_HASH containing the expected output. The key must permit the usage PSA_KEY_USAGE_VERIFY_DERIVATION, and the permitted algorithm must match the operation’s algorithm.

The value of this key is typically computed by a previous call to psa_key_derivation_output_key().

Returns: psa_status_t

PSA_SUCCESS

Success. The output of the key derivation operation matches the expected key value.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

  • The operation state is not valid: it must be active, with all required input steps complete.

  • The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE

expected is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED

The following conditions can result in this error:

PSA_ERROR_INVALID_SIGNATURE

The output of the key derivation operation does not match the value of the expected key.

PSA_ERROR_INSUFFICIENT_DATA

The operation’s capacity was less than the length of the expected key. In this case, the operation’s capacity is set to zero — subsequent calls to this function will not succeed, even with a smaller expected key length.

PSA_ERROR_INVALID_ARGUMENT

The key type is not PSA_KEY_TYPE_PASSWORD_HASH.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

This function calculates output bytes from a key derivation algorithm and compares those bytes to an expected value, provided as key of type PSA_KEY_TYPE_PASSWORD_HASH. If the key derivation’s output is viewed as a stream of bytes, this function destructively reads the number of bytes corresponding to the length of the expected key from the stream before comparing them with the key value. The operation’s capacity decreases by the number of bytes read.

This is functionally equivalent to exporting the expected key and calling psa_key_derivation_verify_bytes() on the result, except that it works when the key cannot be exported.

If this function returns an error status other than PSA_ERROR_INSUFFICIENT_DATA or PSA_ERROR_INVALID_SIGNATURE, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

Note

Implementations must make the best effort to ensure that the comparison between the actual key derivation output and the expected output is performed in constant time.

psa_key_derivation_abort (function)

Abort a key derivation operation.

psa_status_t psa_key_derivation_abort(psa_key_derivation_operation_t * operation);

Parameters

operation

The operation to abort.

Returns: psa_status_t

PSA_SUCCESS

Success. The operation object can now be discarded or reused.

PSA_ERROR_BAD_STATE

The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

Description

Aborting an operation frees all associated resources except for the operation object itself. Once aborted, the operation object can be reused for another operation by calling psa_key_derivation_setup() again.

This function can be called at any time after the operation object has been initialized as described in psa_key_derivation_operation_t.

In particular, it is valid to call psa_key_derivation_abort() twice, or to call psa_key_derivation_abort() on an operation that has not been set up.

10.6.4. Support macros

PSA_ALG_IS_KEY_DERIVATION_STRETCHING (macro)

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

#define PSA_ALG_IS_KEY_DERIVATION_STRETCHING(alg) \
    /* specification-defined value */

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. This macro can return either 0 or 1 if alg is not a supported key derivation algorithm algorithm identifier.

Description

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.

PSA_ALG_IS_HKDF (macro)

Whether the specified algorithm is an HKDF algorithm (PSA_ALG_HKDF(hash_alg)).

#define PSA_ALG_IS_HKDF(alg) /* specification-defined value */

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is an HKDF algorithm, 0 otherwise. This macro can return either 0 or 1 if alg is not a supported key derivation algorithm identifier.

Description

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

PSA_ALG_IS_HKDF_EXTRACT (macro)

Whether the specified algorithm is an HKDF-Extract algorithm (PSA_ALG_HKDF_EXTRACT(hash_alg)).

#define PSA_ALG_IS_HKDF_EXTRACT(alg) /* specification-defined value */

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is an HKDF-Extract algorithm, 0 otherwise. This macro can return either 0 or 1 if alg is not a supported key derivation algorithm identifier.

PSA_ALG_IS_HKDF_EXPAND (macro)

Whether the specified algorithm is an HKDF-Expand algorithm (PSA_ALG_HKDF_EXPAND(hash_alg)).

#define PSA_ALG_IS_HKDF_EXPAND(alg) /* specification-defined value */

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is an HKDF-Expand algorithm, 0 otherwise. This macro can return either 0 or 1 if alg is not a supported key derivation algorithm identifier.

PSA_ALG_IS_TLS12_PRF (macro)

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

#define PSA_ALG_IS_TLS12_PRF(alg) /* specification-defined value */

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. This macro can return either 0 or 1 if alg is not a supported key derivation algorithm identifier.

PSA_ALG_IS_TLS12_PSK_TO_MS (macro)

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

#define PSA_ALG_IS_TLS12_PSK_TO_MS(alg) /* specification-defined value */

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. This macro can return either 0 or 1 if alg is not a supported key derivation algorithm identifier.

PSA_ALG_IS_PBKDF2_HMAC (macro)

Whether the specified algorithm is a PBKDF2-HMAC algorithm.

#define PSA_ALG_IS_PBKDF2_HMAC(alg) /* specification-defined value */

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a PBKDF2-HMAC algorithm, 0 otherwise. This macro can return either 0 or 1 if alg is not a supported key derivation algorithm identifier.

PSA_KEY_DERIVATION_UNLIMITED_CAPACITY (macro)

Use the maximum possible capacity for a key derivation operation.

#define PSA_KEY_DERIVATION_UNLIMITED_CAPACITY \
    /* implementation-defined value */

Use this value as the capacity argument when setting up a key derivation to specify that the operation will use the maximum possible capacity. The value of the maximum possible capacity depends on the key derivation algorithm.

PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE (macro)

This macro returns the maximum supported length of the PSK for the TLS-1.2 PSK-to-MS key derivation.

#define PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE /* implementation-defined value */

This implementation-defined value specifies the maximum length for the PSK input used with a PSA_ALG_TLS12_PSK_TO_MS() key agreement algorithm.

Quoting Pre-Shared Key Ciphersuites for Transport Layer Security (TLS) [RFC4279] §5.3:

TLS implementations supporting these cipher suites MUST support arbitrary PSK identities up to 128 octets in length, and arbitrary PSKs up to 64 octets in length. Supporting longer identities and keys is RECOMMENDED.

Therefore, it is recommended that implementations define PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE with a value greater than or equal to 64.