Derived KEK TISCI Description¶
This chapter provides information on System Firmware API for Derived Key Encryption Key(DKEK) management. The available API are listed below.
| TISCI Message ID | Message Name | Available in GP | Avialable in HS-FS |
|---|---|---|---|
| 0x9003 | TISCI_MSG_SA2UL_SET_DKEK | Yes* | Yes |
| 0x9004 | TISCI_MSG_SA2UL_RELEASE_DKEK | Yes* | Yes |
| 0x9029 | TISCI_MSG_SA2UL_GET_DKEK | Yes* | Yes |
Note
On GP devices, DKEK APIs return unconditional success but do not actually involve any step to derive or program the DKEK values
This document must be read along side
- Using Derived KEK on HS devices and
- Security Board Configuration, specifically Derived KEK Management
API Description¶
TISCI Message ID¶
TISCI_MSG_SA2UL_SET_DKEK (0x9003U)
Message to derive a KEK and set SA2UL DKEK register
struct tisci_msg_sa2ul_set_dkek_req
TISCI Request for setting DKEK in SA2UL registers
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | Generic TISCI message header. |
| sa2ul_instance | u8 | SA2UL instance number - set to 0 |
| kdf_label_len | u8 | Length of “Label” input to KDF |
| kdf_context_len | u8 | Length of “Context” input to KDF |
| kdf_label_and_context | u8 | ”Label” and “Context” bytes are stored in this array one after another. Maximum length of this field is KDF_LABEL_AND_CONTEXT_LEN_MAX |
struct tisci_msg_sa2ul_set_dkek_resp
TISCI Response for setting DKEK in SA2UL registers
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | Generic TISCI message header. |
KDF_LABEL_AND_CONTEXT_LEN_MAX 41U
See API Notes below.
TISCI Message ID¶
TISCI_MSG_SA2UL_RELEASE_DKEK (0x9004U)
Message to erase the DKEK register
struct tisci_msg_sa2ul_release_dkek_req
TISCI Request for releasing DKEK
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | Generic TISCI message header. |
| sa2ul_instance | u8 | SA2UL instance number - set to 0 |
struct tisci_msg_sa2ul_release_dkek_resp
TISCI Response for Releasing DKEK
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | Generic TISCI message header. |
See API Notes below.
TISCI Message ID¶
TISCI_MSG_SA2UL_GET_DKEK (0x9029U)
Message to derive a KEK and return it via TISCI
SA2UL_DKEK_KEY_LEN (32U)
struct tisci_msg_sa2ul_get_dkek_req
TISCI Request for getting DKEK via TISCI
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | Generic TISCI message header. |
| sa2ul_instance | u8 | SA2UL instance number - set to 0 |
| kdf_label_len | u8 | Length of “Label” input to KDF |
| kdf_context_len | u8 | Length of “Context” input to KDF |
| kdf_label_and_context | u8 | ”Label” and “Context” bytes are stored in this array one after another. Maximum length of this field is KDF_LABEL_AND_CONTEXT_LEN_MAX |
struct tisci_msg_sa2ul_get_dkek_resp
TISCI Response for requesting DKEK
| Parameter | Type | Description |
|---|---|---|
| hdr | struct tisci_header | Generic TISCI message header. |
| dkek | u8 | Array containing Derived KEK. Length is 32 bytes |
See API Notes below.
API Notes¶
- The total length of the Label and Context fields below is limited by the size of the TISCI messages(see Secure Messaging Header) to 41 bytes.
- System Firmware only support
sa2ul_instancevalue of 0 in the API below.