MLK-20553-3 doc: imx: ahab: Add Secure Boot documentation for i.MX8 and i.MX8x SPL targets
The current U-Boot implementation includes SPL targets for i.MX8QM and i.MXQXP MEK boards: - imx8qxp_mek_spl_defconfig - imx8qxp_mek_spl_fspi_defconfig - imx8qm_mek_spl_defconfig - imx8qm_mek_spl_fspi_defconfig The U-Boot proper and ATF are included in an additional container being necessary a different procedure for signing the flash.bin image. Add a step-by-step guide covering the signing procedure. Add a CSF example for the 3rd container. Signed-off-by: Breno Lima <breno.lima@nxp.com> Reviewed-by: Frank Zhang <frank.zhang@nxp.com> Reviewed-by: Marius Grigoras <marius.grigoras@nxp.com> Reviewed-by: Utkarsh Gupta <utkarsh.gupta@nxp.com>
This commit is contained in:
Breno Lima
Ye Li
parent
7c46caba3b
commit
04505024d3
|
|
@ -0,0 +1,21 @@
|
||||||
|
[Header]
|
||||||
|
Target = AHAB
|
||||||
|
Version = 1.0
|
||||||
|
|
||||||
|
[Install SRK]
|
||||||
|
# SRK table generated by srktool
|
||||||
|
File = "../crts/SRK_1_2_3_4_table.bin"
|
||||||
|
# Public key certificate in PEM format on this example only using SRK key
|
||||||
|
Source = "../crts/SRK1_sha384_secp384r1_v3_usr_crt.pem"
|
||||||
|
# Index of the public key certificate within the SRK table (0 .. 3)
|
||||||
|
Source index = 0
|
||||||
|
# Type of SRK set (NXP or OEM)
|
||||||
|
Source set = OEM
|
||||||
|
# bitmask of the revoked SRKs
|
||||||
|
Revocations = 0x0
|
||||||
|
|
||||||
|
[Authenticate Data]
|
||||||
|
# Binary to be signed generated by mkimage
|
||||||
|
File = "u-boot-atf-container.img"
|
||||||
|
# Offsets = Container header Signature block (printed out by mkimage)
|
||||||
|
Offsets = 0x0 0x110
|
||||||
|
|
@ -0,0 +1,358 @@
|
||||||
|
+=========================================================+
|
||||||
|
+ i.MX 8, i.MX 8X AHAB guide on SPL targets +
|
||||||
|
+=========================================================+
|
||||||
|
|
||||||
|
1. AHAB secure boot process
|
||||||
|
----------------------------
|
||||||
|
|
||||||
|
This document provides a step-by-step guide on how securely boot a flash.bin
|
||||||
|
image generated by Secondary Program Loader (SPL) targets. It is assumed that
|
||||||
|
the reader is familiar with basic AHAB concepts and with the PKI tree
|
||||||
|
generation.
|
||||||
|
|
||||||
|
Details about AHAB can be found in the introduction_ahab.txt document and in
|
||||||
|
processors Security Reference Manual Document (SRM).
|
||||||
|
|
||||||
|
1.1 Preparing the environment to build a secure boot image
|
||||||
|
-----------------------------------------------------------
|
||||||
|
|
||||||
|
The following files and projects are used to prepare a secure boot image
|
||||||
|
for i.MX8/8x device:
|
||||||
|
|
||||||
|
- imx-mkimage.
|
||||||
|
- SECO Firmware.
|
||||||
|
- U-Boot proper and SPL. (Please refer to section 1.2)
|
||||||
|
- ARM Trusted Firmware (ATF).
|
||||||
|
- System Controller Firmware (SCFW) with debug monitor enabled.
|
||||||
|
- Cortex M binary. (Optional)
|
||||||
|
- Kernel image. (Optional)
|
||||||
|
- Code signing tools (CST).
|
||||||
|
|
||||||
|
The procedure to download the SECO firmware and build U-Boot, SCFW and ATF are
|
||||||
|
out of the scope of this document, please refer to the Linux BSP Release Notes
|
||||||
|
and AN12212[1] for further details.
|
||||||
|
|
||||||
|
1.2 Preparing U-Boot to support AHAB secure boot features
|
||||||
|
----------------------------------------------------------
|
||||||
|
|
||||||
|
The U-Boot provides an alternative SPL target for i.MX8 and i.MX8x devices. The
|
||||||
|
SPL is intended to be used by applications that requires a initial bootloader
|
||||||
|
prior to initialize the ARM Trusted Firmware (ATF) and the U-Boot proper.
|
||||||
|
|
||||||
|
The U-Boot support AHAB functions that are essential to completely authenticate
|
||||||
|
the flash.bin image. On SPL targets only the SCFW, SPL and M4 IMG are
|
||||||
|
authenticated at SCU ROM level, in order to authenticate the ATF and U-Boot
|
||||||
|
proper it's necessary to call the SCU API sc_misc_seco_authenticate() function
|
||||||
|
at SPL level.
|
||||||
|
|
||||||
|
The support is enabled by adding CONFIG_AHAB_BOOT to the defconfig file used
|
||||||
|
by your target:
|
||||||
|
|
||||||
|
- Defconfig:
|
||||||
|
CONFIG_AHAB_BOOT=y
|
||||||
|
- Kconfig:
|
||||||
|
ARM architecture -> Support i.MX 8 AHAB features
|
||||||
|
|
||||||
|
1.3 Building a SPL image supporting secure boot
|
||||||
|
------------------------------------------------
|
||||||
|
|
||||||
|
The boot image generated by SPL targets has three containers:
|
||||||
|
|
||||||
|
+---------------------------+ ---------
|
||||||
|
| 1st Container header | ^
|
||||||
|
| and signature | |
|
||||||
|
+---------------------------+ |
|
||||||
|
| Padding for 1kB alignment | |
|
||||||
|
+---------------------------+ |
|
||||||
|
| 2nd Container header | |
|
||||||
|
| and signature | |
|
||||||
|
+---------------------------+ |
|
||||||
|
| Padding | | Authenticated at
|
||||||
|
+---------------------------+ | SCU ROM Level
|
||||||
|
| SECO FW | |
|
||||||
|
+---------------------------+ |
|
||||||
|
| Padding | |
|
||||||
|
+---------------------------+ |
|
||||||
|
| SCU FW + DCD Table | |
|
||||||
|
+---------------------------+ |
|
||||||
|
| Cortex-M Image | |
|
||||||
|
+---------------------------+ |
|
||||||
|
| SPL Image | v
|
||||||
|
+---------------------------+ ---------
|
||||||
|
| 3rd Container header | ^
|
||||||
|
| and signature | |
|
||||||
|
+---------------------------+ |
|
||||||
|
| Padding | | Authenticated
|
||||||
|
+---------------------------+ | at SPL Level
|
||||||
|
| U-Boot Proper IMG | |
|
||||||
|
+---------------------------+ |
|
||||||
|
| ARM Trusted FW (ATF) | v
|
||||||
|
+---------------------------+ ---------
|
||||||
|
|
||||||
|
The first container includes the SECO firmware which is signed using NXP keys,
|
||||||
|
this container is authenticated by SECO ROM at SCU ROM level.
|
||||||
|
|
||||||
|
The second container includes the SCFW, SPL and Cortex M SW images which are
|
||||||
|
signed using OEM keys, this container is authenticated by SECO FW at SCU ROM
|
||||||
|
level.
|
||||||
|
|
||||||
|
The third container includes the U-Boot proper and the ATF. The SPL is in
|
||||||
|
charge to load this container and also to interface with SCU requesting
|
||||||
|
SECO FW to authenticate the additional container.
|
||||||
|
|
||||||
|
The signing procedure is slightly different when compared with HABv4 series. On
|
||||||
|
AHAB the signature is directly included in the container, the CST is
|
||||||
|
responsible to sign and handle the "Signature Block":
|
||||||
|
|
||||||
|
+----------------------------+ ---------
|
||||||
|
| | ^
|
||||||
|
| | |
|
||||||
|
| Container header | |
|
||||||
|
| | |
|
||||||
|
| | |
|
||||||
|
+---+----------------------- + |
|
||||||
|
| S | Signature block header | | Signed
|
||||||
|
| i +------------------------+ |
|
||||||
|
| g | | |
|
||||||
|
| n | | |
|
||||||
|
| a | SRK table | |
|
||||||
|
| t | | |
|
||||||
|
| u | | v
|
||||||
|
| r +------------------------+ ---------
|
||||||
|
| e | Signature |
|
||||||
|
| +------------------------+
|
||||||
|
| B | |
|
||||||
|
| l | SGK Key |
|
||||||
|
| o | Certificate (optional) |
|
||||||
|
| c | |
|
||||||
|
| k | |
|
||||||
|
+---+------------------------+
|
||||||
|
|
||||||
|
In case using the optional subordinate SGK key, the container signature is
|
||||||
|
verified against the SGK key certificate. This certificate is verified
|
||||||
|
against the SRK table.
|
||||||
|
|
||||||
|
In case not using the subordinate key, the container signature is verified
|
||||||
|
against the SRK keys directly.
|
||||||
|
|
||||||
|
1.4 Preparing the boot image
|
||||||
|
-----------------------------
|
||||||
|
|
||||||
|
1.4.1 Preparing the 3rd container
|
||||||
|
----------------------------------
|
||||||
|
|
||||||
|
The first step is to generate the third container including the U-Boot proper
|
||||||
|
and ATF images.
|
||||||
|
|
||||||
|
The imx-mkimage project includes a target which only generates this third
|
||||||
|
container:
|
||||||
|
|
||||||
|
- Generating the U-Boot proper + ATF container:
|
||||||
|
|
||||||
|
$ make SOC=<SoC Name> u-boot-atf-container.img
|
||||||
|
|
||||||
|
The mkimage log provides the container and signature block offsets used by the
|
||||||
|
CSF description file:
|
||||||
|
|
||||||
|
CST: CONTAINER 0 offset: 0x0
|
||||||
|
CST: CONTAINER 0: Signature Block: offset is at 0x110
|
||||||
|
|
||||||
|
The u-boot-atf-container.img file is the third container which have to be
|
||||||
|
signed using the Code Signing Tool (CST).
|
||||||
|
|
||||||
|
1.4.2 Signing the 3rd container
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
|
The CSF description file contains all the commands that the SECO executes
|
||||||
|
during the secure boot procedure. These commands instruct the AHAB code on
|
||||||
|
which memory areas of the image to authenticate, which keys to install, use
|
||||||
|
and etc.
|
||||||
|
|
||||||
|
CSF examples are available under doc/imx/hab/ahab/csf_examples/ directory.
|
||||||
|
|
||||||
|
As explained in section above the mkimage log provides the container and
|
||||||
|
signature block offsets used by the CSF description file:
|
||||||
|
|
||||||
|
- "Authenticate Data" command in cst_uboot_atf.txt file:
|
||||||
|
|
||||||
|
[Authenticate Data]
|
||||||
|
# Binary to be signed generated by mkimage
|
||||||
|
File = "u-boot-atf-container.img"
|
||||||
|
# Offsets = Container header Signature block
|
||||||
|
Offsets = 0x0 0x110
|
||||||
|
|
||||||
|
- Sign the third container:
|
||||||
|
|
||||||
|
$ ./cst -i cst_uboot_atf.txt -o signed-u-boot-atf-container.img
|
||||||
|
|
||||||
|
The signed-u-boot-atf-container.img have to be copied to imx-mkimage directory
|
||||||
|
and renamed to u-boot-atf-container.img.
|
||||||
|
|
||||||
|
1.4.3 Preparing the flash.bin image
|
||||||
|
------------------------------------
|
||||||
|
|
||||||
|
The signed 3rd container can be now used to create the final flash.bin image,
|
||||||
|
be sure that your signed container were successfully replaced and is named
|
||||||
|
as u-boot-atf-container.img.
|
||||||
|
|
||||||
|
- Generating the flash.bin image:
|
||||||
|
|
||||||
|
$ make SOC=<SoC Name> flash_spl_container
|
||||||
|
|
||||||
|
The mkimage log provides the container and signature block offsets used by the
|
||||||
|
CSF description file:
|
||||||
|
|
||||||
|
CST: CONTAINER 0 offset: 0x400
|
||||||
|
CST: CONTAINER 0: Signature Block: offset is at 0x510
|
||||||
|
|
||||||
|
The flash.bin file include three containers and the second container have to be
|
||||||
|
signed using the Code Signing Tool (CST).
|
||||||
|
|
||||||
|
1.4.4 Signing the flash.bin image
|
||||||
|
----------------------------------
|
||||||
|
|
||||||
|
As mentioned above the CSF description file contains all the commands that
|
||||||
|
the SECO executes during the secure boot procedure.
|
||||||
|
|
||||||
|
The procedure for signing the flash.bin image is similar as documented in
|
||||||
|
mx8_mx8x_secure_boot.txt guide.
|
||||||
|
|
||||||
|
- "Authenticate Data" command in csf_boot_image.txt file:
|
||||||
|
|
||||||
|
[Authenticate Data]
|
||||||
|
# Binary to be signed generated by mkimage
|
||||||
|
File = "flash.bin"
|
||||||
|
# Offsets = Container header Signature block
|
||||||
|
Offsets = 0x400 0x510
|
||||||
|
|
||||||
|
- Sign the flash.bin container:
|
||||||
|
|
||||||
|
$ ./cst -i csf_boot_image.txt -o signed-flash.bin
|
||||||
|
|
||||||
|
The signed-flash.bin image contains all the signatures and can be flashed in
|
||||||
|
the device.
|
||||||
|
|
||||||
|
1.5 Flashing the signed image
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
After completing all steps in section "1.4 Preparing the boot image" the
|
||||||
|
signed flash.bin image can be flashed in the device:
|
||||||
|
|
||||||
|
$ sudo dd if=signed-flash.bin of=/dev/sd<X> bs=1k seek=32 && sync
|
||||||
|
|
||||||
|
For the next steps you should be able to see U-Boot and SCFW consoles in your
|
||||||
|
host PC. Please note that SCU console may be replaced by the M4 console, in
|
||||||
|
case the M4 image is needed a base board will be required to access the SCU
|
||||||
|
console.
|
||||||
|
|
||||||
|
1.6 Programming SRK Hash
|
||||||
|
-------------------------
|
||||||
|
|
||||||
|
As explained in introduction_ahab.txt document the SRK Hash fuse values are
|
||||||
|
generated by the srktool and should be programmed in the SoC SRK_HASH[511:0]
|
||||||
|
fuses.
|
||||||
|
|
||||||
|
Be careful when programming these values, as this data is the basis
|
||||||
|
for the root of trust. An error in SRK Hash results in a part that
|
||||||
|
does not boot.
|
||||||
|
|
||||||
|
The U-Boot fuse tool can be used for programming eFuses on i.MX SoCs.
|
||||||
|
|
||||||
|
- Dump SRK Hash fuses values in host machine:
|
||||||
|
|
||||||
|
$ od -t x4 SRK_1_2_3_4_fuse.bin
|
||||||
|
0000000 d436cc46 8ecccda9 b89e1601 5fada3db
|
||||||
|
0000020 d454114a b6cd51f4 77384870 c50ee4b2
|
||||||
|
0000040 a27e5132 eba887cf 592c1e2b bb501799
|
||||||
|
0000060 ee702e07 cf8ce73e fb55e2d5 eba6bbd2
|
||||||
|
|
||||||
|
- Program SRK_HASH[511:0] fuses:
|
||||||
|
|
||||||
|
* On i.MX 8 QXP:
|
||||||
|
|
||||||
|
=> fuse prog 0 730 0xd436cc46
|
||||||
|
=> fuse prog 0 731 0x8ecccda9
|
||||||
|
=> fuse prog 0 732 0xb89e1601
|
||||||
|
=> fuse prog 0 733 0x5fada3db
|
||||||
|
=> fuse prog 0 734 0xd454114a
|
||||||
|
=> fuse prog 0 735 0xb6cd51f4
|
||||||
|
=> fuse prog 0 736 0x77384870
|
||||||
|
=> fuse prog 0 737 0xc50ee4b2
|
||||||
|
=> fuse prog 0 738 0xa27e5132
|
||||||
|
=> fuse prog 0 739 0xeba887cf
|
||||||
|
=> fuse prog 0 740 0x592c1e2b
|
||||||
|
=> fuse prog 0 741 0xbb501799
|
||||||
|
=> fuse prog 0 742 0xee702e07
|
||||||
|
=> fuse prog 0 743 0xcf8ce73e
|
||||||
|
=> fuse prog 0 744 0xfb55e2d5
|
||||||
|
=> fuse prog 0 745 0xeba6bbd2
|
||||||
|
|
||||||
|
* On i.MX 8 QM:
|
||||||
|
|
||||||
|
=> fuse prog 0 722 0xd436cc46
|
||||||
|
=> fuse prog 0 723 0x8ecccda9
|
||||||
|
=> fuse prog 0 724 0xb89e1601
|
||||||
|
=> fuse prog 0 725 0x5fada3db
|
||||||
|
=> fuse prog 0 726 0xd454114a
|
||||||
|
=> fuse prog 0 727 0xb6cd51f4
|
||||||
|
=> fuse prog 0 728 0x77384870
|
||||||
|
=> fuse prog 0 729 0xc50ee4b2
|
||||||
|
=> fuse prog 0 730 0xa27e5132
|
||||||
|
=> fuse prog 0 731 0xeba887cf
|
||||||
|
=> fuse prog 0 732 0x592c1e2b
|
||||||
|
=> fuse prog 0 733 0xbb501799
|
||||||
|
=> fuse prog 0 734 0xee702e07
|
||||||
|
=> fuse prog 0 735 0xcf8ce73e
|
||||||
|
=> fuse prog 0 736 0xfb55e2d5
|
||||||
|
=> fuse prog 0 737 0xeba6bbd2
|
||||||
|
|
||||||
|
1.7 Verify SECO events
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
If the fuses have been written properly, there should be no SECO events
|
||||||
|
after boot. To validate this, power on the board, and run the following
|
||||||
|
command on the SCFW terminal:
|
||||||
|
|
||||||
|
>$ seco events
|
||||||
|
|
||||||
|
Nothing should be returned after this command. If you get an error, please
|
||||||
|
refer to examples below:
|
||||||
|
|
||||||
|
0x0087EE00 = The container image is not signed.
|
||||||
|
0x0087FA00 = The container image was signed with wrong key which are not
|
||||||
|
matching the OTP SRK hashes.
|
||||||
|
|
||||||
|
In case your SRK fuses are not programmed yet the event 0x0087FA00 may also
|
||||||
|
be displayed.
|
||||||
|
|
||||||
|
Note: The SECO FW v1.1.0 is not logging an invalid image integrity as an event
|
||||||
|
in open mode, in case your image does not boot after moving the lifecycle
|
||||||
|
please review your image setup.
|
||||||
|
|
||||||
|
1.8 Close the device
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
After the device successfully boots a signed image without generating any
|
||||||
|
SECO security events, it is safe to close the device. The SECO lifecycle
|
||||||
|
should be changed from 32 (0x20) NXP open to 128 (0x80) OEM closed. Be
|
||||||
|
aware this step can damage your board if a previous step failed. It is
|
||||||
|
also irreversible. Run on the SCFW terminal:
|
||||||
|
|
||||||
|
>$ seco lifecycle 16
|
||||||
|
|
||||||
|
Now reboot the target, and on the same terminal, run:
|
||||||
|
|
||||||
|
>$ seco info
|
||||||
|
|
||||||
|
The lifecycle value should now be 128 (0x80) OEM closed.
|
||||||
|
|
||||||
|
2. Authenticating the OS container
|
||||||
|
-----------------------------------
|
||||||
|
|
||||||
|
The procedure for authenticating the OS container is similar as in Non-SPL
|
||||||
|
targets, for a complete procedure please refer to mx8_mx8x_secure_boot.txt
|
||||||
|
document available under doc/imx/hab/ahab/guides/ directory.
|
||||||
|
|
||||||
|
References:
|
||||||
|
[1] AN12212: "Software Solutions for Migration Guide from Aarch32 to
|
||||||
|
Aarch64" - Rev 0."
|
||||||
Loading…
Reference in New Issue