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