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

(8b2da8d)

Key Manager 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_autogen.h"

Go to the source code of this file.

Data Structures

struct  dif_keymgr_config
 Runtime configuration for 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...
 
struct  dif_keymgr_binding_value
 Attestation and sealing binding value. More...
 
struct  dif_keymgr_max_key_version
 

Typedefs

typedef enum dif_keymgr_sideload_clr dif_keymgr_sideload_clr_t
 A typical usage of this library during different secure boot stages is as follows: More...
 
typedef struct dif_keymgr_config dif_keymgr_config_t
 Runtime configuration for key manager. 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...
 
typedef struct dif_keymgr_binding_value dif_keymgr_binding_value_t
 Attestation and sealing binding value.
 
typedef struct dif_keymgr_max_key_version dif_keymgr_max_key_version_t
 

Enumerations

enum  dif_keymgr_sideload_clr {
  kDifKeyMgrSideLoadClearNone = 0,
  kDifKeyMgrSideLoadClearAes = 1,
  kDifKeyMgrSideLoadClearKmac = 2,
  kDifKeyMgrSideLoadClearOtbn = 3,
  kDifKeyMgrSideLoadClearAll = 7
}
 A typical usage of this library during different secure boot stages is as follows: 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,
  kDifKeymgrStatusCodeInvalidKmacInput = 1 << 2,
  kDifKeymgrStatusCodeInvalidKmacOutput = 1 << 3,
  kDifKeymgrStatusCodeInvalidState = 1 << 4
}
 Status code bit flags. More...
 
enum  dif_keymgr_versioned_key_dest {
  kDifKeymgrVersionedKeyDestSw,
  kDifKeymgrVersionedKeyDestAes,
  kDifKeymgrVersionedKeyDestKmac,
  kDifKeymgrVersionedKeyDestOtbn,
  kDifKeymgrVersionedKeyDestLast = kDifKeymgrVersionedKeyDestOtbn
}
 Destination of a versioned key generation operation. More...
 

Functions

OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_configure (const dif_keymgr_t *keymgr, dif_keymgr_config_t config)
 Configures key manager with runtime information. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_advance_state (const dif_keymgr_t *keymgr, const dif_keymgr_state_params_t *params)
 Advances key manager state. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_advance_state_raw (const dif_keymgr_t *keymgr)
 Advances key manager state without setting any of the required inputs. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_disable (const dif_keymgr_t *keymgr)
 Disables key manager. More...
 
OT_WARN_UNUSED_RESULT dif_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...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_get_state (const dif_keymgr_t *keymgr, dif_keymgr_state_t *state)
 Gets the current state of key manager. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_generate_identity_seed (const dif_keymgr_t *keymgr)
 Generates an identity seed. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_generate_versioned_key (const dif_keymgr_t *keymgr, dif_keymgr_versioned_key_params_t params)
 Generates a versioned key. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_sideload_clear_set_enabled (const dif_keymgr_t *keymgr, dif_toggle_t state)
 Starts or stops clearing of sideload keys. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_sideload_clear_get_enabled (const dif_keymgr_t *keymgr, dif_toggle_t *state)
 Checks whether clearing of sideload keys is enabled or not. More...
 
OT_WARN_UNUSED_RESULT dif_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...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_read_binding (const dif_keymgr_t *keymgr, dif_keymgr_binding_value_t *output)
 Reads both the attestation or the binding value set. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_read_max_key_version (const dif_keymgr_t *keymgr, dif_keymgr_max_key_version_t *versions)
 Reads the max key version of each stage. More...
 

Detailed Description

Key Manager Device Interface Functions

Definition in file dif_keymgr.h.


Data Structure Documentation

◆ 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 67 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_state_params

struct dif_keymgr_state_params

Parameters for a key manager state.

Definition at line 170 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 393 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 461 of file dif_keymgr.h.

Data Fields
uint32_t value[2][8]

◆ dif_keymgr_binding_value

struct dif_keymgr_binding_value

Attestation and sealing binding value.

Definition at line 488 of file dif_keymgr.h.

Data Fields
uint32_t attestation[8] Attestation binding value.
uint32_t sealing[8] Sealing binding value.

