MLK-20553-1 doc: imx: ahab: Add AHAB introduction
The AHAB is currently supported in i.MX8QXP and i.MX8QM devices.
Add an introductory document containing the following topics:
- AHAB Secure Boot Architecture
- System Control Unit (SCU) introduction
- Security Controller (SECO) introduction
- i.MX8/8x secure boot flow
- AHAB PKI tree generation
- SRK Table and SRK Hash generation
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>
(cherry picked from commit 6e9ceb2526bd4a45c6ff669afb086cc3a0627e6b)
diff --git a/doc/imx/ahab/introduction_ahab.txt b/doc/imx/ahab/introduction_ahab.txt
new file mode 100644
index 0000000..fe026ff
--- /dev/null
+++ b/doc/imx/ahab/introduction_ahab.txt
@@ -0,0 +1,301 @@
+ +=======================================================+
+ + i.MX8/8x AHAB Secure Boot introduction +
+ +=======================================================+
+
+1. Introduction
+----------------
+
+The i.MX8 and i.MX8x family of applications processors introduce a new
+secure boot concept. Due to the multi-core architecture the Security
+Controller (SECO) and System Control Unit (SCU) are heavily involved in
+the secure boot process.
+
+Step-by-step guides are available under doc/imx/hab/ahab/guides/ directory,
+users familiar with AHAB architecture and CST PKI tree generation should
+refer to this directory instead.
+
+1.1 The AHAB Secure Boot Architecture
+--------------------------------------
+
+The Advanced High Assurance Boot (AHAB) feature relies in digital signatures to
+prevent unauthorized software execution during the device boot sequence. In
+case a malware takes control of the boot sequence, sensitive data, services and
+network can be impacted.
+
+The AHAB authentication is based on public key cryptography in which image
+data is signed offline using one or more private keys. The resulting signed
+image data is then verified on the i.MX processor using the corresponding
+public keys. The public keys are included in the final binary and the SRK
+Hash is programmed in the SoC fuses for establishing the root of trust.
+
+In i.MX8 and i.MX8x families the SCU is responsible to interface with the boot
+media, managing the process of loading the firmware and software images in
+different partitions of the SoC. The SECO is responsible to authenticate the
+images and authorize the execution of them.
+
+1.1.1 The System Control Unit (SCU)
+------------------------------------
+
+The System Control Unit SCU is a subsystem equipped with a programmable M4
+core, which is responsible to handle the resource allocation, power, clocking,
+IO configuration and muxing.
+
+The SCU is also responsible to interface between the rest of the system. In the
+secure boot flow the SCU interfaces with the Security Controller (SECO),
+requesting the image authentication.
+
+The System Control Unit FW (SCFW) is responsible to control all the
+functionalities of the SCU. This firmware is distributed in a porting kit form.
+Instructions to download the SCFW Porting Kit are available in the Linux BSP
+Release Notes.
+
+Details about SCU can be found in the processors Reference Manual (RM).
+
+1.1.2 The Security Controller (SECO)
+-------------------------------------
+
+The SECO is a M0+ core dedicated to handle the SoC security subsystem. The
+controller communicates with SCU domain through a dedicate message unit (MU).
+
+The SECO has a dedicate ROM which is responsible to initialize low level
+security features and to authenticate the SECO firmware previously loaded by
+the SCU ROM.
+
+The SECO firmware provides security services at run-time to different domains
+of the SoC, one of these being the capability of authenticate images.
+
+The SECO firmware is signed and distributed by NXP and is always authenticated
+in OEM open and closed configuration, instructions to download the SECO FW are
+available in the Linux BSP Release Notes.
+
+Details about SECO can be found in the processors Security Reference Manual
+(SRM).
+
+1.2 The image container
+------------------------
+
+Due to the new the architecture, multiple firmwares and softwares are required
+to boot i.MX8 and i.MX8x family devices. In order to store all the images in a
+single binary the container image structure is used.
+
+At least two containers are needed for the boot process, the first container
+must include only the SECO FW (provided by NXP). Additional containers can
+contain one or multiple images, depending on the users specific application.
+
+The final binary is generated by the imx-mkimage tool. The tool can generate
+additional containers and also combine all containers in a single binary.
+
+1.3 The i.MX8/8x secure boot flow
+----------------------------------
+
+As mentioned in the introduction, due to the multiple cores architecture the
+i.MX8 boot sequence involves SCU ROM, SCFW, SECO ROM, and SECO FW.
+
+The diagram below illustrate the secure boot flow overview:
+
+System Controller │ Security Controller │ Cortex-M │ Cortex-A
+ (SCU) │ (SECO) │ │
+ │ │ │
+ ╔═════════════╗ │ ╔═════════════╗ ┌───────────┐ ┌─────────┐
+ ║ SCU INIT ║ │ ║ SECO INIT ║ │ │ │ │ │ │
+ ╚══════╤══════╝ │ ╚══════╤══════╝ │ │ v │ │ v
+ │ │ │ │ │ ┌──────────┐ │ │ ┌────────────┐
+ ╔══════╧══════╗ │ │ │ │ │ Start M4 │ │ │ │ Start AP │
+ ║Load SECO FW ║ │ │ │ │ │ IMG │ │ │ │ IMG │
+ ╚══════╤══════╝ │ ╔══════╧══════╗ │ │ └──────────┘ │ │ └─────┬──────┘
+ ├──────────────>║Auth SECO FW ║ │ │ │ │ │
+ ╔══════╧══════╗ │ ╚══════╤══════╝ │ │ ┌────────────┘ │ │
+ ║ Load SCU FW ║ │ │ │ │ │ │ │
+ ║ and DCD ║ │ │ │ │ │ │ ┌─────┴──────┐
+ ╚══════╤══════╝ │ ┌──────┴──────┐ │ │ │ │ │ Load │
+ ├──────────────>│ Auth SCU FW │ │ │ │ │ │ Add AP IMG │
+ │ │ │ and DCD │ │ │ │ │ └─────┬──────┘
+ ╔══════╧══════╗ │ └──────┬──────┘ │ │ │ │ │
+ ║ Run DCD ║<──────────────┤ │ │ │ │ │
+ ╚══════╤══════╝ │ │ │ │ │ ┌───────────────┤
+ │ │ │ │ │ │ │ │ │
+ ╔══════╧══════╗ │ │ │ │ │ │ │ │
+ ║ Load M4 IMG ║ │ │ │ │ │ │ │ │
+ ╚══════╤══════╝ │ ┌──────┴──────┐ │ │ │ │ │ │
+ ├──────────────>│ Auth M4 IMG │ │ │ │ │ │ │
+ ╔══════╧══════╗ │ └──────┬──────┘ │ │ │ │ │ ┌─────┴──────┐
+ ║ Load AP IMG ║ │ │ │ │ │ │ │ │ Run │
+ ╚══════╤══════╝ │ ┌──────┴──────┐ │ │ │ │ │ │ Add AP IMG │
+ ├──────────────>│ Auth AP IMG │ │ │ │ │ │ └────────────┘
+ ╔══════╧══════╗ │ └─────────────┘ │ │ │ │ │
+ ║Start SCU FW ║ │ ┌──────────────────┘ │ │ │ │
+ ╚══════╤══════╝ │ │ │ │ │ │
+ │ │ │ ┌─────────────────────┘ │ │
+ ┌──────┴──────┐ │ │ │ │ │ │
+ │ Start M4 ├──────┘ │ ┌──────────────────────┘ │
+ └──────┬──────┘ │ │ │ │ │
+ │ │ │ │ │ │
+ ┌──────┴──────┐ │ │ │ │ │
+ │ Start AP ├──────────┘ │ │ │
+ └─────────────┘ │ │ │ │
+ ┌───────────────────────┘ │ │
+ │ │ │ │
+ v │ │ │
+ ┌─────────────┐ │ ┌─────────────┐ │ │
+ │Request SECO ├───────>│ Auth AP IMG │ │ │
+ └─────────────┘ │ └─────────────┘ │ │
+ │ │ │
+
+Notes:
+All boxes enclosed by double dash (═) are performed at SCU/SECO ROM level.
+
+The sequence below explains the i.MX8 and i.MX8x boot flow:
+
+1 - At reset, the SCU ROM and SECO ROM both start execution.
+2 - The SCU ROM reads the boot configuration and loads the SECO FW (First
+ container) from the boot media to the SECO TCM.
+3 - A message is sent by the SCU ROM via MU requesting the SECO ROM to
+ authenticate the SECO FW which is signed using NXP key.
+4 - The SCU ROM loads the second container from the boot media, this container
+ must contain at least the SCFW which is signed using the OEM keys.
+5 - The SCU ROM loads the SCFW to the SCU TCM, a message is sent via MU
+ requesting the SECO FW to authenticate the SCFW and DCD table.
+6 - The SCU ROM configures the DDR and loads the M4 and AP images included in
+ the second container to their respective load addresses.
+7 - The SCU ROM request the SECO FW to authenticate the M4 image.
+8 - The SCU ROM request the SECO FW to authenticate the AP image. This image
+ is the initial AP core software, depending in the U-Boot target it can
+ be the U-Boot and ATF or only SPL.
+9 - The SCFW is initialized and starts the ARM Cortex-M and Cortex-A cores.
+10 - From this point additional containers can be loaded by Cortex-M and
+ Cortex-A cores and authenticated by SECO, the AP SW must interface with
+ SCU by calling the sc_misc_seco_authenticate() API function. In current
+ U-Boot implementation the additional image can be the Linux Kernel binary
+ or the U-Boot proper and ATF. Details about current U-Boot implementation
+ can be found in AHAB guides included in doc/imx/hab/ahab/guides/ directory.
+
+2. Generating a PKI tree
+-------------------------
+
+The first step is to generate the private keys and public keys certificates.
+The AHAB architecture is based on a Public Key Infrastructure (PKI) tree.
+
+The Code Signing Tools package contains an OpenSSL based key generation script
+under keys/ directory. The ahab_pki_tree.sh script generates a PKI tree
+containing 4 Super Root Keys (SRK), possible to also include a subordinate
+SGK key.
+
+The AHAB supports both RSA and ECC keys, a new PKI tree can be generated by
+following the example below:
+
+- Generating a P384 ECC PKI tree on CST v3.1.0:
+
+ $ ./ahab_pki_tree.sh
+ ...
+ Do you want to use an existing CA key (y/n)?: n
+ Do you want to use Elliptic Curve Cryptography (y/n)?: y
+ Enter length for elliptic curve to be used for PKI tree:
+ Possible values p256, p384, p521: p384
+ Enter the digest algorithm to use: sha384
+ Enter PKI tree duration (years): 5
+ Do you want the SRK certificates to have the CA flag set? (y/n)?: n
+
+The diagram below illustrate the PKI tree generated:
+
+ ┌─────────┐
+ │ CA │
+ └────┬────┘
+ │
+ │
+ ┌───────────────┬────────┴────────┬───────────────┐
+ │ │ │ │
+ │ │ │ │
+ v v v v
+ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
+ │ SRK1 │ │ SRK2 │ │ SRK3 │ │ SRK4 │
+ └────────┘ └────────┘ └────────┘ └────────┘
+
+2.1 Generating a PKI tree including a subordinate SGK key
+----------------------------------------------------------
+
+The ahab_pki_tree.sh script is also able to generate a PKI tree containing a
+subordinate key of the SRK, this key can be used to verify the signature
+included in the final signed image.
+
+Users should set the CA flag when generating the SRK certificates.
+
+- Generating a P384 ECC PKI tree with a subordinate SGK key on CST v3.1.0:
+
+ $ ./ahab_pki_tree.sh
+ ...
+ Do you want to use an existing CA key (y/n)?: n
+ Do you want to use Elliptic Curve Cryptography (y/n)?: y
+ Enter length for elliptic curve to be used for PKI tree:
+ Possible values p256, p384, p521: p384
+ Enter the digest algorithm to use: sha384
+ Enter PKI tree duration (years): 5
+ Do you want the SRK certificates to have the CA flag set? (y/n)?: y
+
+The diagram below illustrate the PKI tree generated:
+
+ ┌─────────┐
+ │ CA │
+ └────┬────┘
+ │
+ │
+ ┌───────────────┬────────┴────────┬───────────────┐
+ │ │ │ │
+ v v v v
+ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
+ │ SRK1 │ │ SRK2 │ │ SRK3 │ │ SRK4 │
+ └────┬───┘ └───┬────┘ └────┬───┘ └───┬────┘
+ │ │ │ │
+ v v v v
+ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
+ │ SGK1 │ │ SGK2 │ │ SGK3 │ │ SGK4 │
+ └────────┘ └────────┘ └────────┘ └────────┘
+
+Note: Due to a limitation in i.MX8QXP B0 silicon it's not possible to use RSA
+4096-bit SRK keys with an additional subordinate SGK key.
+
+2.2 Generating a SRK Table and SRK Hash
+----------------------------------------
+
+The next step is to generated the SRK Table and its respective SRK Table Hash
+from the SRK public key certificates created in one of the steps above.
+
+In the AHAB architecture, the SRK Table is included in the signed image and the
+SRK Hash is programmed in the SoC SRK_HASH[511:0] fuses.
+
+On the target device during the authentication process the AHAB code verify the
+SRK Table against the SoC SRK_HASH fuses, in case the verification is successful
+the root of trust is established and the AHAB code can progress with the image
+authentication.
+
+The srktool can be used for generating the SRK Table and its respective SRK
+Table Hash.
+
+- Generating SRK Table and SRK Hash in Linux 64-bit machines:
+
+ $ cd ../crts/
+ $ ../linux64/bin/srktool -a -s sha384 -t SRK_1_2_3_4_table.bin \
+ -e SRK_1_2_3_4_fuse.bin -f 1 -c \
+ SRK1_sha384_secp384r1_v3_usr_crt.pem,\
+ SRK2_sha384_secp384r1_v3_usr_crt.pem,\
+ SRK3_sha384_secp384r1_v3_usr_crt.pem,\
+ SRK4_sha384_secp384r1_v3_usr_crt.pem
+
+- Optionally users can check if the sha512sum of SRK_1_2_3_4_table matches with
+ the SRK_1_2_3_4_fuse.bin:
+
+ $ od -t x4 --endian=big SRK_1_2_3_4_fuse.bin
+ 0000000 01b04697 0253376b 2066fe56 aaef9a91
+ 0000020 e62e09d8 14fb7e36 d5b38d05 0982edab
+ 0000040 7ada6576 2f6b4f59 1fd9347e 46e7305d
+ 0000060 46e34bf0 89780bd1 c809e714 a17e2f4e
+
+ $ sha512sum SRK_1_2_3_4_table.bin
+ 01b046970253376b2066fe56aaef9a91\
+ e62e09d814fb7e36d5b38d050982edab\
+ 7ada65762f6b4f591fd9347e46e7305d\
+ 46e34bf089780bd1c809e714a17e2f4e\
+ SRK_1_2_3_4_table.bin
+
+The SRK_1_2_3_4_table.bin and SRK_1_2_3_4_fuse.bin files can be used in further
+steps as explained in AHAB guides available under doc/imx/hab/ahab/guides/
+directory.
