(dcee03a)

Key Manager Device Interface Functions More...

#include <stdint.h>
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_warn_unused_result.h"

Data Structures
struct	dif_keymgr_params
	Hardware instantiation parameters for key manager. More...

struct	dif_keymgr_config
	Runtime configuration for key manager. More...

struct	dif_keymgr
	A handle to a key manager. More...

struct	dif_keymgr_state_params
	Parameters for a key manager state. More...

struct	dif_keymgr_versioned_key_params
	Parameters for generating a versioned key. More...

struct	dif_keymgr_output
	Output of a key manager operation. More...

Typedefs
typedef enum dif_keymgr_toggle	dif_keymgr_toggle_t
	Enumeration for enabling/disabling various functionality.

typedef struct dif_keymgr_params	dif_keymgr_params_t
	Hardware instantiation parameters for key manager. More...

typedef struct dif_keymgr_config	dif_keymgr_config_t
	Runtime configuration for key manager. More...

typedef struct dif_keymgr	dif_keymgr_t
	A handle to a key manager. More...

typedef enum dif_keymgr_result	dif_keymgr_result_t
	Result of a key manager operation.

typedef enum dif_keymgr_lockable_result	dif_keymgr_lockable_result_t
	Result of a key manager operation that writes to lockable registers.

typedef enum dif_keymgr_irq	dif_keymgr_irq_t
	Key manager interrupts.

typedef uint32_t	dif_keymgr_irq_snapshot_t
	A snapshot of the enablement state of key manager interrupts. More...

typedef enum dif_keymgr_alert	dif_keymgr_alert_t
	Key manager alerts. More...

typedef enum dif_keymgr_state	dif_keymgr_state_t
	Key manager states. More...

typedef struct dif_keymgr_state_params	dif_keymgr_state_params_t
	Parameters for a key manager state.

typedef enum dif_keymgr_status_code	dif_keymgr_status_code_t
	Status code bit flags. More...

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

typedef enum dif_keymgr_versioned_key_dest	dif_keymgr_versioned_key_dest_t
	Destination of a versioned key generation operation. More...

typedef struct dif_keymgr_versioned_key_params	dif_keymgr_versioned_key_params_t
	Parameters for generating a versioned key.

typedef struct dif_keymgr_output	dif_keymgr_output_t
	Output of a key manager operation. More...

Enumerations
enum	dif_keymgr_toggle { kDifKeymgrToggleEnabled, kDifKeymgrToggleDisabled }
	Enumeration for enabling/disabling various functionality. More...

enum	dif_keymgr_result { kDifKeymgrOk = 0, kDifKeymgrError = 1, kDifKeymgrBadArg = 2 }
	Result of a key manager operation. More...

enum	dif_keymgr_lockable_result { kDifKeymgrLockableOk = kDifKeymgrOk, kDifKeymgrLockableError = kDifKeymgrError, kDifKeymgrLockableBadArg = kDifKeymgrBadArg, kDifKeymgrLockableLocked }
	Result of a key manager operation that writes to lockable registers. More...

enum	dif_keymgr_irq { kDifKeymgrIrqDone, kDifKeymgrIrqLast = kDifKeymgrIrqDone }
	Key manager interrupts. More...

enum	dif_keymgr_alert { kDifKeymgrAlertHardware, kDifKeymgrAlertSoftware, kDifKeymgrAlertLast = kDifKeymgrAlertSoftware }
	Key manager alerts. More...

enum	dif_keymgr_state { kDifKeymgrStateReset, kDifKeymgrStateInitialized, kDifKeymgrStateCreatorRootKey, kDifKeymgrStateOwnerIntermediateKey, kDifKeymgrStateOwnerRootKey, kDifKeymgrStateDisabled, kDifKeymgrStateInvalid }
	Key manager states. More...

enum	dif_keymgr_status_code { kDifKeymgrStatusCodeIdle = 1 << 0, kDifKeymgrStatusCodeInvalidOperation = 1 << 1, kDifKeymgrStatusCodeInvalidKmacCommand = 1 << 2, kDifKeymgrStatusCodeInvalidKmacInput = 1 << 3, kDifKeymgrStatusCodeInvalidKmacOutput = 1 << 4 }
	Status code bit flags. More...

