          +=======================================================+
          +         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

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/hab/ahab/guides/
directory.