Runtime Keystore TISCI Description

Introduction

This section describes the APIs available to manage the Runtime Keystore in System Firmware.

TISCI Message ID	Message Name
0x900D	TISCI_MSG_KEYSTORE_WRITE
0x900E	TISCI_MSG_KEYSTORE_EXPORT_ALL
0x900F	TISCI_MSG_KEYSTORE_IMPORT_ALL
0x9016	TISCI_MSG_KEYSTORE_GEN_SKEY_FROM_RNG

TISCI_MSG_KEYSTORE_WRITE - Write the entire keystore contents

Keystore write allows the system designer to perform initial provisioning of keystore contents. This is the foundational keystore operation required by System Firmware in order to use any subsequent keystore or key service API.

The initial keys are generated off-line, packed into the defined keystore structure, and signed/encrypted with the active MPK/MEK. Binary format for the write payload is not yet finalized and is subject to change until further notice. As such, the details of the format are not published at this time. To receive details on the current binary format, please contact TI.

Usage

Message Type	Secure
Secure Queue Only?	Yes

TISCI Message ID

TISCI_MSG_KEYSTORE_WRITE          (0x900DU)

Message to write partitioning data and provisioned keys to the keystore memory

struct tisci_msg_keystore_write_req

Request for writing the entire keystore contents

Parameter	Type	Description
hdr	struct tisci_header	Common TI-SCI header
keystore_lo	u32	Lower 32-bit memory location of the signed and encrypted keystore contents
keystore_hi	u32	Higher 32-bit memory location of the signed and encrypted keystore contents

A user may unlock the keystore to write its contents using a signed and encrypted keystore structure. This operation is required for keystore initialization and is mandatorily the first keystore operation which must be executed in order to put the keystore in a valid state for subsequent operations.

struct tisci_msg_keystore_write_resp

Response to the keystore write

Parameter	Type	Description
hdr	struct tisci_header	Generic TISCI message header. ACK response indicates that the accompanying certificate was validated and the keystore contents were successfully decrypted, authenticated, and copied to the internal keystore memory. NACK response indicates that the keystore write could not be completed.

TISCI_MSG_KEYSTORE_EXPORT_ALL - Encrypt and export the contents of the keystore

Usage

Message Type	Secure
Secure Queue Only?	Yes

TISCI Message ID

TISCI_MSG_KEYSTORE_EXPORT_ALL          (0x900EU)

Message to encrypt and export the full keystore contents for saving to external storage

struct tisci_msg_keystore_export_req

Request for exporting the entire keystore contents

Parameter	Type	Description
hdr	struct tisci_header	Common TI-SCI header
keystore_lo	u32	Lower 32-bit memory location where the encrypted keystore contents will be placed to pass back to the host
keystore_hi	u32	Higher 32-bit memory location where the encrypted keystore contents will be placed to pass back to the host

The host will make the request to encrypt and export the entire keystore contents for saving to some storage mechanism to be made available for future re-import. Only the host who owns the keystore structure may execute this operation. The host is responsible for pre-allocating enough memory to fit the keystore structure and all encryption parameters.

Note

Subject to change: Keystore export API requires the host allocate at least CONFIG_SECURITY_KEYSTORE_SIZE + 0x30 bytes to allow sufficient space for System Firmware to copy authenticated encrypted contents. See runtime keystore chapter for the particular SoC family of interest for details on the exact size.

struct tisci_msg_keystore_export_resp

Response to the keystore export

Parameter	Type	Description
hdr	struct tisci_header	Generic TISCI message header. ACK response indicates that the keystore has been encrypted and copied into the host-provided memory. NACK response indicates that the keystore export could not be completed

TISCI_MSG_KEYSTORE_IMPORT_ALL - Import and decrypt a previously exported keystore

Usage

Message Type	Secure
Secure Queue Only?	Yes

TISCI Message ID

TISCI_MSG_KEYSTORE_IMPORT_ALL          (0x900FU)

Message to import and decrypt a previously exported keystore blob

struct tisci_msg_keystore_import_req

Request for importing a previously exported keystore

Parameter	Type	Description
hdr	struct tisci_header	Common TI-SCI header
keystore_lo	u32	Lower 32-bit memory location of the encrypted keystore contents provided by the host
keystore_hi	u32	Higher 32-bit memory location of the encrypted keystore contents provided by the host

struct tisci_msg_keystore_import_resp

Response to the keystore import

Parameter	Type	Description
hdr	struct tisci_header	Generic TISCI message header. ACK response indicates that the imported keystore has been successfully decrypted and authenticated. NACK response indicates that the keystore import could not be completed.

TISCI_MSG_KEYSTORE_GEN_SKEY_FROM_RNG - Generate a symmetric key from RNG and import it into keystore

Usage

Message Type	Secure
Secure Queue Only?	Yes

TISCI Message ID

TISCI_MSG_KEYSTORE_GEN_SKEY_FROM_RNG          (0x9016U)

Message to generate a symmetric key via RNG and save it in the runtime keystore

struct tisci_msg_keystore_gen_skey_from_rng_req

Request to generate symmetric key from RNG command

Parameter	Type	Description
hdr	struct tisci_header	Generic TISCI message header.
key_index	u8	Index in keystore where the generated key must be stored.
key_len_bytes	u8	length of the key in bytes.

struct tisci_msg_keystore_gen_skey_from_rng_resp

Response to generate symmetric key from RNG command

Parameter	Type	Description
hdr	struct tisci_header	Generic TISCI message header. ACK response indicates that the symmetric key of requested length has been successfully generated and populated into the keystore. NACK response indicates that the operation could not be completed