enum	dif_keymgr_versioned_key_dest { kDifKeymgrVersionedKeyDestSw, kDifKeymgrVersionedKeyDestAes, kDifKeymgrVersionedKeyDestHmac, kDifKeymgrVersionedKeyDestKmac, kDifKeymgrVersionedKeyDestLast = kDifKeymgrVersionedKeyDestKmac }
	Destination of a versioned key generation operation. More...

Functions
DIF_WARN_UNUSED_RESULT dif_keymgr_result_t	dif_keymgr_init (dif_keymgr_params_t params, dif_keymgr_t *keymgr)
	Creates a new handle for key manager. More...

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t	dif_keymgr_configure (const dif_keymgr_t *keymgr, dif_keymgr_config_t config)
	Configures key manager with runtime information. More...

DIF_WARN_UNUSED_RESULT dif_keymgr_lockable_result_t	dif_keymgr_advance_state (const dif_keymgr_t keymgr, const dif_keymgr_state_params_t params)
	Advances key manager state. More...

DIF_WARN_UNUSED_RESULT dif_keymgr_lockable_result_t	dif_keymgr_disable (const dif_keymgr_t *keymgr)
	Disables key manager. More...

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t	dif_keymgr_get_status_codes (const dif_keymgr_t keymgr, dif_keymgr_status_codes_t status_codes)
	Gets the operational status of key manager. More...

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t	dif_keymgr_get_state (const dif_keymgr_t keymgr, dif_keymgr_state_t state)
	Gets the current state of key manager. More...

DIF_WARN_UNUSED_RESULT dif_keymgr_lockable_result_t	dif_keymgr_generate_identity_seed (const dif_keymgr_t *keymgr)
	Generates an identity seed. More...

DIF_WARN_UNUSED_RESULT dif_keymgr_lockable_result_t	dif_keymgr_generate_versioned_key (const dif_keymgr_t *keymgr, dif_keymgr_versioned_key_params_t params)
	Generates a versioned key. More...

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t	dif_keymgr_sideload_clear_set_enabled (const dif_keymgr_t *keymgr, dif_keymgr_toggle_t state)
	Starts or stops clearing of sideload keys. More...

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t	dif_keymgr_sideload_clear_get_enabled (const dif_keymgr_t keymgr, dif_keymgr_toggle_t state)
	Checks whether clearing of sideload keys is enabled or not. More...

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t	dif_keymgr_read_output (const dif_keymgr_t keymgr, dif_keymgr_output_t output)
	Reads the output of the last key manager operation. More...

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t	dif_keymgr_alert_force (const dif_keymgr_t *keymgr, dif_keymgr_alert_t alert)
	Forces a particular alert as if hardware had asserted it. More...

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t	dif_keymgr_irq_is_pending (const dif_keymgr_t keymgr, dif_keymgr_irq_t irq, bool is_pending)
	Returns whether a particular interrupt is currently pending. More...

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t	dif_keymgr_irq_acknowledge (const dif_keymgr_t *keymgr, dif_keymgr_irq_t irq)
	Acknowledges a particular interrupt, indicating to the hardware that it has been successfully serviced. More...

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t	dif_keymgr_irq_get_enabled (const dif_keymgr_t keymgr, dif_keymgr_irq_t irq, dif_keymgr_toggle_t state)
	Checks whether a particular interrupt is currently enabled or disabled. More...

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t	dif_keymgr_irq_set_enabled (const dif_keymgr_t *keymgr, dif_keymgr_irq_t irq, dif_keymgr_toggle_t state)
	Sets whether a particular interrupt is currently enabled or disabled. More...

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t	dif_keymgr_irq_force (const dif_keymgr_t *keymgr, dif_keymgr_irq_t irq)
	Forces a particular interrupt, causing it to be serviced as if hardware had asserted it. More...

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t	dif_keymgr_irq_disable_all (const dif_keymgr_t keymgr, dif_keymgr_irq_snapshot_t snapshot)
	Disables all interrupts, optionally snapshotting all toggle state for later restoration. More...

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t	dif_keymgr_irq_restore_all (const dif_keymgr_t keymgr, const dif_keymgr_irq_snapshot_t snapshot)
	Restores interrupts from the given snapshot. More...

