Secureboot on Jetson AGX Xavier and Jetson TX2 Devices
The NVIDIA® Tegra® Linux Driver Package provides boot security using the Secureboot package. Secureboot prevents execution of unauthorized boot codes through chain of trust. The root-of-trust is on-die bootROM code that authenticates boot codes such as BCT, Bootloader, and warmboot vector using Public Key Cryptography (PKC) keys stored in write-once-read-multiple fuse devices. You can also use Secure Boot Key (SBK) to encrypt Bootloader images.
Fuses and Security
NVIDIA SoCs contain multiple fuses that control different items for security and boot. Programming a fuse, such as changing the value of a fuse bit from 0 to 1, is non-reversible. Once a fuse bit is programmed by setting to 1, you cannot change the fuse value from 1 to 0. For example, a value of 1 (0x01) can be changed to 3 (0x03) or 5 (0x05), but not to 4 (0x4) because the bit 0 is already programmed to 1.
Once odm_production_mode is fused with a value of 0x1, all further fuse write requests are blocked and the fused values are available through the provided API. However, the odm_reserved and odm_lock fields are still writable until odm_lock bit is programmed by changing the value of the bit from 0 to 1.
Although SoC fuses are writable, you must use the odmfuse.sh script to program these fuses: public_key_hash, pkc_disable, secure_boot_key, and odm_production_mode.
Example fuses handled by L4T Secureboot are as follows:
Bit size | Name | Default value set by odmfuse.sh |
1 | odm_production_mode | 0x1 |
256 | public_key_hash | RSA Public Key Hash |
1 | pkc_disable | PKC: 0x1, NS: 0x1 |
128 | secure_boot_key | Secure Boot Key (SBK) AES encryption key for other security applications. If no other security applications are used, leave it untouched. |
32 | device_key | Device key (DK for T210). Device key for other security applications. If no other security applicationa are used, leave it untouched. |
128 | KEK0 | Key Encryption Key 0 |
128 | KEK1 | Key Encryption Key 1 |
256 | KEK256 | KEK256 = KEK0 + KEK1 |
128 | KEK2 | Key Encryption Key 2 KEK0 through KEK2 are twelve consecutive registers (three groups of four each) that can be used to encode a Key Encryption Key and/or Key Seed with different combinations of width. For example, KEK2 is used to encrypt/decrypt Encrypted Key Blob (EKB) when TOS is enabled. |
Fuses that are handled by the user are as follows:
Bit size | Name | Default value set by odmfuse.sh |
1 | jtag_disable | 0x1: disable JTAG |
256 | odm_reserved | Programmable fuses at the users direction. However, 32 MSB are reserved for NVIDIA use. |
4 | odm_lock | Each bit set disables the write for the corresponding 32-bit ODM fuses. For example: 0x2 locks B32-b63 of odm_reserved. |
14 | sec_boot_dev_cfg | Depending on sec_boot_dev_sel, each bit has a different meaning. |
8 | sw_reserved | 2-0: sec_boot_dev_sel. Valid if ON and if the ignore_dev_sel_straps is enabled: 0=eMMC, 1=SPI 3: ignore_dev_sel_straps. Ignores boot strap. 4: enable_charger_detect 5: enable_watchdog 7-6: reserved |
For details on hardware fuses and fuse names, consult the following documents:
• NVIDIA Jetson AGX Xavier Fuse Specification, Application Note DA-09342-001_v1.0
• NVIDIA Jetson TX2 Series Fuse Specification, Application Note DA-08415-001_v1.1
The fuse name aliases recognized by tegraflash are as follows:
Name | tegraflash Alias |
odm_production_mode | SecurityMode |
public_key_hash | PublicKeyHash |
pkc_disable | PkcDisable |
secure_boot_key | SecureBootKey |
device_key | DeviceKey |
Key_encryption_key_0 | KEK0 |
Key_encryption_key_1 | KEK1 |
Key_encryption_key_256 | KEK256 |
Key_encryption_key_2 | KEK2 |
jtag_disable | JtagDisable |
odm_reserved0, odm_reserved1,… odm_reserved7 | ReservedOdm0, ReservedOdm1,… ReservedOdm7 |
odm_reserved8,… odm_reserved11 | ReservedOdm8,… ReservedOdm11 (AGX Xavier only) |
odm_lock | OdmLock |
sec_boot_dev_cfg | SecBootDeviceSelect |
sw_reserved | SwReserved |
Overall Fusing and Signing Binaries
The Secureboot process with PKC (and SBK) requires:
• Install the L4T secureboot package.
• If necessary, prepare the DK(KEK), SBK, and ODM fuse values.
• Generate the RSA key-pair.
• Burn DK(KEK), ODM fuses, the PKC/SBK, Security Info, and odm_production mode fuses.
• Sign the boot image files with PKC (and SBK).
• Flash the signed boot image files.
Note: | This process blocks ODM production fuse burning and protects the SoC device from erroneous ODM production fuse burning. ODM_RESERVED and ODM_LOCK fuses are still writable until the ODM_LOCK bit is burned. |
Installing the L4T Secureboot Package
Prerequisites
• X86 host running Ubuntu 14.04 LTS
• libftdi-dev for USB debug port support
• openssh-server package for OpenSSL
• Full installation of the latest L4T release on the host
Download the latest L4T release at:
https://developer.nvidia.com/embedded/linux-tegra-archive
• The Jetson platform is connected to the host with Type-B micro USB cable
• Debug serial port is connected to the host, if necessary
To install secureboot
1. Download the secureboot_<release_version>.tbz2 tarball from:
https://developer.nvidia.com/embedded/downloads
Where <release_version> is identified in the Release Notes.
2. Untar the file by executing the command:
tar xvjf secureboot_<release_version>.tbz2
The tarball includes:
• secureboot.tbz2
• README.secureboot.txt that is also provided as a PDF on the L4T downloads site.
3. Untar the secureboot.tbz2 by overlaying on the L4T Board Support Package (BSP).
Extract the file secureboot.tbz2 onto the directory that is one level up from the Linux_for_Tegra/ directory on your Linux host.
• The Linux_for_Tegra/ directory must be present from installing the L4T Board Support Package as a prerequisite.
• You must be in the same directory where the Linux_for_Tegra/ directory is located before executing the command:
tar xvjf secureboot.tbz2
Generating the RSA Key Pair
If you wish to lock the fuse without PKC encryption, skip this topic. L4T secureboot requires 2048-bit RSA key-pair.
To generate a key-pair
1. Execute the command:
openssl genrsa -out rsa_priv.pem 2048
Upon successful execution, OpenSSL generates the key file named rsa_priv.pem file.
2. Rename and save the key file securely and safely.
The key file is used to burn fuse and sign boot files for Jetson devices. The security of your device depends on how securely you keep the key file.
To ensure the security of the key file, restrict access permission to a minimum number of personnel.
Note: | To generate a truly random number key, use the Hardware Security Module (HSM). Consult the Hardware Security Module User Guide for output format and private key conversion to PEM format. |
Preparing the SBK key
If you want to encrypt Bootloader (and TOS), you must prepare the SBK fuse bits.
Note: | You must use the SBK key along with the PKC key. |
The SBK key consists of four 32-bit words stored in a file in big-endian hexadecimal format. Here is an example of an SBK key file:
0x12345678 0x9abcdef0 0xfedcba98 0x76543210
The representation in the fusing XML file is:
0x123456789abcdef0fedcba9876543210
Preparing the DK(KEK)/ODM Fuses
If you want to use another security application, you must prepare the DK(KEK) and other ODM fuse bits as described in the user guide for the other security application.
Name | Description |
DK Applies to: NVIDIA® Jetson Nano™ devices | A 32-bit number stored in a file in big-endian HEX format. For example: 0xddccbbaa |
KEK 0 KEK 1 KEK 2 | A 128-bit number stored in a file in big-endian HEX format. |
KEK256 | A 256-bit number stored in a file in big-endian HEX format. |
ODM Fuse Bits | To use applications other than Secureboot, additional ODM fuse bits may be required. The specific fuse information differs depending on the application being used. Consult the user guide for the application being used. |
Note: | HEX numbers must be presented in BigEndian format. The leading 0x or 0X can be omitted. The L4T SecureBoot software converts the BigEndian HEX format to the format that the Jetson device expects. All standard OpenSSL utilities output in BigEndian format. |
Burning PKC [DK(KEK), SBK] Fuses
The steps for burning PKC, DK, and SBK fuses using a private key file PEM format are as follows.
To burn PKC fuses
1. Navigate to the directory where you installed L4T.
2. Put the Jetson device into Forced Recovery Mode.
3. Burn the fuse using the odmfuse.sh script. For example:
• To fuse PKC HASH from the .pem file with JTAG enabled:
$ sudo ./odmfuse.sh -j -i <chip_id> -c PKC -p -k <key.pem> [-D <DK_file> | --KEK{0-2} <KEK file>] [-S <SBK_file>]
• To fuse PKC HASH from the .pem file with JTAG disabled:
$ sudo ./odmfuse.sh -i <chip_id> -c PKC -p -k <key.pem> [-D <DK_file> | --KEK{0-2} <KEK file>] [-S <SBK_file>]
• To protect ODM production fuse with JTAG enabled:
$ sudo ./odmfuse.sh -j -i <chip_id> -c NS -p
• To protect ODM production fuse with JTAG disabled:
$ sudo ./odmfuse.sh -i <chip_id> -c NS -p
Where <chip_id> is:
• Jetson AGX Xavier: 019
• Jetson TX2: 0x18
odmfuse.sh Extra Options
For odmfuse.sh, other than PKC key and ODM_PRODUCTION_MODE fuses, odmfuse.sh allows you to program ODM fuses that are completely under your discretion. Skip this topic if you do not plan to modify these fuses.
The odmfuse.sh options that blow some ODM fuses are as follows:
Option | Description |
-d 0xXXXX | Sets sec_boot_dev_cfg=<value>&0x3fff. For detail, refer to TRM. |
-j | Sets JTAG enabled. Unless this option is specified, the usage of the JTAG debugger is blocked by default. |
-l 0xX | Sets odm_lock=0xX. Setting each bit locks corresponding 32-bits in odm_reserved. For example, setting odmlock=0x1 locks the first 32-bit of the odm_reserved read only. Setting odmlock=0x5 locks the first and third 32-bits of the odm_reserved field read only and so on. |
-o <value> | Sets odm_reserved=<value>. The value must be quoted series of 8 32-bit HEX numbers such as: "0xXXXXXXXX 0xXXXXXXXX 0xXXXXXXXX 0xXXXXXXXX 0xXXXXXXXX 0xXXXXXXXX 0xXXXXXXXX 0x00000000" The last 32-bit HEX number must be 0x00000000 because these fuses are reserved for NVIDIA use. |
-p | Sets production mode. |
-r 0xXX | Sets sw_reserved=0xXX. The name of this fuse field is confusing, but the meaning is as follows: bit[7-6] reserved bit[5 ] enable_watchdog bit[4 ] enable_charger_detect bit[3 ] ignore_dev_sel_straps: Ignore "boot strap" bit[2-0] sec_boot_dev_sel: 0:eMMC 2:SPI |
-S <SBK_file> | Sets the Secure Boot Key used to encrypt Bootloader and TOS. The content of <SBK_file> must be four 32‑bit big-endian numbers in hexadecimal format. |
--no-burn | Prepares the fuse blob to be used repeatedly on the factory floor where the private PKC key is not available. This option generates <L4T path>.../Linux_for_Tegra/fuseblob.tbz2 which is downloaded and untarred in <L4T path>.../Linux_for_Tegra directory of a factory host. Once the fuseblob.tbz2 is untarred in the Linux_for_Tegra directory, then fusecmd.sh in the Linux_for_Tegra/booloader directory is used to burn fuses repeatedly instead of the standard odmfuse.sh. |
--KEK0 --KEK1 --KEK2 <path> | Pathname of the Key Encryption Key file that other security applications are to use to encrypt/decrypt keys. The content of the file must be a single 128-bit big-endian number in hexadecimal format. |
--KEK256 <path> | Pathname of the 256-bit Key Encryption Key file that the high level security application will use to encrypt the application keys. The content of the file must be a single 256-bit big-endian number in hexadecimal format. |
Signing and Flashing Boot Files
You can use the following procedures to sign and flash boot files:
• In one step, using the PKC-key only or no-key signing
• In one step, using both SBK and PKC key signing
• In separate steps
To sign and flash in one step using PKC-key or no-key signing
1. Navigate to the directory where you installed L4T.
2. Place the Jetson device into Force Recovery mode.
3. Enter one of these commands:
• To flash the Jetson device with PKC signed binaries:
$ sudo ./flash.sh -u <keyfile> <device name> mmcblk0p1
• To flash the Jetson device with unsigned binaries:
$ sudo ./flash.sh <device name> mmcblk0p1
Where:
• <keyfile> is an RSA 2k key file.
• <device name> is:
• For Jetson AGX Xavier: jetson-xavier
• For Jetson TX2: jetson-tx2
To sign and flash in one step using both SBK and PKC keys
1. Navigate to the directory where you installed L4T.
2. Place the Jetson device into Force Recovery mode.
3. Enter one of these commands:
• For Jetson AGX Xavier:
$ sudo BOARDID=2888 FAB=400 BOARDSKU=0001 BOARDREV=H.0 ./flash.sh -u <pkc_keyfile> -v <sbk_keyfile> jetson-xavier mmcblk0p1
• For Jetson TX2:
$ sudo BOARDID=3310 FAB=C04 ./flash.sh -u <pkc_keyfile> -v <sbk_keyfile> jetson-tx2 mmcblk0p1
Where:
• <pkc_keyfile> is an RSA 2k key file
• <sbk_keyfile> is an SBK key file
Note: | Neither the RSA key file nor the SBK key file may be placed under the Bootloader directory. |
To sign and flash in separate steps
1. Sign the boot files.
• Using PKC-key or no-key signing:
1. Navigate to the directory where you installed L4T.
2. Place the Jetson device into Force Recovery mode.
3. Enter one of the commands:
For PKC-key signing:
$ sudo ./flash.sh --no-flash -u <keyfile> <device name> mmcblk0p1
For no-key signing:
$ sudo ./flash.sh --no-flash <device name> mmcblk0p1
Where:
• <keyfile> is an RSA 2k key file
• <device name> is:
Jetson-Xavier: jetson-xavier
Jetson-TX2: jetson-tx2
• Using both SBK and PKC-key signing:
1. Navigate to the directory where you installed L4T.
2. Place the Jetson device into Force Recovery mode.
3. Enter one of the commands below:
For Xavier:
$ sudo BOARDID=2888 FAB=400 BOARDSKU=0001 BOARDREV=H.0 --no-flash ./flash.sh -u <pkc_keyfile> -v <sbk_keyfile> jetson-xavier mmcblk0p1
For TX2:
$ sudo BOARDID=3310 FAB=C04 --no-flash ./flash.sh -u <pkc_keyfile> -v <sbk_keyfile> jetson-tx2 mmcblk0p1
Where:
• <pkc_keyfile> is an RSA 2k key file
• <sbk_keyfile> is an SBK key file
Note: | Neither the RSA key file nor the SBK key file may be placed under the Bootloader directory. |
2. Flash:
1. Navigate to the directory where you installed L4T.
2. Place the Jetson device into Force Recovery mode.
3. Enter the commands:
$ cd bootloader
$ sudo bash ./flashcmd.txt
Note: | Be sure to press and reset the recovery button even if the Jetson device is still in recovery mode after fusing. |
Accessing the Fuse from the Target
The L4T secureboot package provides a means to access fuses from the target board after it boots up.
To access the fuse from the target board
1. Copy the <top>.../Linux_for_Tegra/pkc/tegrafuse.sh script to the ubuntu@<target IP address>.
2. To access the target’s fuses from the target board, login to the target board.
• To display all fuses:
sudo ./tegrafuse.sh
• To set or amend a specific fuse:
sudo ./tegrafuse.sh <fuse name> <fuse value>
Example: Burning the Fuse in a Factory Environment
This topic provides an example reference implementation for burning fuses in a factory environment.
Building the Fuse in a Trusted Environment
Building a fuse blob in a factory environment requires:
To generate the fuse blob fuseblob.tbz2
• For Jetson TX2:
4. Navigate to the directory where you installed L4T.
5. Execute the command.
sudo ./odmfuse.sh --noburn -i 0x18 -c PKC -p -k <key.pem> [--KEK0 <KEK0 file> --KEK1 <KEK1 file> --KEK2 <KEK2 file> --KEK256 <KEK256 file> -S <SBK file>] jetson-tx2
This standard Jetson TX2 fuse command requires an actual target device connected to the host and placed in force recovery mode.
To generate the fuse blob without actual Jetson target device attached to the host
• Add FAB=C04 in front of ./odmfuse.sh as follows:
sudo FAB=C04 ./odmfuse.sh --noburn -i 0x18 -c PKC -p -k <key.pem> [--KEK0 <KEK0 file> --KEK1 <KEK1 file> --KEK2 <KEK2 file> --KEK256 <KEK256 file> -S <SBK file>] jetson-tx2
Burning the Fuse Blob in a Factory Environment
Burning the fuse blob in a factory environment requires:
• Set up an X86 Linux host system as the factory fuse host.
The factory fuse host does not require the L4T BSP installation.
• Download the fuseblob.tbz2 to the factory fuse host with the command:
sudo tar xvjf <download path>.../fuseblob.tbz2
• Navigate to the Bootloader directory.
• Use the following procedure to burn the fuse.
To burn the fuse
1. Put the Tegra device into force recovery mode.
2. Execute the command:
sudo ./fusecmd.sh
Note: | This procedure can be used and repeated on multiple Tegra boards. All the boards are burned with the same fuseblob and have exactly the same fuse configurations. |
