[PATCH v2 5/7] doc: imx: ahab: add AHAB introduction

["Jérémie Dautheribes (Schneider Electric)" <jeremie.dautheribes@bootlin.com>]

Add an introductory document describing the AHAB (Advanced High
Assurance Boot) secure and encrypted boot flow, covering the
following topics:
- AHAB architecture overview (SCU, SECO, PKI tree)
- AHAB secure boot and encrypted boot flow
- PKI tree generation (ahab_pki_tree.sh)
- SRK Table and SRK Hash generation (srktool)
- SRK Hash fuse programming and sanity check notes
- i.MX 8ULP/93 secure boot support

This is based on doc/imx/ahab/introduction_ahab.txt from uboot-imx
(lf_v2026.04). Originally written by Breno Lima, with contributions
from Ye Li, Vanessa Maegima, and Utkarsh Gupta upstream in
uboot-imx.

Signed-off-by: Jérémie Dautheribes (Schneider Electric) <jeremie.dautheribes@bootlin.com>
---
 doc/board/nxp/index.rst            |   2 +
 doc/imx/ahab/introduction_ahab.rst | 464 +++++++++++++++++++++++++++++++++++++
 doc/imx/ahab/introduction_ahab.txt | 445 +++++++++++++++++++++++++++++++++++
 doc/imx/index.rst                  |  13 ++
 4 files changed, 924 insertions(+)

diff --git a/doc/board/nxp/index.rst b/doc/board/nxp/index.rst
index b28e5b6ceb9..29a90297675 100644
--- a/doc/board/nxp/index.rst
+++ b/doc/board/nxp/index.rst
@@ -29,6 +29,8 @@ NXP Semiconductors
    mx6sabresd
    mx6ul_14x14_evk
    mx6ullevk
+
+   i.MX AHAB secure boot <../../imx/index>
    rproc
    psb
    quickboot
