doc: ahab: Add encrypted boot documentation for i.MX8/8x devices

Add AHAB encrypted boot documentation for i.MX8/8x family devices
covering the following topics:

- How to encrypt and sign the 2nd container in flash.bin image.
- How to encrypt and sign a standalone container image.

Include a CSF example to encrypt 2nd container in flash.bin image.

Reviewed-by: Fabio Estevam <festevam@gmail.com>
Signed-off-by: Catia Han <yaqian.han@nxp.com>
Signed-off-by: Breno Lima <breno.lima@nxp.com>
Signed-off-by: Peng Fan <peng.fan@nxp.com>

2 files changed, 320 insertions, 0 deletions

diff --git a/doc/imx/ahab/csf_examples/csf_enc_boot_image.txt b/doc/imx/ahab/csf_examples/csf_enc_boot_image.txt
new file mode 100644
index 0000000..6c70db6
--- /dev/null
+++ b/doc/imx/ahab/csf_examples/csf_enc_boot_image.txt
@@ -0,0 +1,27 @@
+[Header]
+Target = AHAB
+Version = 1.0
+
+[Install SRK]
+# SRK table generated by srktool
+File = "./release/crts/SRK_1_2_3_4_table.bin"
+# Public key certificate in PEM format
+Source = "./release/crts/SRK1_sha384_secp384r1_v3_usr_crt.pem"
+# Index of the public key certificate within the SRK table (0 .. 3)
+Source index = 0
+# Type of SRK set (NXP or OEM)
+Source set = OEM
+# bitmask of the revoked SRKs
+Revocations = 0x0
+
+[Authenticate Data]
+# Binary to be signed generated by mkimage
+File = "flash.bin"
+# Offsets = Container header  Signature block (printed out by mkimage)
+Offsets   = 0x400             0x590
+
+[Install Secret Key]
+Key = "dek.bin"
+Key Length = 128
+#Key Identifier = 0x1234CAFE
+Image Indexes = 0xFFFFFFFE
diff --git a/doc/imx/ahab/guides/mx8_mx8x_encrypted_boot.txt b/doc/imx/ahab/guides/mx8_mx8x_encrypted_boot.txt
new file mode 100644
index 0000000..dfea4c8
--- /dev/null
+++ b/doc/imx/ahab/guides/mx8_mx8x_encrypted_boot.txt
@@ -0,0 +1,293 @@
+         +=========================================================+
+         +      i.MX 8, i.MX 8X Encrypted Boot guide using AHAB    +
+         +=========================================================+
+
+1. AHAB Encrypted Boot process
+-------------------------------
+
+This document describes a step-by-step procedure on how to encrypt and sign a
+bootloader image for i.MX8/8x family devices. It is assumed that the reader
+is familiar with basic AHAB concepts and has already closed the device,
+step-by-step procedure can be found in mx8_mx8x_secure_boot.txt and
+mx8_mx8x_spl_secure_boot.txt guides.
+
+The steps described in this document were based in i.MX8QM device, the same
+concept can be applied to others processors in i.MX8/8X family devices.
+
+1.1 Understanding the encrypted image signature block
+------------------------------------------------------
+
+As described in mx8_mx8x_secure_boot.txt guide a single binary is used to boot
+the device. The imx-mkimage tool combines all the input images in a container
+structure, generating a flash.bin binary.
+
+AHAB is able to decrypt image containers by calling SECO authentication
+functions, the image must be encrypted by CST and the resulting DEK (Data
+Encryption Key) must be encapsulated and included into the container 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 +------------------------+
+                |   |        DEK Blob        |
+                +---+------------------------+
+
+1.1.1 Understanding and generating the DEK blob
+------------------------------------------------
+
+The encrypted boot image requires a DEK blob on each time AHAB is used to
+decrypt an image. The DEK blob is used as a security layer to wrap and store
+the DEK off-chip using the OTPMK which is unique per device.
+
+On i.MX8/8x devices the DEK blob is generated using the SECO API, the following
+funtion is available in U-Boot and can be executed through dek_blob command:
+
+- sc_seco_gen_key_blob(sc_ipc_t ipc, uint32_t id, sc_faddr_t load_addr,
+		       sc_faddr_t export_addr, uint16_t max_size)
+
+Details in API usage can be found in SCFW API guide [1].
+
+1.2 Enabling the encrypted boot support in U-Boot
+--------------------------------------------------
+
+For deploying an encrypted boot image additional U-Boot tools are needed,
+please be sure to have the following features enabled, this can be achieved
+by following one of the methods below:
+
+- Defconfig:
+
+  CONFIG_AHAB_BOOT=y
+  CONFIG_CMD_DEKBLOB=y
+  CONFIG_IMX_SECO_DEK_ENCAP=y
+  CONFIG_FAT_WRITE=y
+
+- Kconfig:
+
+  ARM architecture -> Support i.MX8 AHAB features
+  ARM architecture -> Support the 'dek_blob' command
+  File systems -> Enable FAT filesystem support-> Enable FAT filesystem
+  write support
+
+1.3 Enabling the encrypted boot support in CST
+-----------------------------------------------
+
+The encryption feature is not enabled by default in Code Signing tools (CST).
+The CST backend must be recompiled, execute the following commands to enable
+encryption support in CST:
+
+  $ sudo apt-get install libssl-dev openssl
+  $ cd <CST install directory>/code/back_end/src
+  $ gcc -o cst_encrypted -I ../hdr -L ../../../linux64/lib *.c
+    -lfrontend -lcrypto
+  $ cp cst_encrypted ../../../linux64/bin/
+
+1.4 Preparing the image container
+----------------------------------
+
+The container generation is explained in and mx8_mx8x_secure_boot.txt and
+mx8_mx8x_spl_secure_boot.txt guides. This document is based in imx-mkimage
+flash target (2 containers in flash.bin).
+
+- Assembly flash.bin binary:
+
+  $ make SOC=<SoC Name> flash
+
+The mkimage log is used during the encrypted boot procedure to create the
+Command Sequence File (CSF):
+
+  CST: CONTAINER 0 offset: 0x400
+  CST: CONTAINER 0: Signature Block: offset is at 0x590
+  DONE.
+  Note: Please copy image to offset: IVT_OFFSET + IMAGE_OFFSET
+
+1.6 Creating the CSF description to encrypt the 2nd container
+--------------------------------------------------------------
+
+The csf_enc_boot_image.txt available under ahab/csf_examples/ can be used as
+example for encrypting the flash.bin binary, the main change is the Install
+Secret Key command that must be added after Authenticate Data command.
+
+  [Install Secret Key]
+  Key = "dek.bin"
+  Key Length = 128
+  #Key Identifier = 0x1234CAFE
+  Image Indexes = 0xFFFFFFFE
+
+By default all images are encrypted and image indexes parameter can be used
+to mask the images indexes that must be encrypted, on this example only the
+2nd container will be encrypted.
+
+Optionally users can provide a key identifier that must match the value
+provided during the blob generation, by default its value is zero.
+
+1.7 Encrypting the 2nd container
+---------------------------------
+
+The image is encrypted using the Code Signing Tool. The tool generates the
+encrypted image and a random dek.bin file.
+
+- Encrypt flash.bin binary:
+
+  $ ./cst_encrypted -i csf_enc_boot_image.txt -o enc_flash.bin
+   The DEK BLOB must be inserted at offset 0x7c0 (its expected size is 72 bytes)
+   CSF Processed successfully and signed image available in enc_boot_image.bin
+
+The output log will be used in a later step to insert the DEK blob into the
+signature block.
+
+1.8 Generating the DEK Blob
+----------------------------
+
+The DEK must be encapsulated into a CAAM blob so it can be included into the
+final encrypted binary. The U-Boot provides a tool called dek_blob which is
+calling the SECO blob encapsulation API.
+
+Copy the dek.bin in SDCard FAT partition and run the following commands from
+U-Boot prompt:
+
+  => mmc list
+     FSL_SDHC: 1 (SD)
+     FSL_SDHC: 2
+  => fatload mmc 1:1 0x80280000 dek.bin
+  => dek_blob 0x80280000 0x80280100 128
+  => fatwrite mmc 1:1 0x80280100 dek_blob.bin 0x48
+
+In host PC copy the generated dek_blob.bin to the CST directory.
+
+1.9 Assembling the encrypted image
+-----------------------------------
+
+The DEK blob generated in the step above have to be inserted into the container
+signature block.
+
+The CSF log is used to determine the DEK Blob offset:
+
+  The DEK BLOB must be inserted at offset 0x7c0 (its expected size is 72 bytes)
+  CSF Processed successfully and signed image available in enc_boot_image.bin
+
+- Insert DEK Blob into container signature block:
+
+  $ dd if=dek_blob.bin of=enc_flash.bin bs=1 seek=$((0x7c0)) conv=notrunc
+
+1.10 Flashing the encrypted boot image
+---------------------------------------
+
+The same offset is used for encrypted boot images, in case booting from
+eMMC/SDCard the offset is 32K.
+
+- Flash encrypted image in SDCard:
+
+  $ sudo dd if=enc_flash.bin of=/dev/sd<x> bs=1K seek=32 && sync
+
+2.0 Encrypting a standalone container
+--------------------------------------
+
+CST is also able to encrypt additional images containers, the steps documented
+in this section are based in OS container but can be also applied to SPL
+targets and 3rd containers.
+
+2.1 Creating the OS container
+------------------------------
+
+As explained in mx8_mx8x_secure_boot.txt guide the imx-mkimage tool is used to
+generate an image container for OS images, the mkimage log is used during the
+encrypted boot procedure to create the Command Sequence File (CSF).
+
+- Creating OS container:
+
+  $ make SOC=<SoC Name> flash_kernel
+   ...
+   CST: CONTAINER 0 offset: 0x0
+   CST: CONTAINER 0: Signature Block: offset is at 0x110
+
+2.2 Creating the CSF description file for standalone container
+---------------------------------------------------------------
+
+The Image Indexes parameter is used to mask the images that are encrypted by
+CST, as a single container is used for OS images the Image Indexes command can
+be commented or set to 0xFFFFFFFF.
+
+  [Install Secret Key]
+  Key = "dek_os.bin"
+  Key Length = 128
+  #Key Identifier = 0x1234CAFE
+  Image Indexes = 0xFFFFFFFF
+
+2.3 Encrypting the standalone container
+----------------------------------------
+
+As explained in section 1.7 the CST generates the encrypted image and a random
+dek.bin file.
+
+- Encrypt the standalone container:
+
+  $ ./cst_encrypted -i csf_linux_img.txt -o enc_flash_os.bin
+   The DEK BLOB must be inserted at offset 0x340 (its expected size is 72 bytes)
+   CSF Processed successfully and signed image available in enc_flash_os.bin
+
+The output log will be used in a later step to insert the DEK blob into the
+signature block.
+
+2.4 Generating the DEK Blob for standalone container
+----------------------------------------------------
+
+Similar to section 1.8 the DEK must be encapsulated into a CAAM blob so it can
+be included into the final encrypted binary.
+
+Copy the dek_os.bin in SDCard FAT partition and run the following commands from
+U-Boot prompt:
+
+  => mmc list
+     FSL_SDHC: 1 (SD)
+     FSL_SDHC: 2
+  => fatload mmc 1:1 0x80280000 dek_os.bin
+  => dek_blob 0x80280000 0x80280100 128
+  => fatwrite mmc 1:1 0x80280100 dek_blob_os.bin 0x48
+
+In host PC copy the generated dek_blob_os.bin to the CST directory.
+
+2.5 Assembling the encrypted image
+-----------------------------------
+
+The DEK blob generated in the step above have to be inserted into the container
+signature block.
+
+The CSF log is used to determine the DEK Blob offset:
+
+   The DEK BLOB must be inserted at offset 0x340 (its expected size is 72 bytes)
+   CSF Processed successfully and signed image available in enc_flash_os.bin
+
+- Insert DEK Blob into container signature block:
+
+  $ dd if=dek_blob_os.bin of=enc_flash_os.bin bs=1 seek=$((0x340)) conv=notrunc
+
+2.6 Copy encrypted image to SDCard
+-----------------------------------
+
+The encrypted container can be copied to SDCard FAT partition, please note
+that U-Boot requires signed and encrypted containers to be named as
+os_cntr_signed.bin.
+
+  $ sudo cp enc_flash_os.bin /media/UserID/Boot\ imx8/os_cntr_signed.bin
+
+References:
+[1] SCFW API guide: "System Controller Firmware API Reference Guide - Rev 1.5"