Detailed Description

Key Manager Device Interface Functions

Definition in file dif_keymgr.h.

Data Structure Documentation

◆ dif_keymgr_params

struct dif_keymgr_params

Hardware instantiation parameters for key manager.

This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.

Definition at line 44 of file dif_keymgr.h.

Data Fields
mmio_region_t	base_addr	Base address of key manager registers.

◆ dif_keymgr_config

struct dif_keymgr_config

Runtime configuration for key manager.

This struct describes runtime information for one-time configuration of the hardware.

Definition at line 57 of file dif_keymgr.h.

Data Fields
uint16_t	entropy_reseed_interval	Number of key manager cycles before the entropy is reseeded. Key manager uses random values generated by the entropy source for initializing its state and clearing sideload keys. This value determines the frequency at which this random value is updated.

◆ dif_keymgr

struct dif_keymgr

A handle to a key manager.

This type should be treated as opaque by users.

Definition at line 73 of file dif_keymgr.h.

Data Fields
dif_keymgr_params_t	params	Hardware instantiation parameters.

◆ dif_keymgr_state_params

struct dif_keymgr_state_params

Parameters for a key manager state.

Definition at line 306 of file dif_keymgr.h.

Data Fields

uint32_t

binding_value[8]

This value is used by key manager to derive secret values and can be either a value that represents the contents of a boot stage, e.g.

a (truncated) hash, or a tag.

If it is a hash, changes in a boot stage will change the secret value, and consequently the versioned keys and identity seeds generated at subsequent boot stages. If it is a tag, those secret values, versioned keys, and identity seeds will be preserved across updates of the boot stage as long as the tag remains the same.

uint32_t max_key_version Maximum allowed version for keys generated at a state.

◆ dif_keymgr_versioned_key_params

struct dif_keymgr_versioned_key_params

Parameters for generating a versioned key.

Definition at line 497 of file dif_keymgr.h.

Data Fields
dif_keymgr_versioned_key_dest_t	dest	Destination of the generated versioned key. See also: `dif_keymgr_versioned_key_dest_t`.
uint32_t	salt[8]	Salt value to use for key generation.
uint32_t	version	Version value to use for key generation.

◆ dif_keymgr_output

struct dif_keymgr_output

Output of a key manager operation.

Key manager outputs are in two-shares.

Definition at line 565 of file dif_keymgr.h.

Data Fields
uint32_t	value[2][8]

Typedef Documentation

◆ dif_keymgr_alert_t

typedef enum dif_keymgr_alert dif_keymgr_alert_t

Key manager alerts.

Key manager generates alerts when it encounters a hardware or software error. Clients can use dif_keymgr_get_status_codes() to determine the type of error that occurred.

◆ dif_keymgr_config_t

typedef struct dif_keymgr_config dif_keymgr_config_t

Runtime configuration for key manager.

This struct describes runtime information for one-time configuration of the hardware.

◆ dif_keymgr_irq_snapshot_t

typedef uint32_t dif_keymgr_irq_snapshot_t

A snapshot of the enablement state of key manager interrupts.

This is an opaque type, to be used with the dif_keymgr_irq_disable_all() and dif_keymgr_irq_restore_all() functions.

Definition at line 148 of file dif_keymgr.h.

◆ dif_keymgr_output_t

typedef struct dif_keymgr_output dif_keymgr_output_t

Output of a key manager operation.

Key manager outputs are in two-shares.

◆ dif_keymgr_params_t

typedef struct dif_keymgr_params dif_keymgr_params_t

Hardware instantiation parameters for key manager.

This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.

◆ dif_keymgr_state_t

typedef enum dif_keymgr_state dif_keymgr_state_t

Key manager states.

Key manager has seven states that control its operation. During secure boot, key manager transitions between these states sequentially and these transitions are irreversible until a power cycle.

