Software APIs
Data Structures | Typedefs | Enumerations | Functions
dif_keymgr.h File Reference

(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"

Go to the source code of this file.

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

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

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

Output of a key manager operation.

Key manager outputs are in two-shares.

◆ 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

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

Status code bit flags.

See also: dif_keymgr_status_codes_t.

◆ 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);

See also: dif_keymgr_status_code_t.

Definition at line 413 of file dif_keymgr.h.

◆ 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

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

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

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

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

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

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

Status code bit flags.

See also: dif_keymgr_status_codes_t.

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.

Definition at line 376 of file dif_keymgr.h.

◆ 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

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
keymgrA key manager handle.
paramsThe 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
keymgrA key manager handle.
alertAn 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
keymgrA key manager handle.
configRuntime 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
keymgrA 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
keymgrA 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
keymgrA key manager handle.
paramsKey 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
keymgrA key manager handle.
[out]stateOut-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
keymgrA key manager handle.
[out]status_codesOut-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:

Parameters
paramsHardware instantiation parameters.
[out]keymgrOut-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
keymgrA key manager handle.
irqAn 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
keymgrA key manager handle.
[out]snapshotOut-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
keymgrA key manager handle.
irqAn 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
keymgrA key manager handle.
irqAn interrupt type.
[out]stateOut-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
keymgrA key manager handle.
irqAn interrupt type.
[out]is_pendingOut-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
keymgrA key manager handle.
snapshotA 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
keymgrA key manager handle.
irqAn interrupt type.
stateThe 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.

See also: dif_keymgr_output_t.

Parameters
keymgrA key manager handle.
[out]outputOut-param for key manager output.
Returns
The result of the operation.

Definition at line 581 of file dif_keymgr.c.

◆ 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
keymgrA key manager handle.
[out]Out-paramfor 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
keymgrA key manager handle.
stateThe new toggle state for sideload clear.
Returns
The result of the operation.

Definition at line 553 of file dif_keymgr.c.