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)

1 files changed, 301 insertions, 0 deletions

diff --git a/doc/imx/hab/ahab/introduction_ahab.txt b/doc/imx/hab/ahab/introduction_ahab.txt
new file mode 100644
index 0000000000..fe026ffcc5
--- /dev/null
+++ b/doc/imx/hab/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.