Secure Element Key Derivation and Agreement#

Key derivation is the process of generating new key material using an existing key and additional parameters, iterating through a basic cryptographic function, such as a hash.

Key agreement is a part of cryptographic protocols that allows two parties to agree on the same key value, but starting from different original key material. The flows are similar, and the PSA Crypto Driver Model uses the same functions for both of the flows.

There are two different final functions for the flows, psa_drv_se_key_derivation_derive and psa_drv_se_key_derivation_export. psa_drv_se_key_derivation_derive is used when the key material should be placed in a slot on the hardware and not exposed to the caller. psa_drv_se_key_derivation_export is used when the key material should be returned to the PSA Cryptographic API implementation.

Different key derivation algorithms require a different number of inputs. Instead of having an API that takes as input variable length arrays, which can be problematic to manage on embedded platforms, the inputs are passed to the driver via a function, psa_drv_se_key_derivation_collateral, that is called multiple times with different collateral_ids. Thus, for a key derivation algorithm that required 3 parameter inputs, the flow would look something like:

psa_drv_se_key_derivation_setup(kdf_algorithm, source_key, dest_key_size_bytes);
psa_drv_se_key_derivation_collateral(kdf_algorithm_collateral_id_0,
                                     p_collateral_0,
                                     collateral_0_size);
psa_drv_se_key_derivation_collateral(kdf_algorithm_collateral_id_1,
                                     p_collateral_1,
                                     collateral_1_size);
psa_drv_se_key_derivation_collateral(kdf_algorithm_collateral_id_2,
                                     p_collateral_2,
                                     collateral_2_size);
psa_drv_se_key_derivation_derive();

key agreement example:

psa_drv_se_key_derivation_setup(alg, source_key. dest_key_size_bytes);
psa_drv_se_key_derivation_collateral(DHE_PUBKEY, p_pubkey, pubkey_size);
psa_drv_se_key_derivation_export(p_session_key,
                                 session_key_size,
                                 &session_key_length);

Modules#

psa_drv_se_key_derivation_t

Typedefs#

typedef psa_status_t(*
psa_drv_se_key_derivation_setup_t)(psa_drv_se_context_t *drv_context, void *op_context, psa_algorithm_t kdf_alg, psa_key_slot_number_t source_key)

A function that Sets up a secure element key derivation operation by specifying the algorithm and the source key sot.

typedef psa_status_t(*
psa_drv_se_key_derivation_collateral_t)(void *op_context, uint32_t collateral_id, const uint8_t *p_collateral, size_t collateral_size)

A function that provides collateral (parameters) needed for a secure element key derivation or key agreement operation.

typedef psa_status_t(*
psa_drv_se_key_derivation_derive_t)(void *op_context, psa_key_slot_number_t dest_key)

A function that performs the final secure element key derivation step and place the generated key material in a slot.

typedef psa_status_t(*
psa_drv_se_key_derivation_export_t)(void *op_context, uint8_t *p_output, size_t output_size, size_t *p_output_length)

A function that performs the final step of a secure element key agreement and place the generated key material in a buffer.

Typedef Documentation#

psa_drv_se_key_derivation_setup_t#

typedef psa_status_t(* psa_drv_se_key_derivation_setup_t) (psa_drv_se_context_t *drv_context, void *op_context, psa_algorithm_t kdf_alg, psa_key_slot_number_t source_key) )(psa_drv_se_context_t *drv_context, void *op_context, psa_algorithm_t kdf_alg, psa_key_slot_number_t source_key)

A function that Sets up a secure element key derivation operation by specifying the algorithm and the source key sot.

Parameters
[inout]drv_context

The driver context structure.

[inout]op_context

A hardware-specific structure containing any context information for the implementation

[in]kdf_alg

The algorithm to be used for the key derivation

[in]source_key

The key to be used as the source material for the key derivation


Definition at line 1201 of file util/third_party/mbedtls/include/psa/crypto_se_driver.h

psa_drv_se_key_derivation_collateral_t#

typedef psa_status_t(* psa_drv_se_key_derivation_collateral_t) (void *op_context, uint32_t collateral_id, const uint8_t *p_collateral, size_t collateral_size) )(void *op_context, uint32_t collateral_id, const uint8_t *p_collateral, size_t collateral_size)

A function that provides collateral (parameters) needed for a secure element key derivation or key agreement operation.

Parameters
[inout]op_context

A hardware-specific structure containing any context information for the implementation

[in]collateral_id

An ID for the collateral being provided

[in]p_collateral

A buffer containing the collateral data

[in]collateral_size

The size in bytes of the collateral

Since many key derivation algorithms require multiple parameters, it is expected that this function may be called multiple times for the same operation, each with a different algorithm-specific collateral_id


Definition at line 1221 of file util/third_party/mbedtls/include/psa/crypto_se_driver.h

psa_drv_se_key_derivation_derive_t#

typedef psa_status_t(* psa_drv_se_key_derivation_derive_t) (void *op_context, psa_key_slot_number_t dest_key) )(void *op_context, psa_key_slot_number_t dest_key)

A function that performs the final secure element key derivation step and place the generated key material in a slot.

Parameters
[inout]op_context

A hardware-specific structure containing any context information for the implementation

[in]dest_key

The slot where the generated key material should be placed


Definition at line 1236 of file util/third_party/mbedtls/include/psa/crypto_se_driver.h

psa_drv_se_key_derivation_export_t#

typedef psa_status_t(* psa_drv_se_key_derivation_export_t) (void *op_context, uint8_t *p_output, size_t output_size, size_t *p_output_length) )(void *op_context, uint8_t *p_output, size_t output_size, size_t *p_output_length)

A function that performs the final step of a secure element key agreement and place the generated key material in a buffer.

Parameters
[out]p_output

Buffer in which to place the generated key material

[in]output_size

The size in bytes of p_output

[out]p_output_length

Upon success, contains the number of bytes of key material placed in p_output


Definition at line 1250 of file util/third_party/mbedtls/include/psa/crypto_se_driver.h