new file mode 100644
@@ -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