The secret value of key manager changes at each state transition in a well-defined manner, thus its meaning is tied to the current state of key manager.

The functionality of key manager is directly tied to the life cycle controller peripheral and it is explicitly disabled during specific life cycle stages. If key manager has not been initialized, it cannot be initialized until it is enabled by life cycle controller. If key manager is disabled by life cycle controller while it is in an operational state, it immediately wipes its contents and transitions to Disabled state.

◆ dif_keymgr_status_code_t

typedef enum dif_keymgr_status_code dif_keymgr_status_code_t

Status code bit flags.

◆ dif_keymgr_status_codes_t

typedef uint8_t dif_keymgr_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 & kDifKeymgrStatusCodeIdle);

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

bool is_idle_and_ok = (status_codes == kDifKeymgrStatusCodeIdle);

◆ dif_keymgr_t

typedef struct dif_keymgr dif_keymgr_t

A handle to a key manager.

This type should be treated as opaque by users.

◆ dif_keymgr_versioned_key_dest_t

typedef enum dif_keymgr_versioned_key_dest dif_keymgr_versioned_key_dest_t

Destination of a versioned key generation operation.

Key manager can make the output of a versioned key generation operation available to software or sideload it directly to a peripheral device. When the destination is a peripheral device, the output of the operation is not visible to software and a different derivation constant is used for each peripheral.

Enumeration Type Documentation

◆ dif_keymgr_alert

enum dif_keymgr_alert

Key manager alerts.

Key manager generates alerts when it encounters a hardware or software error. Clients can use dif_keymgr_get_status_codes() to determine the type of error that occurred.

Enumerator

kDifKeymgrAlertHardware

A hardware error occurred.

This alert is triggered when the hardware encounters an error condition that cannot be caused by the software, e.g. invalid KMAC commands, states, or outputs.

kDifKeymgrAlertSoftware

A software error occurred.

This alert is triggered when the software attempts to start an invalid operation, e.g. attempting to generate keys when the key manager is at Initialized state, or use invalid inputs, e.g. a key with a forbidden version.

Definition at line 157 of file dif_keymgr.h.

◆ dif_keymgr_irq

enum dif_keymgr_irq

Key manager interrupts.

Enumerator

kDifKeymgrIrqDone

Operation was completed.

This interrupt is triggered regardless of the outcome of the operation. Clients can use dif_keymgr_get_status_codes() to determine whether a key manager operation was successful or not.

Definition at line 127 of file dif_keymgr.h.

◆ dif_keymgr_lockable_result

enum dif_keymgr_lockable_result

Result of a key manager operation that writes to lockable registers.

Enumerator
kDifKeymgrLockableOk	The call succeeded.
kDifKeymgrLockableError	A non-specific error occurred and the hardware is in an invalid or irrecoverable state.
kDifKeymgrLockableBadArg	The caller supplied invalid arguments but the call did not cause any side-effects and the hardware is in a valid and recoverable state.
kDifKeymgrLockableLocked	The register that needs to be written to is locked.

Definition at line 103 of file dif_keymgr.h.

◆ dif_keymgr_result

enum dif_keymgr_result

Result of a key manager operation.

Enumerator
kDifKeymgrOk	The call succeeded.
kDifKeymgrError	A non-specific error occurred and the hardware is in an invalid or irrecoverable state.
kDifKeymgrBadArg	The caller supplied invalid arguments but the call did not cause any side-effects and the hardware is in a valid and recoverable state.

Definition at line 83 of file dif_keymgr.h.

◆ dif_keymgr_state

enum dif_keymgr_state

Key manager states.

Key manager has seven states that control its operation. During secure boot, key manager transitions between these states sequentially and these transitions are irreversible until a power cycle.

The secret value of key manager changes at each state transition in a well-defined manner, thus its meaning is tied to the current state of key manager.

The functionality of key manager is directly tied to the life cycle controller peripheral and it is explicitly disabled during specific life cycle stages. If key manager has not been initialized, it cannot be initialized until it is enabled by life cycle controller. If key manager is disabled by life cycle controller while it is in an operational state, it immediately wipes its contents and transitions to Disabled state.

