(8a1a5fe)

Key Manager DPE Device Interface Functions More...

#include <stdint.h>
#include "sw/device/lib/base/macros.h"
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_base.h"
#include "sw/device/lib/dif/autogen/dif_keymgr_dpe_autogen.h"

Go to the source code of this file.

Data Structures
struct	dif_keymgr_dpe_advance_params
	Input parameters for advancing a DPE context/slot. More...

struct	dif_keymgr_dpe_generate_params
	Input parameters for advancing a DPE context/slot. More...

struct	dif_keymgr_dpe_erase_params
	Input parameters for erasing a DPE context/slot. More...

struct	dif_keymgr_dpe_output
	Useed to represent the output of SW generated key. More...

Typedefs
typedef enum dif_keymgr_dpe_state	dif_keymgr_dpe_state_t
	SW-visible key manager DPE states. More...

typedef struct dif_keymgr_dpe_advance_params	dif_keymgr_dpe_advance_params_t
	Input parameters for advancing a DPE context/slot.

typedef enum dif_keymgr_dpe_key_dest	dif_keymgr_dpe_key_dest_t
	Key destination of a versioned key generation operation. More...

typedef struct dif_keymgr_dpe_generate_params	dif_keymgr_dpe_generate_params_t
	Input parameters for advancing a DPE context/slot.

typedef struct dif_keymgr_dpe_erase_params	dif_keymgr_dpe_erase_params_t
	Input parameters for erasing a DPE context/slot.

typedef struct dif_keymgr_dpe_output	dif_keymgr_dpe_output_t
	Useed to represent the output of SW generated key.

typedef enum dif_keymgr_dpe_status_code	dif_keymgr_dpe_status_code_t
	Status code bit flags. More...

typedef uint8_t	dif_keymgr_dpe_status_codes_t
	A bit vector of status codes. More...

Enumerations
enum	dif_keymgr_dpe_state { kDifKeymgrDpeStateReset = 0, kDifKeymgrDpeStateAvailable = 1, kDifKeymgrDpeStateDisabled = 2, kDifKeymgrDpeStateInvalid = 3 }
	SW-visible key manager DPE states. More...

enum	dif_keymgr_dpe_key_dest { kDifKeymgrDpeKeyDestNone = 0, kDifKeymgrDpeKeyDestAes = 1, kDifKeymgrDpeKeyDestKmac = 2, kDifKeymgrDpeKeyDestOtbn = 3 }
	Key destination of a versioned key generation operation. More...

enum	dif_keymgr_dpe_status_code { kDifKeymgrDpeStatusCodeIdle = 1 << 0, kDifKeymgrDpeStatusCodeInvalidOperation = 1 << 1, kDifKeymgrDpeStatusCodeInvalidKmacInput = 1 << 2, kDifKeymgrDpeStatusCodeInvalidState = 1 << 3 }
	Status code bit flags. More...

Functions
dif_result_t	dif_keymgr_dpe_initialize (const dif_keymgr_dpe_t *keymgr_dpe, uint32_t slot_dst_sel)
	Initializes the keymgr_pde block by performing an advance operation. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_keymgr_dpe_advance_state (const dif_keymgr_dpe_t keymgr_dpe, const dif_keymgr_dpe_advance_params_t params)
	Advances a keymgr_dpe slot with given parameters. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_keymgr_dpe_erase_slot (const dif_keymgr_dpe_t keymgr_dpe, const dif_keymgr_dpe_erase_params_t params)
	Erases a given keymgr_dpe slot. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_keymgr_dpe_generate (const dif_keymgr_dpe_t keymgr_dpe, const dif_keymgr_dpe_generate_params_t params)
	Generate a SW/HW key from a chosen keymgr_dpe slot. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_keymgr_dpe_get_status_codes (const dif_keymgr_dpe_t keymgr_dpe, dif_keymgr_dpe_status_codes_t status_codes)
	Gets the operational status of keymgr_dpe. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_keymgr_dpe_get_state (const dif_keymgr_dpe_t keymgr_dpe, uint32_t state)
	Gets the current state of key manager. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_keymgr_dpe_read_output (const dif_keymgr_dpe_t keymgr_dpe, dif_keymgr_dpe_output_t output)
	Read the value of SW generated key from its related CSR. More...

Detailed Description

Key Manager DPE Device Interface Functions

Definition in file dif_keymgr_dpe.h.

Data Structure Documentation

◆ dif_keymgr_dpe_advance_params

struct dif_keymgr_dpe_advance_params

Input parameters for advancing a DPE context/slot.

Definition at line 48 of file dif_keymgr_dpe.h.

Data Fields
uint32_t	binding_value[8]	This value is used by key manager as input to DICE computation and can be either a value that represents the measurement of a boot stage or simply a tag from a manifest.
uint32_t	max_key_version	Maximum allowed version for keys to be generated at a state. This value is stored inside keymgr slot so that it can later be compared against the `key_version` input provided along with generation request.
uint32_t	slot_dst_sel	The destination slot which recieves the derived child DPE context.
uint32_t	slot_policy	The slot policy bits for the derived child DPE context.
uint32_t	slot_src_sel	The source slot to be used as parent DPE context.

