Skip to main content
Version: Torizon OS 7.x.y

Integrate Secure Boot on Torizon OS

Introduction​

This article is a guide on how to enable and use Secure Boot on Torizon OS.

Prerequisites​

Build Secure Boot Image​

Currently, generating Torizon OS images with Secure Boot enabled requires performing a Yocto Project/OpenEmbedded build. Before doing so, one has to select the appropriate BitBake class based on the desired coverage level:

Class nameCoverageProvider
tdx-signedBCoTLayer meta-toradex-security
torizon-signedECoTLayer meta-toradex-torizon

The class tdx-signed is included by torizon-signed so that when the latter is employed one gets all the protections provided by the former plus the root filesystem protection. Apart from that, the extra functionality offered by torizon-signed is mostly independent of those offered by tdx-signed and so is the configuration to be performed.

Once the class is selected one has to set up their Yocto project as described in the following sections.

Setup Yocto Project​

Set up your host PC for building Torizon OS from source as explained in the article Build Torizon OS from Source With Yocto Project/OpenEmbedded.

Then add a line like this to your conf/local.conf file (with the appropriate class):

conf/local.conf
INHERIT += "tdx-signed"

Setup for NXP i.MX SoMs​

Configure HAB/AHAB support as described on meta-toradex-security: README-secure-boot-imx / Configuring HAB/AHAB support.

The above instructions point to the NXP Code-Signing Tool User’s Guide, also known as CSP UG. This document, as well as other tutorials on the web, don't provide information on what difference setting the CA flag has on the overall system security, as well as their pros and cons.

For SoMs with HABv4, the NXP AN4581 i.MX Secure Boot on HABv4 Supported Devices states that the CA flag being set is a recommended default:

Unless boot time is critical, it is recommended that the SRK have the CA flag, and the CSF and IMG keys used to validate their respective data. The fast authentication feature supplies the user with a faster boot time, at the cost of a less robust signature.

For SoMs with AHAB, the NXP AN12312 Secure Boot on i.MX 8 and i.MX 8X Families using AHAB doesn't provide information on whether the CA flag being set is a recommended default, it only states the following:

The container signature is verified against the SGK key certificate, which is then verified against the SRK table. If the subordinate key is not used, the container signature is directly verified against the SRK keys.

Setup of the FIT Image Signing​

Configure the kernel FIT image signing as described on meta-toradex-security: README-secure-boot / Configuring FIT image signing.

For configuring additional aspects of the various features provided by tdx-signed (i.e. within the BCoT coverage level), refer to the meta-toradex-security README. Notice that the layer offers other functionalities (e.g. encryption) that may be utilized independent of the selected Secure Boot coverage level.

Setup of the Root Filesystem Protection​

Notice that this section is relevant only if the torizon-signed class is being used.

The root filesystem protection is based on composefs which is integrated into OSTree – a core technology employed by Torizon OS. When composefs is in use, OSTree's behavior regarding the generation and access to deployments changes significantly. Fortunately, most of these changes are transparent to users, but not all of them.

The most notable difference involves the management of the /etc directory. Without composefs, changes made to /etc are written to disk and persist after a reboot. However, when composefs is used, changes are stored on an overlay and are lost upon reboot. Such behavior may be acceptable for testing purposes but normally users will need to take decisions and perform customization in order to persist some of the files in /etc across reboots to ensure proper behavior of their products. To understand this topic, we encourage users to carefully read the article about the Root Filesystem Protection.

For configuring the present feature, the following variables are available (notice that their default values should work out-of-the-box, at least for development purposes):

VariableDescriptionDefault value
CFS_GENERATE_KEYSEnable ("1") or disable ("0") composefs key pair generation at build time."1"
CFS_SIGN_KEYDIRDirectory where the composefs keys are stored.${TOPDIR}/keys/ostree
CFS_SIGN_KEYNAMEBase name of the key files; the secret key will stored into a file named ${CFS_SIGN_KEYNAME}.sec and the public one into ${CFS_SIGN_KEYNAME}.pub.cfs-dev

Build the Image​

Build the Torizon OS image as explained in the article Build Torizon OS from Source With Yocto Project/OpenEmbedded.

Install Secure Boot Image​

A Secure Boot image can be flashed (installed) onto a Toradex SoM in the same manner as a Non-Secure image, by using Toradex Easy Installer. However, certain details are device-dependent, as explained in the following sections.