Enumerator
kDifKeymgrStateReset	Reset state. This is the initial state of key manager after PoR. At this state, the secret value of key manager is non-deterministic, i.e. some value based on the physical characteristics of the device and environment conditions.
kDifKeymgrStateInitialized	Initialized state. Secret value of key manager is initialized with random values generated by the entropy source. This is not an operational state and the key manager state must be advanced one more time before keys or identity seeds can be generated.
kDifKeymgrStateCreatorRootKey	CreatorRootKey state. This is the first operational state of key manager. At this state, key manager can generate a versioned creator key or a creator identity seed that can be used to generate a creator identity using an asymmetric KDF.
kDifKeymgrStateOwnerIntermediateKey	OwnerIntermediateKey state. This is the second operational state of key manager. At this state, key manager can generate a versioned intermediate owner key or an intermediate owner identity seed that can be used to generate an intermediate owner identity using an asymmetric KDF.
kDifKeymgrStateOwnerRootKey	OwnerRootKey state. This is the last operational state of key manager. At this state, key manager can generate a versioned owner key or an owner identity seed that can be used to generate an owner identity using an asymmetric KDF.
kDifKeymgrStateDisabled	Disabled state. This is a terminal state where key manager is no longer operational. At this state, the secret value of key manager is a random value.
kDifKeymgrStateInvalid	Invalid state. Keymgr is in an invalid state and must be reset.

Definition at line 200 of file dif_keymgr.h.

◆ dif_keymgr_status_code

enum dif_keymgr_status_code

Status code bit flags.

◆ dif_keymgr_toggle

enum dif_keymgr_toggle

Enumeration for enabling/disabling various functionality.

Enumerator
kDifKeymgrToggleEnabled	Enabled state.
kDifKeymgrToggleDisabled	Disabled state.

Definition at line 26 of file dif_keymgr.h.

◆ dif_keymgr_versioned_key_dest

enum dif_keymgr_versioned_key_dest

Destination of a versioned key generation operation.

Key manager can make the output of a versioned key generation operation available to software or sideload it directly to a peripheral device. When the destination is a peripheral device, the output of the operation is not visible to software and a different derivation constant is used for each peripheral.

Enumerator
kDifKeymgrVersionedKeyDestSw	Store the generated versioned key in software visible registers. The generated versioned key can be read by calling `dif_keymgr_read_output()` after verifying that the operation was successful using `dif_keymgr_get_status_codes()`.
kDifKeymgrVersionedKeyDestAes	Sideload the generated versioned key to AES device.
kDifKeymgrVersionedKeyDestHmac	Sideload the generated versioned key to HMAC device.
kDifKeymgrVersionedKeyDestKmac	Sideload the generated versioned key to KMAC device.

Definition at line 467 of file dif_keymgr.h.

Function Documentation

◆ dif_keymgr_advance_state()

DIF_WARN_UNUSED_RESULT dif_keymgr_lockable_result_t dif_keymgr_advance_state	(	const dif_keymgr_t *	keymgr,
		const dif_keymgr_state_params_t *	params
	)

Advances key manager state.

This function instructs key manager to transition to the next state, i.e. Reset -> Initialized -> CreatorRootKey -> OwnerIntermediateKey -> OwnerRootKey -> Disabled. Once a state transition starts, key manager locks the control register until the transition is complete. State transitions are irreversible until a power cycle.

The entropy source must be initialized before this function is called. After PoR, key manager is in Reset state with a non-deterministic secret value. The first call to this function after PoR causes key manager to initialize its secret value using the random values generated by the entropy source and transition to Initialized state.

params is required when the next state is an operational state, i.e. CreatorRootKey, OwnerIntermediateKey, or OwnerRootKey. It must be NULL for all other cases.

This is an asynchronous function because key manager state transitions involve KMAC operations that can take some time to complete. Clients must check the status of key manager using dif_keymgr_get_status_codes() before calling other functions in this library.

Parameters

keymgr	A key manager handle.
params	The binding and max key version value for the next state.

Returns: The result of the operation.

Definition at line 300 of file dif_keymgr.c.

