Skip to content

Latest commit

 

History

History
68 lines (49 loc) · 4.66 KB

README-secure-boot-imx.md

File metadata and controls

68 lines (49 loc) · 4.66 KB
Raw

Bootloader signature checking for NXP iMX-based platforms

This document describes how bootloader signature checking works for System on Modules (SoMs) that use iMX-based System on Chips (SoCs) by NXP Semiconductors.

Introduction

To support bootloader signature checking, such a feature needs to be available in the SoC ROM code.

On iMX6, iMX7 and iMX8M, this feature is available and it is called HAB (High Assurance Boot).

On iMX8 and iMX8X, this feature is available and it is called AHAB (Advanced High Assurance Boot).

Configuring HAB/AHAB support

When the tdx-signed class is inherited, signing bootloader images via HAB/AHAB is enabled by default. Set TDX_IMX_HAB_ENABLE to 0 to disable it.

Before using this feature, it is required to:

  1. Download NXP CST tool from https://www.nxp.com/webapp/sps/download/license.jsp?colCode=IMX_CST_TOOL_NEW.
  2. Follow the NXP documentation to generate the keys, certificates, SRK tables and Efuse Hash (the documentation can be found inside the CST tool in docs/CST_UG.pdf); be sure to take note of your answers to the key generation script.

After that, configure the various variables listed below to match your choices; pay special attention to the ones depending on your answers to the NXP key generation script.

Variable Description Default value
TDX_IMX_HAB_ENABLE Enable/disable HAB/AHAB support; allowed values: 0 or 1. 1
TDX_IMX_HAB_CST_DIR Location of the CST tool. ${TOPDIR}/keys/cst
TDX_IMX_HAB_CST_CERTS_DIR Location of the certificates directory. The associated private keys must be located in a directory called keys at the same level as the crts directory (this is a requirement for the CST tool to work properly). ${TDX_IMX_HAB_CST_DIR}/crts
TDX_IMX_HAB_CST_CRYPTO Type of cryptographic keys in use; allowed values: rsa or ecdsa. This should be set to ecdsa if (and only if) you selected "Elliptic Curve Cryptography" when generating the keys/certificates with the CST tool. rsa
TDX_IMX_HAB_CST_KEY_SIZE For RSA keys, this would be the key length (in bits) as entered into the CST tool. For ECDSA, this would be a string determined from the generated certificate file name; for example, for a file named SRK1_sha256_secp384r1_v3_ca_crt.pem (found in the certificates directory) the present variable would be set to secp384r1. 2048
TDX_IMX_HAB_CST_DIG_ALGO Digest algorithm as entered into the CST tool. sha256
TDX_IMX_HAB_CST_SRK_CA Whether or not the SRK certificates have the CA flag set as entered into the CST tool; allowed values: 0 or 1. 1

The complete list of variables can be found in the imx-hab.bbclass file.

Known issues

  • On devices based on the NXP i.MX6 and i.MX7 SoCs, TDX_IMX_HAB_CST_SRK_CA must be set to 1 and the SRK certificates must be generated with the CA flag set. Build errors will happen if the variable is set to 0 because the signing logic currently unconditionally tries to use the CSF and IMG certificates which are not generated by CST when the CA flag is not set.

Closing the device

If HAB/AHAB is enabled, at the end of the build, a file with the commands to fuse the SoC (fuse-cmds.txt) will be generated in the images directory. The commands in this file should be executed in the U-Boot command line interface.

Read the warning messages carefully and be aware that the commands will write to One-Time Programmable e-fuses, and once you write them, you can't go back! You can check for HAB events with the command hab_status for HAB or ahab_status for AHAB. It is recommended to read NXP documentation about HAB/AHAB before writing to the e-fuses. This is an output example of the fuse-cmds.txt file:

$ cat deploy/images/verdin-imx8mp/fuse-cmds.txt
# These are One-Time Programmable e-fuses. Once you write them you can't
# go back, so get it right the first time!
fuse prog -y 6 0 0x8AE322B2
fuse prog -y 6 1 0xDF2939A3
fuse prog -y 6 2 0x9DA80323
fuse prog -y 6 3 0x3B024EF2
fuse prog -y 7 0 0xA53091
fuse prog -y 7 1 0x55304E7A
fuse prog -y 7 2 0xFB8FF259
fuse prog -y 7 3 0x9CE57582

# After the device successfully boots a signed image without generating
# any HAB events, it is safe to secure, or 'close', the device. This is
# the last step in the process. Once the fuse is blown, the chip does
# not load an image that has not been signed using the correct PKI tree.
# Be careful! This is again a One-Time Programmable e-fuse. Once you
# write it you can't go back, so get it right the first time. If
# anything in the previous steps wasn't done correctly, after writing
# this bit, the SOM will not boot anymore!
fuse prog -y 1 3 0x02000000