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 Previous Message Name
0x9003 TISCI_MSG_CRYPTO_SET_DKEK Yes* Yes TISCI_MSG_SA2UL_SET_DKEK
0x9004 TISCI_MSG_CRYPTO_RELEASE_DKEK Yes* Yes TISCI_MSG_SA2UL_RELEASE_DKEK
0x9029 TISCI_MSG_CRYPTO_GET_DKEK Yes* Yes TISCI_MSG_SA2UL_GET_DKEK

Note

The TISCI Message ID macros have been renamed. Please update your code to use the new names.

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

  1. Using Derived KEK on HS devices and
  2. Security Board Configuration, specifically Derived KEK Management

API Description

TISCI_MSG_CRYPTO_SET_DKEK - Set DKEK

Usage:

Message Type Normal
Secure Queue Only? Yes

TISCI Message ID

TISCI_MSG_CRYPTO_SET_DKEK          (0x9003U)

Message to derive a KEK and set DKEK register

struct tisci_msg_crypto_set_dkek_req

TISCI Request for setting DKEK in crypto engine registers

Parameter Type Description
hdr struct tisci_header Generic TISCI message header.
instance u8 crypto engine 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_crypto_set_dkek_resp

TISCI Response for setting DKEK in crypto engine registers

Parameter Type Description
hdr struct tisci_header Generic TISCI message header.

KDF_LABEL_AND_CONTEXT_LEN_MAX          41U

Note

The structures tisci_msg_sa2ul_set_dkek_req and tisci_msg_sa2ul_set_dkek_resp have been renamed to tisci_msg_crypto_set_dkek_req and tisci_msg_crypto_set_dkek_resp respectively. Please update your code to use the new names.

See API Notes below.

TISCI_MSG_CRYPTO_RELEASE_DKEK - Release DKEK

Usage:

Message Type Normal
Secure Queue Only? Yes

TISCI Message ID

TISCI_MSG_CRYPTO_RELEASE_DKEK          (0x9004U)

Message to erase the DKEK register

struct tisci_msg_crypto_release_dkek_req

TISCI Request for releasing DKEK

Parameter Type Description
hdr struct tisci_header Generic TISCI message header.
instance u8 Crypto instance number - set to 0

struct tisci_msg_crypto_release_dkek_resp

TISCI Response for Releasing DKEK

Parameter Type Description
hdr struct tisci_header Generic TISCI message header.

Note

The structures tisci_msg_sa2ul_release_dkek_req and tisci_msg_sa2ul_release_dkek_resp have been renamed to tisci_msg_crypto_release_dkek_req and tisci_msg_crypto_release_dkek_resp respectively. Please update your code to use the new names.

See API Notes below.

TISCI_MSG_CRYPTO_GET_DKEK - Get DKEK

Usage:

Message Type Normal
Secure Queue Only? Yes

TISCI Message ID

TISCI_MSG_CRYPTO_GET_DKEK          (0x9029U)

Message to derive a KEK and return it via TISCI

CRYPTO_DKEK_KEY_LEN          (32U)

struct tisci_msg_crypto_get_dkek_req

TISCI Request for getting DKEK via TISCI

Parameter Type Description
hdr struct tisci_header Generic TISCI message header.
instance u8 Crypto engine 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_crypto_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

Note

The structures tisci_msg_sa2ul_get_dkek_req and tisci_msg_sa2ul_get_dkek_resp have been renamed to tisci_msg_crypto_get_dkek_req and tisci_msg_crypto_get_dkek_resp respectively. Also, the MACRO SA2UL_DKEK_KEY_LEN has been renamed to CRYPTO_DKEK_KEY_LEN. Please update your code to use the new names.

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 instance value of 0 in the API below.