◆ dif_keymgr_alert_force()

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t dif_keymgr_alert_force	(	const dif_keymgr_t *	keymgr,
		dif_keymgr_alert_t	alert
	)

Forces a particular alert as if hardware had asserted it.

Parameters

keymgr	A key manager handle.
alert	An alert type.

Returns: The result of the operation.

Definition at line 597 of file dif_keymgr.c.

◆ dif_keymgr_configure()

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t dif_keymgr_configure	(	const dif_keymgr_t *	keymgr,
		dif_keymgr_config_t	config
	)

Configures key manager with runtime information.

This function should need to be called once for the lifetime of keymgr.

Parameters

keymgr	A key manager handle.
config	Runtime configuration parameters.

Returns: The result of the operation.

Definition at line 286 of file dif_keymgr.c.

◆ dif_keymgr_disable()

DIF_WARN_UNUSED_RESULT dif_keymgr_lockable_result_t dif_keymgr_disable ( const dif_keymgr_t * keymgr )

Disables key manager.

This function disables key manager until the next power cycle by making it transition to Disabled state. Disabled state is a terminal state where key manager is no longer operational and its secret value is a random value.

Parameters

keymgr A key manager handle.

Returns: The result of the operation.

Definition at line 372 of file dif_keymgr.c.

◆ dif_keymgr_generate_identity_seed()

DIF_WARN_UNUSED_RESULT dif_keymgr_lockable_result_t dif_keymgr_generate_identity_seed ( const dif_keymgr_t * keymgr )

Generates an identity seed.

This function requests key manager to generate an identity seed using its current secret value. Clients must first verify that the operation was successful using dif_keymgr_get_status_codes() before reading the generated identity seed using dif_keymgr_read_output().

The generated seed can be used to generate an identity using an asymmetric KDF.

Parameters

keymgr A key manager handle.

Returns: The result of the operation.

Definition at line 483 of file dif_keymgr.c.

◆ dif_keymgr_generate_versioned_key()

DIF_WARN_UNUSED_RESULT dif_keymgr_lockable_result_t dif_keymgr_generate_versioned_key	(	const dif_keymgr_t *	keymgr,
		dif_keymgr_versioned_key_params_t	params
	)

Generates a versioned key.

This function requests key manager to generate a versioned key using its current secret value and the provided parameters. The generated key can be sideloaded directly to a peripheral device or made visible to software using params.dest. If the destination is software, clients must first verify that the operation was successful using dif_keymgr_get_status_codes() before reading the generated key using dif_keymgr_read_output().

Parameters

keymgr	A key manager handle.
params	Key generation parameters.

Returns: The result of the operation.

Definition at line 501 of file dif_keymgr.c.

◆ dif_keymgr_get_state()

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t dif_keymgr_get_state	(	const dif_keymgr_t *	keymgr,
		dif_keymgr_state_t *	state
	)

Gets the current state of key manager.

Parameters

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

Returns: The result of the operation.

Definition at line 447 of file dif_keymgr.c.

◆ dif_keymgr_get_status_codes()

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t dif_keymgr_get_status_codes	(	const dif_keymgr_t *	keymgr,
		dif_keymgr_status_codes_t *	status_codes
	)

Gets the operational status of key manager.

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

Parameters

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

Returns: The result of the operation.

Definition at line 390 of file dif_keymgr.c.

◆ dif_keymgr_init()

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t dif_keymgr_init	(	dif_keymgr_params_t	params,
		dif_keymgr_t *	keymgr
	)

Creates a new handle for key manager.

This function does not actuate the hardware and must be called to initialize the handle that must be passed to other functions in this library in each boot stage. A typical usage of this library during different secure boot stages is as follows:

In Mask ROM:
- Create a new handle: dif_keymgr_init().
- Configure hardware: dif_keymgr_configure().
- Initialize state: dif_keymgr_advance_state(), dif_keymgr_get_status_codes(), dif_keymgr_get_state().
- Advance state: dif_keymgr_advance_state(), dif_keymgr_get_status_codes(), dif_keymgr_get_state().
In subsequent boot stages, i.e. ROM_EXT, BL0, kernel:
- Create a new handle: dif_keymgr_init().
- Generate keys and/or identity seeds: dif_keymgr_generate_versioned_key(), dif_keymgr_generate_identity_seed(), dif_keymgr_get_status_codes().
- Read output (if applicable): dif_keymgr_read_output().
- Advance state: dif_keymgr_advance_state(), dif_keymgr_get_status_codes(), dif_keymgr_get_state().

Parameters

	params	Hardware instantiation parameters.
[out]	keymgr	Out-param for the initialized handle.

Returns: The result of the operation.

Definition at line 275 of file dif_keymgr.c.

◆ dif_keymgr_irq_acknowledge()

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t dif_keymgr_irq_acknowledge	(	const dif_keymgr_t *	keymgr,
		dif_keymgr_irq_t	irq
	)

Acknowledges a particular interrupt, indicating to the hardware that it has been successfully serviced.

Parameters

keymgr	A key manager handle.
irq	An interrupt type.

Returns: The result of the operation.

Definition at line 637 of file dif_keymgr.c.

◆ dif_keymgr_irq_disable_all()

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t dif_keymgr_irq_disable_all	(	const dif_keymgr_t *	keymgr,
		dif_keymgr_irq_snapshot_t *	snapshot
	)

Disables all interrupts, optionally snapshotting all toggle state for later restoration.

Parameters

	keymgr	A key manager handle.
[out]	snapshot	Out-param for the snapshot; may be `NULL`.

Returns: The result of the operation.

Definition at line 699 of file dif_keymgr.c.

◆ dif_keymgr_irq_force()

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t dif_keymgr_irq_force	(	const dif_keymgr_t *	keymgr,
		dif_keymgr_irq_t	irq
	)

Forces a particular interrupt, causing it to be serviced as if hardware had asserted it.

Parameters

keymgr	A key manager handle.
irq	An interrupt type.

Returns: The result of the operation.

Definition at line 685 of file dif_keymgr.c.

◆ dif_keymgr_irq_get_enabled()

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t dif_keymgr_irq_get_enabled	(	const dif_keymgr_t *	keymgr,
		dif_keymgr_irq_t	irq,
		dif_keymgr_toggle_t *	state
	)

Checks whether a particular interrupt is currently enabled or disabled.

Parameters

	keymgr	A key manager handle.
	irq	An interrupt type.
[out]	state	Out-param for toggle state of the interrupt.

Returns: The result of the operation.

Definition at line 651 of file dif_keymgr.c.

◆ dif_keymgr_irq_is_pending()

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t dif_keymgr_irq_is_pending	(	const dif_keymgr_t *	keymgr,
		dif_keymgr_irq_t	irq,
		bool *	is_pending
	)

Returns whether a particular interrupt is currently pending.

Parameters

	keymgr	A key manager handle.
	irq	An interrupt type.
[out]	is_pending	Out-param for whether the interrupt is pending.

Returns: The result of the operation.

Definition at line 621 of file dif_keymgr.c.

◆ dif_keymgr_irq_restore_all()

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t dif_keymgr_irq_restore_all	(	const dif_keymgr_t *	keymgr,
		const dif_keymgr_irq_snapshot_t *	snapshot
	)

Restores interrupts from the given snapshot.

This function can be used with dif_keymgr_irq_disable_all() to temporary interrupt save-and-restore.

Parameters

keymgr	A key manager handle.
snapshot	A snapshot to restore from.

Returns: The result of the operation.

Definition at line 715 of file dif_keymgr.c.

◆ dif_keymgr_irq_set_enabled()

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t dif_keymgr_irq_set_enabled	(	const dif_keymgr_t *	keymgr,
		dif_keymgr_irq_t	irq,
		dif_keymgr_toggle_t	state
	)

Sets whether a particular interrupt is currently enabled or disabled.

Parameters

keymgr	A key manager handle.
irq	An interrupt type.
state	The new toggle state for the interrupt.

Returns: The result of the operation.

Definition at line 666 of file dif_keymgr.c.

