Sample Applications#

The following diagram shows an overview of secure sample applications provided by Jetson Linux:

A PTA: jetson-user-key PTA in the OP-TEE OS.
Three CAs and TAs: hwkey-agent TA and luks TA with corresponding CAs in the normal-world user space, and cpubl-payload-dec TA with the corresponding CA in L4T Launcher.

Jetson User Key PTA#

The Jetson user key TA is a pseudo-TA that is bundled with OP-TEE OS and runs at the OS layer. This TA provides APIs to the user TA and exports these APIs to the user TA via the GlobalPlatform TEE API.

Note

Before studying the service interface of this PTA, you should understand how the GlobalPlatform TEE API defines the application communication interface and flow. This pattern applies to communication between TA and TA, TA and PTA, and CA and TA.

The user TA initializes a session with the PTA using TEE_OpenTASession. Establishing a session requires the UUID of the PTA as input so that it knows which PTA to communicate with.
After the session is created, the TA calls the service in the PTA using TEE_InvokeTACommand, with the command ID and parameters stored in the structure TEE_Param. The TEE_Param structure can store two types of data, a value or a memory reference pointer.

The jetson-user-key PTA provides EKB key management, user key services, random number generator, key derivation function, and CPUBL payload decryption services.

EKB Key Management#

The jetson-user-key PTA shows how to derive keys from the SE keyslot and derive other keys for different security purposes.

OEM_K1: Root key for RPMB_Key and EKB_RK (Jetson Orin series only).
OEM_K2: Root key for SSK_RK (Jetson Orin series only).
PSC_OEM_KDK1: Root key for EKB_RK and HUK_RK (Jetson Thor series only).
RPMB_Key: Per-device unique key derived from OEM_K1. This key should be provisioned to the eMMC device and generated at runtime. The runtime generated key must be exactly the same as the key provisioned to the eMMC device.

Note

EMMC RPMB is not supported for the Jetson Thor series.
SSK_RK: Per-device unique key derived from OEM_K2 (Jetson Orin series only). You can use it to encrypt data that is bound to the device. The jetson-user-key PTA does not use this key, but only shows how to derive it.
HUK_RK: Hardware unique key derived from TZ_RK (Jetson Thor series only).
User Keys: User-defined keys stored in the EKB.

The jetson-user-key PTA extracts user-defined keys from EKB and saves the keys into a linked list. For security reasons, all the keys should not leave the jetson-user-key PTA, at least not leave the secure world, and the PTA services can only be accessed by user TA.

User Key Services#

The jetson-user-key pta provides three APIs for users to get keys.

The user-space TA can get a derived key from the user-defined keys through jetson-user-key PTA interface via command ID JETSON_USER_KEY_CMD_GEN_KEY and Key_tag.
The user-space TA can get a per-device unique derived key from a user-defined keys through jetson-user-key PTA interface via command ID JETSON_USER_KEY_CMD_GEN_UNIQUE_KEY_BY_EKB and Key_tag.
The user-space TA can also get the user keys through the jetson-user-key PTA interface directly via the command ID JETSON_USER_KEY_CMD_GET_EKB_KEY and Key_tag.

Note

Although we provide the API for the user TA to directly get the user keys, we do not recommend doing so because it causes the user key to leave the jetson-user-key PTA.

Random Number Generator#

The GlobalPlatform TEE Internal API provides an interface for the user TA to get random numbers from OP-TEE. This hooks into HW RNG.

/* Cryptographic Operations API - Random Number Generation Functions */
void TEE_GenerateRandom(void *randomBuffer, uint32_t randomBufferLen);

In addition to this, the user TA can also access the hardware RNG through jetson-user-key PTA interface via the command ID JETSON_USER_KEY_CMD_GET_RANDOM.

Key Derivation Function#

The jetson-user-key PTA implements the software-based NIST-SP 800-108 KDF as a counter-mode KDF with AES-CMAC and HMAC-SHA256 as PRF. For the formula definitions that these helpers compute, see Key Hierarchy and Derivation.