◆ dif_keymgr_max_key_version

struct dif_keymgr_max_key_version

Definition at line 510 of file dif_keymgr.h.

Data Fields
uint32_t creator_max_key_version Max creator key version.
uint32_t owner_int_max_key_version Max owner intermediate key version.
uint32_t owner_max_key_version Max owner key version.

Typedef Documentation

◆ dif_keymgr_config_t

Runtime configuration for key manager.

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

◆ dif_keymgr_output_t

Output of a key manager operation.

Key manager outputs are in two-shares.

◆ dif_keymgr_sideload_clr_t

A typical usage of this library during different secure boot stages is as follows:

◆ 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 310 of file dif_keymgr.h.

◆ 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_sideload_clr

A typical usage of this library during different secure boot stages is as follows:

Definition at line 50 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 96 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.

kDifKeymgrStatusCodeInvalidKmacInput 

Key manager issued invalid data to KMAC interface.

kDifKeymgrStatusCodeInvalidKmacOutput 

Software performed an invalid shadow update.

kDifKeymgrStatusCodeInvalidState 

Key manager encountered invalid state.

Definition at line 272 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.

kDifKeymgrVersionedKeyDestKmac 

Sideload the generated versioned key to KMAC device.

kDifKeymgrVersionedKeyDestOtbn 

Sideload the generated versioned key to Otbn device.

Definition at line 363 of file dif_keymgr.h.

Function Documentation

◆ dif_keymgr_advance_state()

OT_WARN_UNUSED_RESULT dif_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 257 of file dif_keymgr.c.

◆ dif_keymgr_advance_state_raw()

OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_advance_state_raw ( const dif_keymgr_t keymgr)

Advances key manager state without setting any of the required inputs.

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.

This function does not have a dif_keymgr_state_params_t parameter since these inputs are expected to be set before this function is called, e.g. when the chip is using rom as opposed to test_rom. See dif_keymgr_advance_state() if you need to set the binding value and max key version before advancing the state.

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.

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.
Returns
The result of the operation.

Definition at line 330 of file dif_keymgr.c.

◆ dif_keymgr_configure()

OT_WARN_UNUSED_RESULT dif_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 242 of file dif_keymgr.c.

◆ dif_keymgr_disable()

OT_WARN_UNUSED_RESULT dif_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 349 of file dif_keymgr.c.

◆ dif_keymgr_generate_identity_seed()

OT_WARN_UNUSED_RESULT dif_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 464 of file dif_keymgr.c.

◆ dif_keymgr_generate_versioned_key()

OT_WARN_UNUSED_RESULT dif_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 482 of file dif_keymgr.c.

◆ dif_keymgr_get_state()

OT_WARN_UNUSED_RESULT dif_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 428 of file dif_keymgr.c.

◆ dif_keymgr_get_status_codes()

OT_WARN_UNUSED_RESULT dif_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 368 of file dif_keymgr.c.

◆ dif_keymgr_read_binding()

OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_read_binding ( const dif_keymgr_t keymgr,
dif_keymgr_binding_value_t output 
)

Reads both the attestation or the binding value set.

Parameters
keymgrA key manager handle.
[out]outputValue read.
Returns
The result of the operation.

Definition at line 577 of file dif_keymgr.c.

◆ dif_keymgr_read_max_key_version()

OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_read_max_key_version ( const dif_keymgr_t keymgr,
dif_keymgr_max_key_version_t versions 
)

Reads the max key version of each stage.

Parameters
keymgrA key manager handle.
versionStruct with the max versions set.
Returns
dif_result_t

Definition at line 594 of file dif_keymgr.c.

◆ dif_keymgr_read_output()

OT_WARN_UNUSED_RESULT dif_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 561 of file dif_keymgr.c.

◆ dif_keymgr_sideload_clear_get_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_sideload_clear_get_enabled ( const dif_keymgr_t keymgr,
dif_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 548 of file dif_keymgr.c.

◆ dif_keymgr_sideload_clear_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_keymgr_sideload_clear_set_enabled ( const dif_keymgr_t keymgr,
dif_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 533 of file dif_keymgr.c.