◆ dif_keymgr_dpe_generate_params

struct dif_keymgr_dpe_generate_params

Input parameters for advancing a DPE context/slot.

Definition at line 112 of file dif_keymgr_dpe.h.

Data Fields
dif_keymgr_dpe_key_dest_t	key_dest	Destination for {AES, KMAC, OTBN}, which is used for diversification.
uint32_t	salt[8]	Salt value used as input for key generation (i.e. becomes part of the message payload sent to KMAC during computation).
bool	sideload_key	Set to true, if this is a sideload key, otherwise set to false.
uint32_t	slot_src_sel	The source slot from which the key is derived.
uint32_t	version	The key version used for generating versioned key. This value should not be greater than the `max_key_version` value stored inside the source slot that is used to generate the key.

◆ dif_keymgr_dpe_erase_params

struct dif_keymgr_dpe_erase_params

Input parameters for erasing a DPE context/slot.

Definition at line 145 of file dif_keymgr_dpe.h.

Data Fields
uint32_t	slot_dst_sel	Index for the slot to be erased.

◆ dif_keymgr_dpe_output

struct dif_keymgr_dpe_output

Useed to represent the output of SW generated key.

Definition at line 155 of file dif_keymgr_dpe.h.

Data Fields
uint32_t	value[2][8]

Typedef Documentation

◆ dif_keymgr_dpe_key_dest_t

typedef enum dif_keymgr_dpe_key_dest dif_keymgr_dpe_key_dest_t

Key destination of a versioned key generation operation.

Regardless of whether the generated key is SW or sideload key, HW uses a unique diversification constant for each cryptographic use case. In the case of sideload key, this enum value is also used to determine the target peripheral port to which the generated key is loaded.

◆ dif_keymgr_dpe_state_t

typedef enum dif_keymgr_dpe_state dif_keymgr_dpe_state_t

SW-visible key manager DPE states.

Key manager RTL has more than 4 finite state machine (FSM) states, but it simply truncates the reported state into four states given below. The reason behind this truncation is that FSM lingers on some states temporarily (i.e. few clock cycles) and the transition into the next state does not require further invocation.

From SW point of view, key manager FSM transitions follow a sequence sequential manner and these transitions are irreversible until a power cycle.

◆ dif_keymgr_dpe_status_code_t

typedef enum dif_keymgr_dpe_status_code dif_keymgr_dpe_status_code_t

Status code bit flags.

See also: dif_keymgr_dpe_status_codes_t.

◆ dif_keymgr_dpe_status_codes_t

typedef uint8_t dif_keymgr_dpe_status_codes_t

A bit vector of status codes.

The following snippet can be used to check if key manager is idle:

bool is_idle = (status_codes & kDifKeymgrDpeStatusCodeIdle);

The following snippet can be used to check if key manager is idle and error-free:

bool is_idle_and_ok = (status_codes == kDifKeymgrDpeStatusCodeIdle);

See also: dif_keymgr_dpe_status_code_t.

Definition at line 214 of file dif_keymgr_dpe.h.

Enumeration Type Documentation

◆ dif_keymgr_dpe_key_dest

enum dif_keymgr_dpe_key_dest

Key destination of a versioned key generation operation.

Regardless of whether the generated key is SW or sideload key, HW uses a unique diversification constant for each cryptographic use case. In the case of sideload key, this enum value is also used to determine the target peripheral port to which the generated key is loaded.