diff --git a/doc/imx/ahab/introduction_ahab.rst b/doc/imx/ahab/introduction_ahab.rst
new file mode 100644
index 00000000000..aef75b5e841
--- /dev/null
+++ b/doc/imx/ahab/introduction_ahab.rst
@@ -0,0 +1,464 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+i.MX Secure and Encrypted Boot using AHAB
+=========================================
+
+1. Introduction
+---------------
+
+The i.MX 8/8x/8ULP/9x 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) in i.MX 8/8x, and EdgeLock secure enclave (ELE)
+in i.MX 8ULP/9x are heavily involved in the secure boot process.
+
+Step-by-step guides are available under doc/imx/ahab/guides/ directory,
+users familiar with AHAB architecture and CST PKI tree generation should
+refer to these documents 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 [i.MX 8/8x] 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 [i.MX 8/8x] 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.1.3 [i.MX 8ULP/9x] The EdgeLock secure enclave
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+EdgeLock Secure Enclave is the security subsystem based on a dedicated core
+(RISC-V) to manage security tasks with a tight control on security resources
+along with other enhancements.
+
+The secure enclave has a dedicate ROM which is responsible to initialize low
+level security features and to authenticate the secure enclave firmware
+previously loaded by the boot management core.
+
+The secure enclave firmware provides security services at run-time to different
+domains of the SoC, one of these being the capability of authenticate images.
+
+The secure enclave firmware is signed and distributed by NXP and is always
+authenticated in OEM open and closed configuration, instructions to download
+this FW are available in the Linux BSP Release Notes.
+
+Details about EdgeLock secure enclave can be found in the processors Security
+Reference Manual (SRM).
+
+.. note::
+
+   The terms Sentinel, S400, and EdgeLock secure enclave (ELE)
+   are used interchangeably throughout the document.
+
+1.2 The image container
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Due to the new architecture, multiple firmwares and software are required to
+boot AHAB supporting 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 Security Subsystem FW (SECO/ELE 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 binman tool.
+
+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:
+
+.. code-block:: text
+
+   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.
+
+1.4 The i.MX 8ULP/9x secure boot flow
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The secure boot sequence involves multiple cores booting up at same time and
+EdgeLock secure enclave ensure authentication of any boot software being loaded.
+
+The diagram below illustrate the secure boot flow overview for dual boot
+scenario in i.MX 8ULP:
+
+.. code-block:: text
+
+       Cortex-M(CM)     │   EdgeLock Secure   │    Cortex-A(CA)   │   uPower(uP)
+                        │    Enclave(ELE)     │                   │
+              │          │          │          │         │         │        │
+       ┌┬─────┴─────┬┐   │   ┌┬─────┴─────┬┐   │         │         │ ┌┬─────┴─────┬┐
+       ││   INIT    ││   │   ││   INIT    ││   │         │         │ ││   INIT    ││
+       └┴─────┬─────┴┘   │   └┴─────┬─────┴┘   │         │         │ └┴─────┬─────┴┘
+              │          │          │          │  ┌┬─────┴─────┬┐  │        │
+       ┌┬─────┴─────┬┐   │          │          │  ││Load CA FW ││  │ ┌──────┐  │
+       ││Load uP FW ││   │          │          │  └┴─────┬─────┴┘  ││     │  │
+       └┴─────┬─────┴┘   │          │          │         │        ││ ┌┬──v──┴─────┬┐
+              │          │   ┌┬─────┴─────┬┐   │┌────────┤        ││ ││Load &Start││
+              ├─────────────>├│Auth uP FW ││   ││        │        ││ ││   uP FW   ││
+              │          │   └┴─────┬─────┴┘   ││        │        ││ └┴───────────┴┘
+       ┌┬─────┴─────┬┐   │          │          ││        │        ││
+       ││Load CM  FW││   │          ├────────────────────┼────────┘│
+       └┴─────┬─────┴┘   │          │          ││        │         │
+              │          │   ┌┬─────┴─────┬┐   ││        │         │
+              ├─────────────>├│Auth CM FW ││   ││ ┌┬─────┴─────┬┐  │
+              │          │   └┴─────┬─────┴┘   ││ ││Start CA FW││  │
+       ┌┬─────┴─────┬┐   │          │          ││ └┴─────┬─────┴┘  │
+       ││Load ELE FW││   │          │          ││        │         │
+       └┴─────┬─────┴┘   │          │          ││        │         │
+              │          │   ┌┬─────┴─────┬┐   ││        │         │
+              ├─────────────>├│Auth ELE FW││   ││        │         │
+              │          │   └┴─────┬─────┴┘   ││ ┌┬─────┴─────┬┐  │
+       ┌┬─────┴─────┬┐   │          │          ││ ││ Load SPL  ││  │
+       ││Start CM FW││   │          │          ││ └┴─────┬─────┴┘  │
+       └┴─────┬─────┴┘   │          │          ││        │         │
+              │          │   ┌┬─────┴─────┬┐   ││   ┌────┤         │
+              │          │   ││Auth CA FW │┤<───┘   │    │         │
+              │          │   └┴─────┬─────┴┘   │    │    │         │
+              │          │          │          │    │    │         │
+              │          │   ┌┬─────┴─────┬┐   │    │    │         │
+              │          │   ││ Auth SPL  │┤<───────┘    │         │
+              │          │   └┴─────┬─────┴┘   │         │         │
+              │          │          ├─────────────────┐  │         │
+              │          │          │          │      │  │         │
+              │          │          │          │  ┌┬──v──v─────┬┐  │
+              │          │          │          │  ││  Run SPL  ││  │
+              │          │          │          │  └┴───────────┴┘  │
+
+The diagram below illustrate the secure boot flow overview for single boot
+scenario in i.MX 9x:
+
+.. code-block:: text
+
+       Cortex-A(CA)     │   EdgeLock Secure   │    Cortex-M(CM)
+                        │    Enclave(ELE)     │
+              │          │          │          │         │
+       ┌┬─────┴─────┬┐   │   ┌┬─────┴─────┬┐   │         │
+       ││   INIT    ││   │   ││   INIT    ││   │         │
+       └┴─────┬─────┴┘   │   └┴─────┬─────┴┘   │         │
+              │          │          │          │  ┌┬─────┴─────┬┐
+              │          │          │          │┌>││   INIT    ││
+              │          │          │          ││ └┴─────┬─────┴┘
+       ┌┬─────┴─────┬┐   │          │          ││        |
+       ││Load ELE FW││─────────────>│          ││        │
+       └┴─────┬─────┴┘   |          |          |│        │
+              │          │   ┌┬─────┴─────┬┐   ││ ┌┬─────┴─────┬┐
+              │          │   ├│Auth ELE FW││   ││ ││Start CM FW││
+              │          │   └┴─────┬─────┴┘   ││ └┴─────┬─────┴┘
+              |          |          |          |│        |
+       ┌┬─────┴─────┬┐   │          │          ││        │
+       ││Load CM  FW││   │          |          ││        │
+       └┴─────┬─────┴┘   │          │          ││        │
+              │          │   ┌┬─────┴─────┬┐   ││        │
+              ├─────────────>├│Auth CM FW ││   ││        │
+              │          │   └┴─────┬─────┴┘   ││        │
+              |          │          │          ││        │
+              │          │          |───────────┘        │
+       ┌┬─────┴─────┬┐   │          │          │         │
+       ││Load  CA FW││   │          │          │         │
+       └┴─────┬─────┴┘   │          │          │         │
+              │          │   ┌┬─────┴─────┬┐   │         │
+              ├─────────────>├│Auth CA  FW││   │         │
+              │          │   └┴─────┬─────┴┘   │         │
+       ┌┬─────┴─────┬┐   │          │          │         │
+       ││Start CA FW││   │          |          │         │
+       └┴─────┬─────┴┘   │          │          │         │
+              |          │          │          │         │
+              |          │          │          │         │
+              |          │          │          │         │
+
+More details on the boot flow can be found in respective Security Reference
+Manual (SRM).
+
+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 (starting from v3.1.0):
+
+  .. code-block:: console
+
+     $ ./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:
+
+.. code-block:: text
+
+                            ┌─────────┐
+                            │   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 (starting
+  from v3.1.0):
+
+  .. code-block:: console
+
+     $ ./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:
+
+.. code-block:: text
+
+                            ┌─────────┐
+                            │   CA    │
+                            └────┬────┘
+                                 │
+                                 │
+        ┌───────────────┬────────┴────────┬───────────────┐
+        │               │                 │               │
+        │               │                 │               │
+        v               v                 v               v
+   ┌────────┐       ┌────────┐       ┌────────┐       ┌────────┐
+   │  SRK1  │       │  SRK2  │       │  SRK3  │       │  SRK4  │
+   └────┬───┘       └───┬────┘       └────┬───┘       └───┬────┘
+        │               │                 │               │
+        v               v                 v               v
+   ┌────────┐       ┌────────┐       ┌────────┐       ┌────────┐
+   │  SGK1  │       │  SGK2  │       │  SGK3  │       │  SGK4  │
+   └────────┘       └────────┘       └────────┘       └────────┘
+
+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]/SRK_HASH[255: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 to generate the SRK Table and its respective SRK
+Table Hash.
+
+- Generating SRK Table and SRK Hash in Linux 64-bit machines:
+  - In i.MX 8/8x family, the expected SRK HASH is of 512 bit.
+
+    .. code-block:: console
+
+       $ 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
+
+  - In i.MX 8ULP/9x, the expected SRK HASH is of 256 bit.
+
+    .. code-block:: console
+
+       $ cd ../crts/
+       $ ../linux64/bin/srktool -a -d sha256 -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
+
+    Regenerate the SRK HASH (SRK_1_2_3_4_fuse.bin) by using SHA256 with
+    SRK_1_2_3_4_table.bin:
+
+    .. code-block:: console
+
+       $ openssl dgst -binary -sha256 SRK_1_2_3_4_table.bin
+
+- Optionally users can check if the sha512sum/sha256sum of SRK_1_2_3_4_table
+  matches with the SRK_1_2_3_4_fuse.bin:
+
+  .. code-block:: console
+
+     $ 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
+
+.. note::
+
+   The commands above cannot be used as reference to program the SoC
+   SRK_HASH fuses.
+
+3 Known limitations
+-------------------
+
+- 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.
diff --git a/doc/imx/ahab/introduction_ahab.txt b/doc/imx/ahab/introduction_ahab.txt
new file mode 100644
index 00000000000..4a5b6f795c4
--- /dev/null
+++ b/doc/imx/ahab/introduction_ahab.txt
@@ -0,0 +1,445 @@
+          +=======================================================+
+          +       i.MX Secure and Encrypted Boot using AHAB       +
+          +=======================================================+
+
+1. Introduction
+----------------
+
+The i.MX 8/8x/8ULP/9x 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) in i.MX 8/8x, and Edgelock secure enclave (ELE)
+in i.MX 8ULP/9x are heavily involved in the secure boot process.
+
+Step-by-step guides are available under doc/imx/ahab/guides/ directory,
+users familiar with AHAB architecture and CST PKI tree generation should
+refer to these documents 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 [i.MX 8/8x] 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 [i.MX 8/8x] 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.1.3 [i.MX 8ULP/9x] The Edgelock secure enclave
+-------------------------------------
+
+EdgeLock™ Secure Enclave is the security subsystem based on a dedicated core
+(RISC-V) to manage security tasks with a tight control on security resources
+along with other enhancements.
+
+The secure enclave has a dedicate ROM which is responsible to initialize low
+level security features and to authenticate the secure enclave firmware
+previously loaded by the boot management core.
+
+The secure enclave firmware provides security services at run-time to different
+ domains of the SoC, one of these being the capability of authenticate images.
+
+The secure enclave firmware is signed and distributed by NXP and is always
+authenticated in OEM open and closed configuration, instructions to download
+this FW are available in the Linux BSP Release Notes.
+
+Details about Edgelock secure enclave can be found in the processors Security
+Reference Manual (SRM).
+
+NOTE: The terms Sentinel, S400, and EdgeLock secure enclave (ELE), and ELE
+are used interchangeably throughout the document.
+
+1.2 The image container
+------------------------
+
+Due to the new architecture, multiple firmwares and software are required to
+boot AHAB supporting 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 Security Subsystem FW (SECO/ELE 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.
+
+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/ahab/guides/ directory.
+
+1.4 The i.MX 8ULP/9x secure boot flow
+----------------------------------
+
+The secure boot sequence involves multiple cores booting up at same time and
+Edgelock secure enclave ensure authentication of any boot software being loaded.
+
+The diagram below illustrate the secure boot flow overview for dual boot
+scenario in i.MX 8ULP:
+
+
+    Cortex-M(CM)     │   Edgelock Secure   │    Cortex-A(CA)   │   uPower(uP)
+                     │    Enclave(ELE)     │                   │
+          │          │          │          │         │         │        │
+   ┌┬─────┴─────┬┐   │   ┌┬─────┴─────┬┐   │         │         │ ┌┬─────┴─────┬┐
+   ││   INIT    ││   │   ││   INIT    ││   │         │         │ ││   INIT    ││
+   └┴─────┬─────┴┘   │   └┴─────┬─────┴┘   │         │         │ └┴─────┬─────┴┘
+          │          │          │          │  ┌┬─────┴─────┬┐  │        │
+   ┌┬─────┴─────┬┐   │          │          │  ││Load CA FW ││ ┌──────┐  │
+   ││Load uP FW ││   │          │          │  └┴─────┬─────┴┘ ││     │  │
+   └┴─────┬─────┴┘   │          │          │         │        ││ ┌┬──v──┴─────┬┐
+          │          │   ┌┬─────┴─────┬┐   │┌────────┤        ││ ││Load &Start││
+          ├─────────────>├│Auth uP FW ││   ││        │        ││ ││   uP FW   ││
+          │          │   └┴─────┬─────┴┘   ││        │        ││ └┴───────────┴┘
+   ┌┬─────┴─────┬┐   │          │          ││        │        ││
+   ││Load CM  FW││   │          ├────────────────────┼────────┘│
+   └┴─────┬─────┴┘   │          │          ││        │         │
+          │          │   ┌┬─────┴─────┬┐   ││        │         │
+          ├─────────────>├│Auth CM FW ││   ││ ┌┬─────┴─────┬┐  │
+          │          │   └┴─────┬─────┴┘   ││ ││Start CA FW││  │
+   ┌┬─────┴─────┬┐   │          │          ││ └┴─────┬─────┴┘  │
+   ││Load ELE FW││   │          │          ││        │         │
+   └┴─────┬─────┴┘   │          │          ││        │         │
+          │          │   ┌┬─────┴─────┬┐   ││        │         │
+          ├─────────────>├│Auth ELE FW││   ││        │         │
+          │          │   └┴─────┬─────┴┘   ││ ┌┬─────┴─────┬┐  │
+   ┌┬─────┴─────┬┐   │          │          ││ ││ Load SPL  ││  │
+   ││Start CM FW││   │          │          ││ └┴─────┬─────┴┘  │
+   └┴─────┬─────┴┘   │          │          ││        │         │
+          │          │   ┌┬─────┴─────┬┐   ││   ┌────┤         │
+          │          │   ││Auth CA FW │┤<───┘   │    │         │
+          │          │   └┴─────┬─────┴┘   │    │    │         │
+          │          │          │          │    │    │         │
+          │          │   ┌┬─────┴─────┬┐   │    │    │         │
+          │          │   ││ Auth SPL  │┤<───────┘    │         │
+          │          │   └┴─────┬─────┴┘   │         │         │
+          │          │          ├─────────────────┐  │         │
+          │          │          │          │      │  │         │
+          │          │          │          │  ┌┬──v──v─────┬┐  │
+          │          │          │          │  ││  Run SPL  ││  │
+          │          │          │          │  └┴───────────┴┘  │
+
+
+The diagram below illustrate the secure boot flow overview for single boot
+scenario in i.MX 9x:
+
+
+    Cortex-A(CA)     │   Edgelock Secure   │    Cortex-M(CM)
+                     │    Enclave(ELE)     │
+          │          │          │          │         │
+   ┌┬─────┴─────┬┐   │   ┌┬─────┴─────┬┐   │         │
+   ││   INIT    ││   │   ││   INIT    ││   │         │
+   └┴─────┬─────┴┘   │   └┴─────┬─────┴┘   │         │
+          │          │          │          │  ┌┬─────┴─────┬┐
+          │          │          │          │┌>││   INIT    ││
+          │          │          │          ││ └┴─────┬─────┴┘
+   ┌┬─────┴─────┬┐   │          │          ││        |
+   ││Load ELE FW││─────────────>│          ││        │
+   └┴─────┬─────┴┘   |          |          |│        |
+          │          │   ┌┬─────┴─────┬┐   ││ ┌┬─────┴─────┬┐
+          │          │   ├│Auth ELE FW││   ││ ││Start CM FW││
+          │          │   └┴─────┬─────┴┘   ││ └┴─────┬─────┴┘
+          |          |          |          |│        |
+   ┌┬─────┴─────┬┐   │          │          ││        │
+   ││Load CM  FW││   │          |          ││        │
+   └┴─────┬─────┴┘   │          │          ││        │
+          │          │   ┌┬─────┴─────┬┐   ││        │
+          ├─────────────>├│Auth CM FW ││   ││        │
+          │          │   └┴─────┬─────┴┘   ││        │
+          |          │          │          ││        │
+          │          │          |───────────┘        │
+   ┌┬─────┴─────┬┐   │          │          │         │
+   ││Load  CA FW││   │          │          │         │
+   └┴─────┬─────┴┘   │          │          │         │
+          │          │   ┌┬─────┴─────┬┐   │         │
+          ├─────────────>├│Auth CA  FW││   │         │
+          │          │   └┴─────┬─────┴┘   │         │
+   ┌┬─────┴─────┬┐   │          │          │         │
+   ││Start CA FW││   │          |          │         │
+   └┴─────┬─────┴┘   │          │          │         │
+          |          │          │          │         │
+          |          │          │          │         │
+          |          │          │          │         │
+
+More details on the boot flow can be found in respective Security Reference
+Manual (SRM).
+
+
+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 (starting from 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 (starting
+from 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  │
+    └────────┘       └────────┘       └────────┘       └────────┘
+
+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]/SRK_HASH[255: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 to generate the SRK Table and its respective SRK
+Table Hash.
+
+- Generating SRK Table and SRK Hash in Linux 64-bit machines:
+  - In i.MX 8/8x family, the expected SRK HASH is of 512 bit.
+    $ 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
+
+  - In i.MX 8ULP/9x, the expected SRK HASH is of 256 bit.
+    $ cd ../crts/
+    $ ../linux64/bin/srktool -a -d sha256 -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
+
+    Regenerate the SRK HASH (SRK_1_2_3_4_fuse.bin) by using SHA256 with
+    SRK_1_2_3_4_table.bin.
+    $ openssl dgst -binary -sha256 SRK_1_2_3_4_table.bin
+
+
+
+- Optionally users can check if the sha512sum/sha256sum 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
+
+NOTE: The commands above cannot be used as reference to program the SoC
+      SRK_HASH fuses.
+
+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/ahab/guides/
+directory.
+
+3 Known limitations
+----------------------------------------
+
+- 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.
diff --git a/doc/imx/index.rst b/doc/imx/index.rst
new file mode 100644
index 00000000000..cc5f427de92
--- /dev/null
+++ b/doc/imx/index.rst
@@ -0,0 +1,13 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+i.MX AHAB secure boot
+======================
+
+This section provides documentation for the NXP i.MX AHAB (Advanced
+High Assurance Boot) secure boot mechanisms, covering the AHAB
+architecture introduction and the i.MX93 secure boot guide.
+
+.. toctree::
+   :maxdepth: 2
+
+   ahab/introduction_ahab

-- 
2.55.0