Devices based on NXP i.MX SoCs​

On NXP devices, the Secure Boot image will run normally after an installation because the device would be in the so called open state in terms of Secure Boot. In such a state, the ROM code does not prevent the boot of unsigned (or even wrongly signed) images. In other words, the first link in the CoT (ROM → bootloader) is not secured. For this reason, shipping devices in this state to the field would not be appropriate. They need to be placed into the closed state first, an operation that involves burning eFuses (Electronic fuses) with values representing the keys that are allowed to sign the software that will run on the device.

In case of NXP, the eFuse burning operations can be performed via the U-Boot serial console as described on meta-toradex-security: README-secure-boot-imx / Closing the device. The use of the console is generally acceptable for development and testing purposes, and, in some cases, even in production, but Torizon OS (since version 7.2.0) provides a feature that simplifies the process and that does not require access to the console. The feature allows one to embed the desired fuse values into an Easy Installer image, as part of the U-Boot environment blob that the installer flashes into the device. Then, the first time the device starts with the newly installed OS, it will safely burn the eFuses and close the device (if instructed to do so). To learn more about this feature, please refer to the article on Secure Boot Fuse Programming.

Irrespective of the chosen fusing method, it's important to keep in mind that:

Devices based on TI AM62x SoCs​

For TI devices, users need to select the desired target device state when building an image. A Secure Boot image built for a device in the open (or closed) state will only run on a device in that particular state. This is true for any image, including the Toradex Easy Installer which is built by Toradex to run on open devices. As a result we have the following possible scenarios:

  • An image targeting an open device (called HS-FS in TI terminology) is installed via Toradex Easy Installer: the image will run normally right after installation.
  • An image targeting a closed device (called simply HS in TI terminology) is installed via Toradex Easy Installer: the image will only run after additional steps are taken to program the device fuses and put it into the closed state. The process for fusing the keys is briefly described on meta-toradex-security: README-secure-boot-k3 / Fusing the keys into the SoC with references to TI documentation. Since the process is relatively complex, Toradex also provides a more thorough explanation on a dedicated article: Integrate Secure Boot on AM62-Based Devices.

In-field upgrades to Secure Boot​

Torizon OS enables users to perform in-field upgrades to Secure Boot (including fusing the devices remotely). To learn about this topic, please refer to the dedicated article: In-field Upgrades to Secure Boot on Torizon OS.

Key Management​

It is critical to manage signing keys with care. Losing or leaking keys may lead to compromising the system's security or preventing the system from being ever updated.

danger

If you lose the private keys you have created to sign your images, you won't be able to install or update the software on devices that are closed.

Keep your keys in a safe and secure place, and consider having one or more backups in physically different locations.

Due to the first keys from the CoT being often stored in a place tightly coupled with the Boot ROM, every silicon vendor, and even every SoC for a given vendor, may have their own specification and peculiarities.

Key Management on NXP i.MX SoMs​

In previous steps before the build, you had to perform a Setup for NXP i.MX SoMs, and in such case, you generated a PKI Tree, SRK Tables, and Efuse Hash. You must store those in a safe and secure place, otherwise, you won't be able to sign software with the corresponding keys and certificates that match the hashes used for verification on all SoMs closed with such corresponding Efuse Hashes.

In addition to it, for the NXP i.MX SoMs, you are entitled to burn 4 Efuse hashes on the SoC HAB/AHAB, thus you have effectively four valid signing keys to boot from. You can revoke them one by one, if and as needed, and still seamlessly boot from the other valid ones. You should consider keeping those in separate safe places so that in case a key gets compromised, you can use the others as backups.

Troubleshoot​

This section has some common issues and their fixes.

/usr/bin/env: ‘python’: No such file or directory​

When running repo init, you may see the following error:

/usr/bin/env: ‘python’: No such file or directory

This is because newer Linux distros don't provide python, only python3. On Ubuntu, you may work around this limitation by installing python-is-python3:

$ apt install python-is-python3

Could not find CST binary​

Make sure to download and configure the NXP CST tool, otherwise, you will see the following build error or similar:

ERROR: imx-boot-1.0-r0 do_compile: Could not find CST binary at /workdir/build-torizon/keys/cst/linux64/bin/cst

Could not find cert file SRK_1_2_3_4_table.bin​