/*
 * Software-based NIST-SP 800-108 HMAC KDF and NIST-SP 800-108 CMAC KDF
 * derives keys from a key in a key buffer.
 *
 * key          [in] input key for derivation.
 * key_len      [in] length in bytes of the input key.
 * context      [in] a pointer to a NIST-SP 800-108 context string.
 * context_len  [in] length in bytes of the context.
 * label        [in] a pointer to a NIST-SP 800-108 label string.
 * label_len    [in] length in bytes of the label.
 * dk_len       [in] length of the derived key in bytes;
 *                   may be 16 (128 bits) or any multiple of 16.
 * out_dk       [out] a pointer to the derived key. The function stores
 *                    its result in this location.
 */
 TEE_Result nist_sp_800_108_hmac_kdf(const uint8_t *key,
                                     uint32_t key_len,
                                     char const *context,
                                     uint32_t context_len,
                                     char const *label,
                                     uint32_t label_len,
                                     uint32_t dk_len,
                                     uint8_t *out_dk);
 TEE_Result nist_sp_800_108_cmac_kdf(const uint8_t *key,
                                     uint32_t key_len,
                                     char const *context,
                                     uint32_t context_len,
                                     char const *label,
                                     uint32_t label_len,
                                     uint32_t dk_len,
                                     uint8_t *out_dk);

The user TA can access the software-based NIST 800-108 KDF through the jetson-user-key PTA interface via the command ID JETSON_USER_KEY_CMD_GEN_KEY.

Note

The default Key Derivation Function for Jetson Orin series is nist_sp_800_108_cmac_kdf, and the default Key Derivation function for Jetson Thor series is nist_sp_800_108_hmac_kdf.

CPUBL Payload Decryption Services#

The jetson-user-key PTA provides UEFI payload decryption services, supporting decryption of UEFI payloads during the boot process. The PTA gets the UEFI payload encryption key from the user key linked list and then uses the key to decrypt the UEFI payload.

Note

The CPUBL payload decryption is currently not supported in the Jetson AGX Thor series.

HWKEY AGENT CA and TA#

The hwkey-agent CA is a command-line program that illustrates how to encrypt and decrypt data using user-defined keys stored in the EKB and get random numbers from the hwkey-agent TA.

This hwkey-agent TA is a user-space TA that provides two functions for the hwkey-agent CA: data encryption and decryption, and getting random numbers.

Data Encryption and Decryption#

Typically, the hwkey-agent CA issues a request to encrypt or decrypt data. The hwkey-agent TA transparently transmits the request to the jetson-user-key PTA to get a derived key based on a pre-defined user key stored in EKB, and then uses this key to encrypt or decrypt the data.

For demonstration only, the jetson-user-key PTA uses the hwkey key to derive the encrypt or decrypt key.

Get a Random Number#

Typically, the hwkey-agent CA issues a request to get a random number. The hwkey-agent TA does not process the request directly; instead it transparently transmits the request to the jetson-user-key PTA to get a random number based on hardware RNG.

LUKS CA and TA#

This is the disk encryption CA and TA. Typically, the luks CA communicates with the luks TA to retrieve the passphrase. The luks TA supports disk encryption functionality with one-time passphrase generation during boot time to unlock the encrypted disk.

For more information about the luks CA and TA, refer to Disk Encryption.

CPUBL Payload Decryption CA and TA#

The L4T launcher takes the role of the cpubl-payload-dec CA, and communicates with cpubl-payload-dec TA to decrypt the UEFI payloads (Kernel, Kernel-DTB and Initrd).

Typically, the cpubl-payload-dec CA (L4T launcher) sends a decryption request to the cpubl-payload-dec TA at boot time. After receiving the request, the cpubl-payload-dec TA passes the request to jetson-user-key PTA, which performs the image decryption operation by using a pre-assigned user key stored in EKB. (For more information, refer to sym_t234.key and sym_t264.key in Tool for EKB Generation.)

For more information about the cpubl-payload-dec CA and TA, refer to UEFI Payload Encryption.

Note

The CPUBL payload decryption is currently not supported in the Jetson AGX Thor series.