doc: imx: habv4: Add HABv4 introduction

The HABv4 is supported in i.MX50, i.MX53, i.MX6, i.MX7,
series and i.MX 8M, i.MX8MM devices.

Add an introductory document containing the following topics:

- HABv4 Introduction
- HABv4 Secure Boot
- HABv4 Encrypted Boot
- HAB PKI tree generation
- HAB Fast Authentication PKI tree generation
- SRK Table and SRK Hash generation

Reviewed-by: Ye Li <ye.li@nxp.com>
Reviewed-by: Utkarsh Gupta <utkarsh.gupta@nxp.com>
Signed-off-by: Breno Lima <breno.lima@nxp.com>

1 files changed, 262 insertions, 0 deletions

diff --git a/doc/imx/habv4/introduction_habv4.txt b/doc/imx/habv4/introduction_habv4.txt
new file mode 100644
index 0000000000..25711bbe95
--- /dev/null
+++ b/doc/imx/habv4/introduction_habv4.txt
@@ -0,0 +1,262 @@
+          +=======================================================+
+          +     i.MX Secure and Encrypted Boot using HABv4        +
+          +=======================================================+
+
+1. Introduction
+----------------
+
+The i.MX family of applications processors provides the High Assurance Boot
+(HAB) feature in the on-chip ROM. The ROM is responsible for loading the
+initial program image (U-Boot) from the boot media and HAB enables the ROM
+to authenticate and/or decrypt the program image by using cryptography
+operations.
+
+This feature is supported in i.MX 50, i.MX 53, i.MX 6, i.MX 7 series and
+ i.MX 8M, i.MX 8MM devices.
+
+Step-by-step guides are available under doc/imx/habv4/guides/ directory,
+users familiar with HAB and CST PKI tree generation should refer to these
+documents instead.
+
+1.1 The HABv4 Secure Boot Architecture
+---------------------------------------
+
+The HABv4 secure boot feature uses 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 HAB authentication is based on public key cryptography using the RSA
+algorithm in which image data is signed offline using a series of 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 CSF
+binary and the SRK Hash is programmed in the SoC fuses for establishing the
+root of trust.
+
+The diagram below illustrate the secure boot process overview:
+
+          Host PC + CST                             i.MX + HAB
+          +----------+                             +----------+
+     ---> |  U-Boot  |                             | Compare  |
+     |    +----------+                             +----------+
+     |          |                                     ^    ^
+     |          v                         Reference  /      \  Generated
+     |    +----------+                      Hash    /        \   Hash
+     |    |   Hash   |  Private                    /          \
+     |    +----------+    Key                     /            \
+     |          |          |                +----------+  +----------+
+     |          v          |                |  Verify  |  |   Hash   |
+     |    +----------+     |                +----------+  +----------+
+     |    |   Sign   |  <---      SRK            ^            ^
+     |    +----------+            HASH            \          /
+     |          |                  |          CSF  \        /   U-Boot
+     |          v                  v                \      /
+     |    +----------+        +----------+        +----------+
+     |    |  U-Boot  |        |          |        |  U-Boot  |
+     ---> |     +    | -----> |   i.MX   | -----> |     +    |
+          |    CSF   |        |          |        |    CSF   |
+          +----------+        +----------+        +----------+
+
+The U-Boot image to be programmed into the boot media needs to be properly
+constructed i.e. it must contain a proper Command Sequence File (CSF).
+
+The CSF is a binary data structure interpreted by the HAB to guide
+authentication process, this is generated by the Code Signing Tool[1].
+The CSF structure contains the commands, SRK table, signatures and
+certificates.
+
+Details about the Secure Boot and Code Signing Tool (CST) can be found in
+the application note AN4581[2] and in the secure boot guides.
+
+1.2 The HABv4 Encrypted Boot Architecture
+------------------------------------------
+
+The HAB Encrypted Boot feature available in CAAM supported devices adds an
+extra security operation to the bootloading sequence. It uses cryptographic
+techniques (AES-CCM) to obscure the U-Boot data, so it cannot be seen or used
+by unauthorized users. This mechanism protects the U-Boot code residing on
+flash or external memory and also ensures that the final image is unique
+per device.
+
+The process can be divided into two protection mechanisms. The first mechanism
+is the bootloader code encryption which provides data confidentiality and the
+second mechanism is the digital signature, which authenticates the encrypted
+image.
+
+Keep in mind that the encrypted boot makes use of both mechanisms whatever the
+order is (sign and then encrypt, or encrypt and then sign), both operations
+can be applied on the same region with exception of the U-Boot Header (IVT,
+boot data and DCD) which can only be signed, not encrypted.
+
+The diagram below illustrate the encrypted boot process overview:
+
+     Host PC + CST                                      i.MX + HAB
+     +------------+                                  +--------------+
+     |   U-Boot   |                                  |    U-Boot    |
+     +------------+                                  +--------------+
+            |                                                ^
+            |                                                |
+            v         DEK                            +--------------+
+     +------------+    |                       ----> |    Decrypt   |
+     |   Encrypt  | <---                       |     +--------------+
+     +------------+                        DEK |             ^
+            |                                  |             |
+            |       Private                    |             |
+            v         Key                  +------+   +--------------+
+     +------------+    |                   | CAAM |   | Authenticate |
+     |    Sign    | <---                   +------+   +--------------+
+     +------------+            DEK             ^             ^
+            |                + OTPMK       DEK  \           /  U-Boot
+            |                   |          Blob  \         /   + CSF
+            v                   v                 \       /
+     +------------+       +----------+          +------------+
+     | Enc U-Boot |       |          |          | Enc U-Boot |
+     |   + CSF    | ----> |   i.MX   | -------> |   + CSF    |
+     | + DEK Blob |       |          |          | + DEK Blob |
+     +------------+       +----------+          +------------+
+            ^                   |
+            |                   |
+            ---------------------
+                   DEK Blob
+                    (CAAM)
+
+The Code Signing Tool automatically generates a random AES Data Encryption Key
+(DEK) when encrypting an image. This key is used in both encrypt and decrypt
+operations and should be present in the final image structure encapsulated
+by a CAAM blob.
+
+The OTP Master Key (OTPMK) is used to encrypt and wrap the DEK in a blob
+structure. The OTPMK is unique per device and can be accessed by CAAM only.
+To further add to the security of the DEK, the blob is decapsulated and
+decrypted inside a secure memory partition that can only be accessed by CAAM.
+
+During the design of encrypted boot using DEK blob, it is necessary to inhibit
+any modification or replacement of DEK blob with a counterfeit one allowing
+execution of malicious code. The PRIBLOB setting in CAAM allows secure boot
+software to have its own private blobs that cannot be decapsulated or
+encapsulated by any other user code, including any software running in trusted
+mode.
+
+Details about DEK Blob generation and PRIBLOB setting can be found in the
+encrypted boot guide and application note AN12056[3] .
+
+2. Generating a PKI tree
+-------------------------
+
+The first step is to generate the private keys and public keys certificates.
+The HAB architecture is based in a Public Key Infrastructure (PKI) tree.
+
+The Code Signing Tools package contains an OpenSSL based key generation script
+under keys/ directory. The hab4_pki_tree.sh script is able to generate a PKI
+tree containing up to 4 Super Root Keys (SRK) as well as their subordinated
+IMG and CSF keys.
+
+A new PKI tree can be generated by following the example below:
+
+- Generating 2048-bit PKI tree on CST v3.1.0:
+
+  $ ./hab4_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)?: n
+  Enter key length in bits for PKI tree: 2048
+  Enter PKI tree duration (years): 5
+  How many Super Root Keys should be generated? 4
+  Do you want the SRK certificates to have the CA flag set? (y/n)?: y
+
+The diagram below illustrate the PKI tree:
+
+                                +---------+
+                                |   CA    |
+                                +---------+
+                                     |
+                                     |
+            ---------------------------------------------------
+            |               |                 |               |
+            |               |                 |               |
+            v               v                 v               v
+       +--------+       +--------+       +--------+       +--------+
+       |  SRK1  |       |  SRK2  |       |  SRK3  |       |  SRK4  |
+       +--------+       +--------+       +--------+       +--------+
+         /    \           /    \           /    \           /    \
+        v      v         v      v         v      v         v      v
+     +----+  +----+   +----+  +----+   +----+  +----+   +----+  +----+
+     |CSF1|  |IMG1|   |CSF2|  |IMG2|   |CSF3|  |IMG3|   |CSF4|  |IMG4|
+     +----+  +----+   +----+  +----+   +----+  +----+   +----+  +----+
+
+After running the script users can check the private keys under keys/ directory
+and their respective X.509v3 public key certificates under crts/ directory.
+Those files will be used during the signing and authentication process.
+
+2.1 Generating a fast authentication PKI tree
+----------------------------------------------
+
+Starting in HAB v4.1.2 users can use a single SRK key to authenticate the both
+CSF and IMG contents. This reduces the number of key pair authentications that
+must occur during the ROM/HAB boot stage, thus providing a faster boot process.
+
+The script hab4_pki_tree.sh is also able to generate a Public Key Infrastructure
+(PKI) tree which only contains SRK Keys, users should not set the CA flag when
+generating the SRK certificates.
+
+- Generating 2048-bit fast authentication PKI tree on CST v3.1.0:
+
+  $ ./hab4_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)?: n
+  Enter key length in bits for PKI tree: 2048
+  Enter PKI tree duration (years): 5
+  How many Super Root Keys should be generated? 4
+  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.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 HAB architecture, the SRK Table is included in the CSF binary and the
+SRK Hash is programmed in the SoC SRK_HASH[255:0] fuses.
+
+On the target device during the authentication process the HAB code verify the
+SRK Table against the SoC SRK_HASH fuses, in case the verification success the
+root of trust is established and the HAB 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:
+
+  $ ../linux64/bin/srktool -h 4 -t SRK_1_2_3_4_table.bin -e \
+	SRK_1_2_3_4_fuse.bin -d sha256 -c \
+	SRK1_sha256_2048_65537_v3_ca_crt.pem,\
+	SRK2_sha256_2048_65537_v3_ca_crt.pem,\
+	SRK3_sha256_2048_65537_v3_ca_crt.pem,\
+	SRK4_sha256_2048_65537_v3_ca_crt.pem
+
+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 HAB guides available under doc/imx/habv4/guides/
+directory.
+
+References:
+[1] CST: i.MX High Assurance Boot Reference Code Signing Tool.
+[2] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using
+ HABv4" - Rev 2.
+[3] AN12056: "Encrypted Boot on HABv4 and CAAM Enabled Devices" - Rev. 1