Trusty in NVIDIA® Jetson™ Linux Driver Package (L4T) enables booting a Trusted OS on NVIDIA® Jetson AGX Xavier™ NVIDIA® Jetson™ TX2 devices. The following sections explain how to set up and use Trusty.

This topic uses some terms that are specific to Trusty:

Trusty resides in a separate storage partition and boots as part of a chain of trust or a secure boot sequence. It creates two environments in a device with different security modes:

The normal world OS and Trusty software operate in a client-server relationship, with Trusty as the server.

The bootloader allocates a dedicated carveout, TZ-DRAM, to run a secure OS. All secure operations are initiated by a client application running in the non-secure environment. A trusted application, in the secure world, never initiates contact with the non-secure environment.

This diagram shows the relationships among the components:

This section gives instructions for developing Trusted Applications (TAs) that run with Trusty's Trusted Execution Environment (TEE).

L4T enables three TAs by default:

The first two TAs constitute a functional testing framework developed as part of the Android Open Source Project (AOSP).

The third TA was developed by NVIDIA to serve as a reference for implementing hardware-backed encrypted keyblobs on Jetson devices. Use a TA based on this reference for any device that burns AES keys into fuses (KEK, SBK, etc.) if the device is to be provisioned with an encrypted blob containing keys or other encrypted content.

Two additional TAs from AOSP are packaged with Trusty, but are disabled by default. These TAs are located in the <TRUSTY_TOP>/trusty/app/sample directory, where <TRUSTY_TOP> is the root directory of the Trusty source package.

Each Trusted Application must have a corresponding manifest that specifies the TA’s configuration properties. The manifest data structure is:

The manifest is defined at:

Where <TRUSTY_TOP> is the root directory that holds all Trusty code.

Use the manifest to specify configurations such as: stack size, heap size, and map the MMIO address. A UUID generator (https://www.uuidgenerator.net/) creates the UUID.

This is an example of a TA manifest:

To access hardware registers, a Trusted Application must map the registers to MMIO regions in the address space.

The Trusty system functions prepare_dma() and finish_dma() perform direct memory access (DMA) operations. The flags argument determines the direction of the DMA and cache operations.

Values for flags are defined at:

Where <TRUSTY_TOP> is the root directory that holds all Trusty code.The functions are declared in trusty_syscalls.h:

To implement a new trusted application, perform these steps:

The Trusty API Reference may be found at:

This section explains how to utilize the encrypted keyblob mechanism to provision keys or other secret content on Jetson devices that support Trusty.

This section introduces some additional terms:

A common use case for a Trusted OS is managing secret keys. Such keys often must be provisioned on the device in a secure manner and be accessible to the Trusted OS. To assist in these use cases, Jetson devices that support Trusty support an encrypted keyblob feature which you may use to provision secret keys on Jetson devices and utilize them within the trusted OS.

Trusty uses the following encrypted keyblobs:

The encrypted keyblob (EKB) format is designed to be as generic as possible, giving you full control of the actual keyblob content structure. An EKB binary (an .img file) has a 16-byte EKB header that is prefixed to an EKB blob’s contents:

EKB header information is consumed by the MB2 bootloader. It must match the following layout:

The EKB Size field, EKB_size, is the length of the EKB binary starting from the Magic field. The value of EKB_size must be 4 less than the total size of the EKB binary in bytes. EKB_size is 4 bytes long, in little endian format.

The EKB Magic field, Magic, is eight bytes long, and must contain the exact string "NVEKBP\0\0".

The EKB Reserved field contains four unused bytes. NVIDIA recommends that these bytes be set to binary zero.

The EKB content information is completely implementation-defined. There are no restrictions on the data in the EKB content, although it is intended to hold encrypted keys or other content.

Any data in the EKB content section is accessible to a Trusty TA during device boot.

For security reasons, the EKB binary size must be 1024 bytes or more. It may not exceed the EKS partition size. If the EKB binary size does not fall in this range, flashing will fail.

If you have very little EKB content, pad the EKB binary to a length of at least 1024 bytes. The recommended way to pad the binary is to append random values to the EKB data before encryption. The TA in Trusty decrypts the entire binary, then discards the padding.

NVIDIA recommends that the EKB content be encrypted with a 128-bit symmetric key that is derived from a hardware-backed EKB_RK key burned into the device's KEK2 fuse.

This is the correct way to generate an EKB binary and provision a Jetson device:

This flow diagram illustrates the EKB generation process:

During boot, a TA inside Trusty performs the following steps:

The following diagram shows the process of EKB decryption.

After Trusty derives EKB_EK from EKB_RK in the KEK2 keyslot, there is no longer a need for EKB_RK to persist in the keyslot. NVIDIA strongly recommends that the key be wiped from the keyslot to prevent any component from utilizing it after the device boots.

The keystore-demo TA demonstrates the keyslot clearing procedure. NVIDIA recommends that you use the se_clear_aes_keyslots() function provided in the keystore-demo TA. This function clears several keyslots as a security precaution.

TAs inside Trusty must use SE only during boot. Using SE from Trusty after boot may cause a system crash because there is no guarantee that the SE clocks are enabled. This means that EKB_EK must be derived and the SE keyslot must be cleared during boot. After booting you must utilize EKB_EK through a software crypto library.

You may want to sign the EKB binary during the generation process and have the Trusty TA verify the EKB binary signature. NVIDIA recommends an encrypt-then-sign approach for keyblobs that contain keys or other high-entropy content. You can implement an encrypt-then-sign approach like this:

 

NVIDIA strongly recommends that the TOS image be encrypted when utilizing the encrypted keyblob to store keys or other sensitive content.