Make sure to generate all the keys and certificates, otherwise, you will see the following build error or similar. Such an error may also happen if you generate the file with a name different than the one expected, which is SRK_1_2_3_4_table.bin:

ERROR: imx-boot-1.0-r0 do_compile: Could not find cert file at /workdir/cst-3.3.2/crts/SRK_1_2_3_4_table.bin.

Could not find cert file SRK1_sha256_2048_65537_v3_usr_crt.pem​

There is more than one reason for this error to happen.

  1. By default, the build expects the SRK certificates to be generated with the CA flag unset. If you set it, you may see the following error, in which case you can re-create the keys to fix it:
ERROR: imx-boot-1.0-r0 do_compile: Could not find cert file at /workdir/cst-3.3.2/crts/SRK1_sha256_2048_65537_v3_usr_crt.pem.
  1. The cert filename expected by OpenEmbedded is generated based on the configuration parameters TDX_IMX_HAB_CST_DIG_ALGO and TDX_IMX_HAB_CST_KEY_SIZE, both described on meta-toradex-security: README-secure-boot-imx. If you use different values when creating the certificates with the CST, the certificate file will not be found during the build.

Serial debug console hangs on "Starting version" during boot​

The serial debug console seems to hang on the line Starting version <version number> during boot:

[    1.906201] debugfs: Directory 'mipi1-i2c0' with parent 'pm_genpd' already present!
[    1.913875] debugfs: Directory 'mipi1-pwm0' with parent 'pm_genpd' already present!
[    1.921557] debugfs: Directory 'mipi1' with parent 'pm_genpd' already present!
[    2.039331] imx6q-pcie 5f010000.pcie: PCIe PLL lock timeout
Starting version 250.5+

The boot time during the first boot can take much longer than on an image without Secure Boot. Just wait a couple of minutes and the login prompt will appear.

On the second boot onward, boot time will be faster.

The SoM doesn't boot and nothing shows up on the debug UART​

This may happen if you use HABv4 keys to create the U-Boot binary for an AHAB SoM and vice-versa, for instance, by following the instructions in the wrong section of the NXP CST, or in case you are trying to use Secure Boot on different SoMs - one with HABv4 and another with AHAB - and you mistake the keys.

To fix it, create/use keys for the corresponding hardware.

The SoM uses a different bootloader than then one being installed​

This scenario may have the same root cause as the SoM doesn't boot and nothing shows up on the debug UART, and thus it may happen if you use HABv4 keys to create the U-Boot binary for an AHAB SoM and vice-versa, for instance, by following the instructions in the wrong section of the NXP CST, or in case you are trying to use Secure Boot on different SoMs - one with HABv4 and another with AHAB - and you mistake the keys.

But (1) why would it boot a different bootloader, and (2) where does it come from?

(1) The eMMC standard specifies two bootloader partitions. On some SoCs, if booting from the active bootloader partition fails, it will automatically try the other one.

(2) If you ever performed a bootloader update prior to trying Secure Boot on a given SoM, the procedure will install the new bootloader on the second partition and make it the default, keeping the previous bootloader on the other partition.

To fix it, create/use keys for the corresponding hardware.

HAB warning on i.MX6 based modules​

When running hab_status on i.MX6 based modules (Colibri i.MX6 & Apalis i.MX6), you may see a warning that looks similar to this:

Secure boot disabled

HAB Configuration: 0xf0, HAB State: 0x66

--------- HAB Event 1 -----------------
event data:
        0xdb 0x00 0x24 0x42 0x69 0x30 0xe1 0x1d
        0x00 0x04 0x00 0x02 0x40 0x00 0x36 0x06
        0x55 0x55 0x00 0x03 0x00 0x00 0x00 0x00
        0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
        0x00 0x00 0x00 0x01

STS = HAB_WARNING (0x69)
RSN = HAB_ENG_FAIL (0x30)
CTX = HAB_CTX_ENTRY (0xE1)
ENG = HAB_ENG_CAAM (0x1D)

This is due to a defect on certain silicon revisions of the SoC itself. For more information regarding this defect please refer to the official NXP public report on the matter. Just to summarize the main points:

  • This issue does not have any impact on the HAB/secure boot process.
  • This issue does not compromise the security of the device.
  • Devices showing this warning can still be safely closed via the corresponding Efuse.
  • There is no way to remove this warning message, so it will have to be ignored.
Send Feedback!