◆ dif_keymgr_read_output()

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t dif_keymgr_read_output	(	const dif_keymgr_t *	keymgr,
		dif_keymgr_output_t *	output
	)

Reads the output of the last key manager operation.

After starting a key manager operation, clients must verify that the operation was successful using dif_keymgr_get_status_codes() before calling this function.

When key manager is used for versioned key generation, the output of this function is valid only if the destination of the operation was kDifKeymgrVersionedKeyDestSw.

◆ dif_keymgr_sideload_clear_get_enabled()

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t dif_keymgr_sideload_clear_get_enabled	(	const dif_keymgr_t *	keymgr,
		dif_keymgr_toggle_t *	state
	)

Checks whether clearing of sideload keys is enabled or not.

Parameters

	keymgr	A key manager handle.
[out]	Out-param	for the current toggle state of sideload clear.

Returns: The result of the operation.

Definition at line 567 of file dif_keymgr.c.

◆ dif_keymgr_sideload_clear_set_enabled()

DIF_WARN_UNUSED_RESULT dif_keymgr_result_t dif_keymgr_sideload_clear_set_enabled	(	const dif_keymgr_t *	keymgr,
		dif_keymgr_toggle_t	state
	)

Starts or stops clearing of sideload keys.

When a key is generated to be sideloaded to a hardware peripheral, key manager stores it in a set of storage registers. Calling this function with state set to kDifKeymgrToggleEnabled causes key manager to clear sideload keys continously using random values from the entropty source. Callers must disable clearing of sideload keys to resume normal sideload operation.

Parameters

keymgr	A key manager handle.
state	The new toggle state for sideload clear.

Returns: The result of the operation.

Definition at line 553 of file dif_keymgr.c.

Enumerator
kDifKeymgrStatusCodeIdle	Key manager is idle.
kDifKeymgrStatusCodeInvalidOperation	Software invoked an invalid operation.
kDifKeymgrStatusCodeInvalidKmacCommand	Key manager issued an invalid command to KMAC interface.
kDifKeymgrStatusCodeInvalidKmacInput	Key manager issued invalid data to KMAC interface.
kDifKeymgrStatusCodeInvalidKmacOutput	KMAC returned an invalid output.

(dcee03a)

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ dif_keymgr_params

◆ dif_keymgr_config

◆ dif_keymgr

◆ dif_keymgr_state_params

◆ dif_keymgr_versioned_key_params

◆ dif_keymgr_output

Typedef Documentation

◆ dif_keymgr_alert_t

◆ dif_keymgr_config_t

◆ dif_keymgr_irq_snapshot_t

◆ dif_keymgr_output_t

◆ dif_keymgr_params_t

◆ dif_keymgr_state_t

◆ dif_keymgr_status_code_t

◆ dif_keymgr_status_codes_t

◆ dif_keymgr_t

◆ dif_keymgr_versioned_key_dest_t

Enumeration Type Documentation

◆ dif_keymgr_alert

◆ dif_keymgr_irq

◆ dif_keymgr_lockable_result

◆ dif_keymgr_result

◆ dif_keymgr_state

◆ dif_keymgr_status_code

◆ dif_keymgr_toggle

◆ dif_keymgr_versioned_key_dest

Function Documentation

◆ dif_keymgr_advance_state()

◆ dif_keymgr_alert_force()

◆ dif_keymgr_configure()

◆ dif_keymgr_disable()

◆ dif_keymgr_generate_identity_seed()

◆ dif_keymgr_generate_versioned_key()

◆ dif_keymgr_get_state()

◆ dif_keymgr_get_status_codes()

◆ dif_keymgr_init()

◆ dif_keymgr_irq_acknowledge()

◆ dif_keymgr_irq_disable_all()

◆ dif_keymgr_irq_force()

◆ dif_keymgr_irq_get_enabled()

◆ dif_keymgr_irq_is_pending()

◆ dif_keymgr_irq_restore_all()

◆ dif_keymgr_irq_set_enabled()

◆ dif_keymgr_read_output()

◆ dif_keymgr_sideload_clear_get_enabled()

◆ dif_keymgr_sideload_clear_set_enabled()