Applies to the Jetson AGX Xavier series, the Jetson Xavier NX series, and the Jetson AGX Orin.
Disk encryption encrypts a whole disk or partition to protect the datait contains. NVIDIA ® Jetson™ Linux offers disk encryption that is based on Linux Unified Key Setup (LUKS) Data-at-rest encryption ,the standard for Linux disk encryption. It provides a standard diskformat that stores all necessary setup information on the disk itself,in the partition header. The passphrase in the Jetson OP-TEE luks-srv Trusted Application (TA) supports disk encryption functionality with one-timepassphrase generation during boot time to unlock the encrypted disk.
Setup Preparation ¶Jetson Linux uses cryptsetup , a LUKS user space command line utility, toset up and unlock an encrypted disk. It uses the DMCrypt kernel moduleas its backend. The utility sets up the encrypted disk as a LUKSpartition and configures it with a passphrase.
The DMCrypt kernel module is the standard device-mapper interface forencryption functionality in the Linux kernel. It sits between the diskdriver and the file system, where it encrypts and decrypts data blockstransparently.
For more information about cryptsetup and DMCrypt , see the cryptsetup project and the DMCrypt documentation ,both hosted by GitLab.
Details of Operation ¶Two types of keys are used for disk encryption:
The master key , also known as the Disk Encryption Key (DEK).This key is used for data encryption or decryption when data istransferred between the file system and the disk.
The master key is generated by cryptsetup . The default and recommended source for data used to generate the key is /dev/random . The key resides in the LUKS header, and is encrypted by the key derived from the passphrase.
The passphrase or password is an input string or patternsupplied by the user to set up disk encryption and lock the disk. Thesame input is used to decrypt and unlock data stored on the disk.
The passphrase is generated with help from two applications:
luks-srv : A trusted application (TA) that utilizes the key generatingservice from jetson_user_key_pta . Using that service it can derivea LUKS key, which is the root key for deriving the passphrase.
This block shows the service interfaces provided by luks-srv :
/* * Each trusted app UUID should have a unique UUID that is * generated from a UUID generator such as * http://www.uuidgenerator.net/ * * UUID : {b83d14a8-7128-49df-9624-35f14f65ca6c} */ #define LUKS_SRV_TA_UUID { 0xb83d14a8, 0x7128, 0x49df, { 0x96, 0x24, 0x35, 0xf1, 0x4f, 0x65, 0xca, 0x6c } }#define LUKS_SRV_CONTEXT_STR_LEN 40#define LUKS_SRV_PASSPHRASE_LEN 16/* * LUKS_SRV_TA_CMD_GET_UNIQUE_PASS - Get unique passphrase * param[0] in (memref) context string, length * param[1] out (memref) passphrase, size * param[2] unused * param[3] unused */#define LUKS_SRV_TA_CMD_GET_UNIQUE_PASS 0/* * LUKS_SRV_TA_CMD_SRV_DOWN - Turn off the service * param[0] unused * param[1] unused * param[2] unused * param[3] unused */#define LUKS_SRV_TA_CMD_SRV_DOWN 1nvluks-srv-app : A Client Application (CA) in the normal (non-secure) world thatcommunicates with luks-srv to retrieve the passphrase. cryptsetup uses the passphrase to unlock the encrypted disk.
The cryptographic algorithm used for disk encryption is AES-XTS, witha key length of 256 bits. This mode of operation makes theencrypted data look completely random, minimizing the potential forattack. The entire key derivation process is performed in the secureworld.
The following diagram outlines the overall process:
The nvluks-srv-app CA queries the per-device unique passphrasevia the command interface LUKS_SRV_TA_CMD_GET_UNIQUE_PASS .
When the luks-srv TA receives the command, it sends a request to jetson_user_key_pta to generate a per-device unique LUKS key. jetson_user_key_pta uses the NIST-SP 800-108 KDF to derivea new key from the EKB disk encryption key.
The KDF’s input parameters are the fixed label string "luks-srv-ecid" and the ECID as the context string.
The TA uses the LUKS key to generate a passphrase. The passphraseis generated with the same KDF as the LUKS key.
The KDF’s context string parameter is the disk UUID, so no user interaction is needed to create the encrypted disk image or to unlock it at boot time. The fixed label string is "luks-srv-passphrase-unique" .
The TA returns the output passphrase.
Send the LUKS_SRV_TA_CMD_SRV_DOWN command to shut the service down.This ensures that passphrase generation is done only once.
The generation process uses this key derivation function (KDF) togenerate a per-device unique LUKS key or a generic key:
key = NIST-SP-800-108( inkey , labelstring , contextstring )
Where:
NIST-SP-800-108 is a key derivation function (KDF) recommended by the NationalInstitute of Standards and Technology algorithm for key derivationusing pseudorandom functions..
in-key is the key source used to derive a new key.
label-string identifies the purpose of the key to be generated. Inthe reference implementation label-string is a fixed value definedby the TA.
context-string is a string that contains information related to thederived key, and which the KDF uses as a parameter for keygeneration. In the reference implementation the default contextstring is the disk’s UUID, but you can change this by modifying the TA.
To unlock the encrypted disk with nvluks-srv-app , enter these commands:
#!/bin/bash# Using "cryptsetup" and "nvluks-srv-app" to unlock the encrypted device:nvluks-srv-app --context-string "${DISK_UUID}" --get-unique-pass | cryptsetup -c luksOpenWhere:
is the device name of the encrypted disk, e.g. /dev/mmcblk1 .
is the mapping name after the encrypted disk is unlocked,e.g. /dev/mapper/DM_name .
See Basic Flashing Script Usage in the topic Flashing Support for more information.
Note
To prevent any form of attack from extracting the passphrase at boot time (e.g. in the initrd), use the command type LUKS_SRV_TA_CMD_SRV_DOWN . This command instructs luks-srv not to respond to a LUKS_GET command (to get the passphrase) until reboot. This step is crucial to ensure the security of your design.
The Threat Model ¶The purpose of disk encryption is to prevent an attack from stealing ortampering with data on the disk. Even if the disk is physicallyunmounted (or, in the case of an internal device such as an eMMC, isremoved from the device), the data cannot be exposed.
Disk encryption cannot protect against the following types of threat:
A background process or daemon that has a security hole. An attackermay be able to use the hole to gain control of the process and access the disk.
Theft or leakage of the login ID and password. An attacker can usethese credentials to log in to the device and access the disk.
Disk Encryption Implementation in Jetson Linux ¶Jetson Linux provides a reference implementation of disk encryptionwhich fulfills the security requirements of many use cases. If your usecase’s requirements are different, you can modify it or use it as amodel for implementing your own.
Layout of an Encrypted Disk ¶Because Bootloader cannot read encrypted files, disk encryptionrequires Jetson Linux to divide a “naive” system’s APP partition in two:
The unencrypted APP partition contains the /boot branch of thefile system, including the kernel, DTB, and initrd images.
A new, encrypted APP_ENC partition contains the rest of the file system.
Following is an example of the APP partition definition for a system onwhich disk encryption is not enabled. You can find a definition likethis one in the Jetson Linux BSP partition configuration files, e.g. Linux_for_Tegra/bootloader/t186ref/cfg/flash_t194_sdmmc.xml for an NVIDIA ® Jetson AGX Xavier™ series device booting from SDMMC memory:
sequential basic APPSIZE 0 0x8 4096 0 APPFILE APPUUID **Required.** Contains the rootfs. This partition must be defined after ``primary_GPT`` so that it can be accessed as the fixed known special device ``/dev/mmcblk0p1``.The following example shows how disk encryption separates APP into two partitions. (Each partition’s differences from the preceding example are highlighted in red type. The elements in the two definitions are the same.) You can find the file in the Jetson Linux BSP, e.g. Linux_for_Tegra/bootloader/t186ref/cfg/flash_t194_sdmmc_enc_rfs.xml for the same device as above:
sequential basic 104857600 0 0x8 4096 0 system_boot.img APPUUID **Required.** Contains the boot partition. This partition must be defined after ``primary_GPT`` so that it can be accessed as the fixed known special device ``/dev/mmcblk0p1``. APP_ENC" type="data" encrypted="true"> sequential basic APP_ENC_SIZE 0 0x8 4096 0 system_root_encrypted.img APP_ENC_UUID **Required.** Contains the encrypted root partition.Notice that the element of APP specifies an actual number, butthe element of APP_ENC specifies a symbol, APP_ENC_SIZE . Later,the value of APP_ENC_SIZE must be calculated by subtracting the size of APP from the total rootfs size.
Each partition’s element specifies the actual file name ofthe appropriate disk image (not a symbol that is resolved to the filename during flashing).
The partitions’ elements specify the partitions’ UUIDs, APPUUID and APP_ENC_UUID respectively. Both symbols are translated toreal UUID numbers by the image generation process.
The APP_ENC partition’s encrypted attribute indicates that the partitionis encrypted.
With the new partition layout, new parameters are needed in the boardconfiguration file to enable disk encryption and apply the new partitionlayout file. Use the appropriate board configuration file for yourdevice, e,g, Linux_for_Tegra/p2972-0000.conf.common for a Jetson AGXXavier module in a Jetson AGX Xavier Developer Kit. The disk_enc_enable setting indicates that disk encryption is enabled, and EMMC_CFG identifies the partition layout file to use:
disk_enc_enable=1;EMMC_CFG=flash_l4t_t194_sdmmc_enc_rfs.xml;The flash tool uses the board configuration file to generate file systemimages and flash them onto the device.
How to Create File System Images ¶When you create file system images to support booting with an encrypteddisk, keep the following points in mind:
The bootarg kernel command line’s root parameter must use the disk’sUUID (not the partition’s UUID specified in the partition definition)to identify the root disk if the device is to boot from an encryptedroot disk.
The crypttab file in initrd includes the mount point and the devicename of the encrypted disk. It may be a real device name like /dev/mmcblk0p1 or the UUID of the disk.
The fstab file in the rootfs is updated with the /boot directory inthe APP partition. This helps the automount process to mount thepartition at boot time.
How to Create an Encrypted Rootfs on the Host ¶The rootfs is generated on the host by flash.sh . The diagram below showsthe elements of the rootfs (in green), the utilities used to generate it(in gray), and the input (in blue).
The input has two parts: the plain key file of the EKB key used for diskencryption, and an input string used to generate the passphrase. Bydefault, the input string is the UUID of the encrypted disk. You canmodify the script that generates the rootfs to let user to enter theirown string. You must change the initrd accordingly to make it use theuser-supplied string.
You must generate the rootfs on a secure system, that is, a secure hostcomputer equipped with a Hardware Security Module (HSM). The HSM isused for key generation and management to secure key assets and safetransport to the factory floor. This is necessary to ensure that thekeys cannot be leaked to an unsecure system on the production line. flash.sh invokes two helper scripts to generate the passphrase and thedisk images:
gen_luks_passphrase.py follows the same process as the hwkey-agent and luks-srv TAs to derive the LUKS key, and uses the key to generatethe passphrase.
disk_encryption.sh outputs the disk images for the initrd, system_boot.img , and system_root_encrypted.img .
The Jetson Linux reference implementation only generates per-deviceencrypted disk images. Use it as a starting point to develop a scriptthat is suited to your use case and production environment.
To flash the encrypted rootfs on the host with flash.sh for the Jetson AGX Xavier series and the Jetson Xavier NX series:
# The disk encryption key in the EKB partition:$ echo "00000000000000000000000000000000" > ekb.key$ sudo ROOTFS_ENC=1 ./flash.sh -i "./ekb.key"Flashing the encrypted rootfs on the host with flash.sh for the Jetson AGX Orin requires an update of the Linux_for_Tegra/bootloader/eks.img .
Decompress the OP-TEE source package and run example.sh in it to generate a test EKS image(In real production scenario, you must generate your own EKS image using your own keys):
$ cd optee/samples/hwkey-agent/host/tool/gen_ekb/# Take a look at example.sh and you can see the test keys$ ./example.shCopy the eks_t234.img generated by example.sh to the Linux_for_Tegra/bootloader folder and overwrite the eks.img file.
The Tool for EKB Generation chapter in OP-TEE has detailed descriptions about EKS image generation.
NVIDIA strongly recommends you to generate your own keys and EKS image, the keys defined in example.sh and the EKS image it generates are only for test purpose.
Use flash.sh to generate and flash the encrypted rootfs:
# The disk encryption key in the EKB partition:# This key is defined in example.sh too to generate the EKS image$ echo "f0e0d0c0b0a001020304050607080900" > ekb.key$ sudo ROOTFS_ENC=1 ./flash.sh -i "./ekb.key"Where:
is the value of $(BOARD) for your Jetson moduleand configuration, as shown in the table in the section Jetson Modules and Configurations in the topic Quick Start .
is the partition where the root file system is to be flashed.
The flash.sh command line option -i specifies the key to be used fordisk encryption. The reference implementation described above uses theEKB key. NVIDIA recommends that you customize the script to use adifferent key source for the sake of security. The keys in the example aboveare only for reference and testing purposes so that you should not use them asgiven. When you change the key, change the EKS partition accordingly,and review the overall key and passphrase generation flow to be surethat everything works correctly.
How to Flash an Encrypted Rootfs to an External Storage Device ¶To flash an encrypted rootfs generated by flash.sh to an externalstorage device, use l4t_initrd_flash.sh (also known as “the initrdflashing tool”). (See the section Flashing with initrd in the topic Flashing Support ).
Following is an example of commands that use l4t_initrd_flash.sh toflash an encrypted rootfs to an NVMe SSD attached to a Jetson AGX Xavierseries device:
$ cd Linux_for_Tegra$ sudo ROOTFS_ENC=1 ./tools/kernel_flash/l4t_initrd_flash.sh --external-device nvme0n1p1 -c ./tools/kernel_flash/flash_l4t_nvme_rootfs_enc.xml --external-only -S 8GiB jetson-xavier externalTools and instructions for flashing an encrypted rootfs with initrd maybe found in the directory /Linux_for_Tegra/tools/kernel_flash/ . For moredetailed information, see README_initrd_flash.txt in that directory.
To Enhance initrd to Unlock an Encrypted Rootfs ¶To boot from an encrypted root file system, you need an initrd imagewhich includes the necessary utilities (e.g. cryptsetup ) and scripts toset up the root device after the kernel is initialized, but before therest of the operating system is booted. The image must contain the APP partition, which contains the /boot branch of the rootfs (unencrypted),and the APP_ENC partition, which contains the rest of the rootfs(encrypted).
The boot flow diagram below shows that by default the Bootloader (UEFI)uses the APP partition as the boot partition.
The init script in the initrd follows these steps to check the encryptedroot device, unlock it, and mount it:
Verify that the root parameter specifies the same device as the rootdevice setting in /etc/crypttab .
Verify that the root device is a LUKS device.
Unlock the encrypted root device with the per-device unique passphrase.
Mount the root device.
Command the luks-srv TA not to respond to further passphrase requests until reboot.
To modify initrd to unlock additional encrypted file systems ¶The file /etc/crypttab , kept in initrd, describes encrypted blockdevices that are set up during system boot. Each line of this file hasthe form:
UUID=Where:
is the name of a volume in which decrypted data is tobe placed. Its block device is set up in /dev/mapper/ . must be unique across all lines in the file.
is the UUID of the underlying block device containingencrypted data.
Here are two examples of entries in /etc/crypttab :
crypt_root UUID=b5600ed6-69e7-42b8-bee3-ecfdd12649d1crypt_UDA UUID=cf6fa01d-1127-4612-9992-2f6db77385e0If your device has several encrypted file systems, you must add a lineto /etc/crypttab for each one you want Bootloader to unlock.
This is an example of how to unlock an encrypted file system:
Enter this command to find the UUID of the encrypted file system:
$ sudo blkid | grep TYPE="crypto_LUKS"This command line displays a line of output for each encrypted disk that includes the disk’s UUID. Such a line looks like this:
/dev/mmcblk0p43: UUID="5096aa4d-6590-429b-9295-a1fe041b8fa3"TYPE="crypto_LUKS" PARTLABEL="UDA"PARTUUID="2b23da7f-2f18-44bf-9e1d-6e3a3a39ad21"Unpack the initrd. For instructions, see the section Modifying Jetson RAM Disk in the topic Flashing Support .
Add a line to /etc/crypttab for each encrypted file system that youwant to unlock at subsequent reboots. The line specifies the UUID ofthe file system to be unlocked, as in this example:
crypt_fs UUID="5096aa4d-6590-429b-9295-a1fe041b8fa3"Repackage the initrd and store it in /boot , replacing the initrd that was originally there.
Create a subdirectory in /mnt in which initrd can mount each unlockedfile system during the initialization process. For the sake ofsimplicity, NVIDIA recommends giving each subdirectory the same nameas the volume to be mounted there. For the volume specified instep 3, the subdirectory would be named crypt_fs :
$ mkdir -p /mnt/crypt_fsBootloader unlocks your encrypted file system at each subsequent reboot.
Summary ¶The following diagram shows the overall flow of the encrypted diskunlocking process.
The steps of the process are:
nvluks-srv-app queries the hardware-based passphrase from the Trusty luks-srv TA and pass it to the cryptsetup utility.
cryptsetup unlocks the disk and decrypts the disk encryption key(DEK) with the passphrase.
cryptsetup invokes the DMCrypt kernel module and loads the key intothe kernel. DMCrypt uses the tegra-crypto driver, which usesSecurity Engine (SE) hardware for data encryption and decryption.
Subsequent disk I/O is routed through DMCrypt , which decrypts andencrypts data as it reads and writes.
Manufacturing process ¶The following diagram illustrates the post-development manufacturingprocess for a Jetson-based device.
All disk images and blobs to be flashed onto production devices must begenerated on a secure system. The HSM holds all of the security keysneeded in the manufacturing process. If more than one production deviceis to be flashed at a time, the security machine must be able to deployimages to other systems (flashing machines) for flashing devices.
If the device is designed to use per-device encrypted disk images, theimages must be generated one at a time on the security machine.