Enumerator
kDifKeymgrDpeKeyDestNone	Diversify the generated key for no HW IP (and don't sideload it).
kDifKeymgrDpeKeyDestAes	Diversify the generated key for AES (and load it to AES peripheral port if sideload key).
kDifKeymgrDpeKeyDestKmac	Diversify the generated key for KMAC (and load it to KMAC peripheral port if sideload key).
kDifKeymgrDpeKeyDestOtbn	Diversify the generated key for OTBN (and load it to OTBN peripheral port if sideload key).

Definition at line 87 of file dif_keymgr_dpe.h.

◆ dif_keymgr_dpe_state

enum dif_keymgr_dpe_state

SW-visible key manager DPE states.

Key manager RTL has more than 4 finite state machine (FSM) states, but it simply truncates the reported state into four states given below. The reason behind this truncation is that FSM lingers on some states temporarily (i.e. few clock cycles) and the transition into the next state does not require further invocation.

From SW point of view, key manager FSM transitions follow a sequence sequential manner and these transitions are irreversible until a power cycle.

Definition at line 38 of file dif_keymgr_dpe.h.

◆ dif_keymgr_dpe_status_code

enum dif_keymgr_dpe_status_code

Status code bit flags.

See also: dif_keymgr_dpe_status_codes_t.

Enumerator
kDifKeymgrDpeStatusCodeIdle	Key manager is idle.
kDifKeymgrDpeStatusCodeInvalidOperation	Software invoked an invalid operation.
kDifKeymgrDpeStatusCodeInvalidKmacInput	Key manager issued invalid data to KMAC interface.
kDifKeymgrDpeStatusCodeInvalidState	Key manager encountered invalid state.

Definition at line 164 of file dif_keymgr_dpe.h.

Function Documentation

◆ dif_keymgr_dpe_advance_state()

OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_dpe_advance_state	(	const dif_keymgr_dpe_t *	keymgr_dpe,
		const dif_keymgr_dpe_advance_params_t *	params
	)

Advances a keymgr_dpe slot with given parameters.

Parameters

keymgr_dpe	A key manager handle.
params	Struct to pass inputs consumed by HW during advance.

Returns: The result of the operation.

Definition at line 185 of file dif_keymgr_dpe.c.

◆ dif_keymgr_dpe_erase_slot()

OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_dpe_erase_slot	(	const dif_keymgr_dpe_t *	keymgr_dpe,
		const dif_keymgr_dpe_erase_params_t *	params
	)

Erases a given keymgr_dpe slot.

Parameters

keymgr_dpe	A key manager handle.
params	A struct that selects the slot to be erased.

Returns: The result of the operation.

Definition at line 256 of file dif_keymgr_dpe.c.

◆ dif_keymgr_dpe_generate()

OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_dpe_generate	(	const dif_keymgr_dpe_t *	keymgr_dpe,
		const dif_keymgr_dpe_generate_params_t *	params
	)

Generate a SW/HW key from a chosen keymgr_dpe slot.

Parameters

keymgr_dpe	A key manager handle.
params	Struct to pass inputs consumed by HW generate operation.

Returns: The result of the operation.

Definition at line 282 of file dif_keymgr_dpe.c.

◆ dif_keymgr_dpe_get_state()

OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_dpe_get_state	(	const dif_keymgr_dpe_t *	keymgr_dpe,
		uint32_t *	state
	)

Gets the current state of key manager.

Parameters

	keymgr_dpe	A key manager handle.
[out]	state	Out-param for current key manager state.

Returns: The result of the operation.

◆ dif_keymgr_dpe_get_status_codes()

OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_dpe_get_status_codes	(	const dif_keymgr_dpe_t *	keymgr_dpe,
		dif_keymgr_dpe_status_codes_t *	status_codes
	)

Gets the operational status of keymgr_dpe.

This function also clears OP_STATUS and ERR_CODE registers after reading them.

Parameters

	keymgr_dpe	A key manager handle.
[out]	status_codes	Out-param for key manager status codes.

Returns: The result of the operation.

Definition at line 343 of file dif_keymgr_dpe.c.

◆ dif_keymgr_dpe_initialize()

dif_result_t dif_keymgr_dpe_initialize	(	const dif_keymgr_dpe_t *	keymgr_dpe,
		uint32_t	slot_dst_sel
	)

Initializes the keymgr_pde block by performing an advance operation.

The hardware does not have an explicit initialize command. Initialization is simple the first advance call without software binding, max version or policy registers set. Use this call before calling dif_keymgr_dpe_advance_state().

Parameters

keymgr_dpe	A key manager handle.
slot_dst_sel	Target slot used to latch the UDS key.

Returns: The result of the operation.

Definition at line 159 of file dif_keymgr_dpe.c.

◆ dif_keymgr_dpe_read_output()

OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_dpe_read_output	(	const dif_keymgr_dpe_t *	keymgr_dpe,
		dif_keymgr_dpe_output_t *	output
	)

Read the value of SW generated key from its related CSR.

It is the responsibility of the caller to check that key generation has completed.

Parameters

	keymgr_dpe	A key manager handle.
[out]	output	The key value in two shares.

Returns: The result of the operation.

Definition at line 327 of file dif_keymgr_dpe.c.

(8a1a5fe)

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ dif_keymgr_dpe_advance_params

◆ dif_keymgr_dpe_generate_params

◆ dif_keymgr_dpe_erase_params

◆ dif_keymgr_dpe_output

Typedef Documentation

◆ dif_keymgr_dpe_key_dest_t

◆ dif_keymgr_dpe_state_t

◆ dif_keymgr_dpe_status_code_t

◆ dif_keymgr_dpe_status_codes_t

Enumeration Type Documentation

◆ dif_keymgr_dpe_key_dest

◆ dif_keymgr_dpe_state

◆ dif_keymgr_dpe_status_code

Function Documentation

◆ dif_keymgr_dpe_advance_state()

◆ dif_keymgr_dpe_erase_slot()

◆ dif_keymgr_dpe_generate()

◆ dif_keymgr_dpe_get_state()

◆ dif_keymgr_dpe_get_status_codes()

◆ dif_keymgr_dpe_initialize()

◆ dif_keymgr_dpe_read_output()