     +=========================================================+
     +              Extend RoT guide using AHAB                +
     +=========================================================+

1. Extension of Root of Trust
------------------------------

The Root of Trust established by enabling secure boot in boot image can be
extended by authenticating the OS by an authentic uboot image. Following
sections describes ways to build and sign an OS container.

2. Signing the OS container
-----------------------------------

The OS container needs to be prepared with proper container header in order to
sign the OS image. Using imx-mkimage tool provided by NXP, the OS image can be
wrapped into a container format.

Note: Signing OS container is not mandatory. If you do not plan to authenticate
 the kernel image, you can disable this behavior by setting sec_boot=no in
U-Boot environment variable.

Note: OS image can also be authenticated by running a U-Boot command:

  => auth_cntr <Container address>

2.1 Prepare the OS container image
-----------------------------------

Note: As the final OS container image is also generated as flash.bin, make sure
 to save any other flash.bin image previously generated.

- Build the kernel image for the target

  $ make SOC=<SoC name> flash_kernel
  $ mv <SoC name>/flash.bin <SoC name>/flash_os.bin

Note: flash.bin has been renamed to flash_os.bin for clarity.

If the make command ends successfully, the end of the result should look
like:

  CST: CONTAINER 0 offset: 0x0
  CST: CONTAINER 0: Signature Block: offset is at 0x110
  DONE.
  Note: Please copy image to offset: IVT_OFFSET + IMAGE_OFFSET

Keep a note of the offsets above to be used with CST/CSF

2.2 Creating the CSF description file for OS container image
-------------------------------------------------------------

CSF examples are available under doc/imx/hab/ahab/csf_examples/ directory.

The csf_linux_img.txt file example should be updated with the offset values
of the 2.1 chapter and the path to the flash_os.bin file. It is the last
part of the file:

  [Authenticate Data]
  # Binary to be signed generated by mkimage
  File = "flash_os.bin"
  # Offsets = Container header  Signature block (printed out by mkimage)
  Offsets   = 0x0             0x110

2.3 Authenticating container image
-----------------------------------

Now CST can be used to sign the OS image using the previously created
csf_linux_img.txt Commands Sequence File:

  $ cd <work>
  $ ./release/linux64/bin/cst -i csf_linux_img.txt -o os_cntr_signed.bin

2.4 Copy OS container
----------------------

- For i.MX 8 QXP/QM/DXL

Mount the SD Card:

  $ sudo mount /dev/sdX1 partition

Copy the OS signed image on the SD Card:

  $ sudo cp os_cntr_signed.bin /media/UserID/Boot\ <soc>

Finally:

  $ sudo umount partition

- For i.MX 8ULP/9x

Goto fastboot mode from uboot:

  => fastboot auto
  auto usb 0

Use UUU to download signed OS container:

  $ sudo ./uuu ucmd setenv fastboot_buffer ${cntr_addr}
  $ sudo ./uuu download -i os_cntr_signed.bin
  $ sudo ./uuu FB: ucmd fatwrite mmc 0:1 ${fastboot_buffer} os_cntr_signed.bin <size in hex>
