Eric Lee / smarc-uboot

Download as
Browse Code ยป

Commit cbc4b0418cddb577002305112399f0d869087c88

Authored by Breno Matheus Lima
Committed by Stefano Babic
1 parent 8a23fc9c94
Exists in smarc_8mq_lf_v2020.04 and in 11 other branches 8qm-imx_v2020.04_5.4.70_2.3.0, emb_lf_v2022.04, pitx_8mp_lf_v2020.04, smarc-8m-android-10.0.0_2.6.0, smarc-8m-android-11.0.0_2.0.0, smarc-8mp-android-11.0.0_2.0.0, smarc_8m-imx_v2019.04_4.19.35_1.1.0, smarc_8mm-imx_v2019.04_4.19.35_1.1.0, smarc_8mm-imx_v2020.04_5.4.24_2.1.0, smarc_8mp_lf_v2020.04, smarc_8mq-imx_v2020.04_5.4.24_2.1.0

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>

Showing 1 changed file with 262 additions and 0 deletions Side-by-side Diff

doc/imx/habv4/introduction_habv4.txt
Diff comments   View file @ cbc4b04
  1 + +=======================================================+
  2 + + i.MX Secure and Encrypted Boot using HABv4 +
  3 + +=======================================================+
  4 +
  5 +1. Introduction
  6 +----------------
  7 +
  8 +The i.MX family of applications processors provides the High Assurance Boot
  9 +(HAB) feature in the on-chip ROM. The ROM is responsible for loading the
  10 +initial program image (U-Boot) from the boot media and HAB enables the ROM
  11 +to authenticate and/or decrypt the program image by using cryptography
  12 +operations.
  13 +
  14 +This feature is supported in i.MX 50, i.MX 53, i.MX 6, i.MX 7 series and
  15 + i.MX 8M, i.MX 8MM devices.
  16 +
  17 +Step-by-step guides are available under doc/imx/habv4/guides/ directory,
  18 +users familiar with HAB and CST PKI tree generation should refer to these
  19 +documents instead.
  20 +
  21 +1.1 The HABv4 Secure Boot Architecture
  22 +---------------------------------------
  23 +
  24 +The HABv4 secure boot feature uses digital signatures to prevent unauthorized
  25 +software execution during the device boot sequence. In case a malware takes
  26 +control of the boot sequence, sensitive data, services and network can be
  27 +impacted.
  28 +
  29 +The HAB authentication is based on public key cryptography using the RSA
  30 +algorithm in which image data is signed offline using a series of private
  31 +keys. The resulting signed image data is then verified on the i.MX processor
  32 +using the corresponding public keys. The public keys are included in the CSF
  33 +binary and the SRK Hash is programmed in the SoC fuses for establishing the
  34 +root of trust.
  35 +
  36 +The diagram below illustrate the secure boot process overview:
  37 +
  38 + Host PC + CST i.MX + HAB
  39 + +----------+ +----------+
  40 + ---> | U-Boot | | Compare |
  41 + | +----------+ +----------+
  42 + | | ^ ^
  43 + | v Reference / \ Generated
  44 + | +----------+ Hash / \ Hash
  45 + | | Hash | Private / \
  46 + | +----------+ Key / \
  47 + | | | +----------+ +----------+
  48 + | v | | Verify | | Hash |
  49 + | +----------+ | +----------+ +----------+
  50 + | | Sign | <--- SRK ^ ^
  51 + | +----------+ HASH \ /
  52 + | | | CSF \ / U-Boot
  53 + | v v \ /
  54 + | +----------+ +----------+ +----------+
  55 + | | U-Boot | | | | U-Boot |
  56 + ---> | + | -----> | i.MX | -----> | + |
  57 + | CSF | | | | CSF |
  58 + +----------+ +----------+ +----------+
  59 +
  60 +The U-Boot image to be programmed into the boot media needs to be properly
  61 +constructed i.e. it must contain a proper Command Sequence File (CSF).
  62 +
  63 +The CSF is a binary data structure interpreted by the HAB to guide
  64 +authentication process, this is generated by the Code Signing Tool[1].
  65 +The CSF structure contains the commands, SRK table, signatures and
  66 +certificates.
  67 +
  68 +Details about the Secure Boot and Code Signing Tool (CST) can be found in
  69 +the application note AN4581[2] and in the secure boot guides.
  70 +
  71 +1.2 The HABv4 Encrypted Boot Architecture
  72 +------------------------------------------
  73 +
  74 +The HAB Encrypted Boot feature available in CAAM supported devices adds an
  75 +extra security operation to the bootloading sequence. It uses cryptographic
  76 +techniques (AES-CCM) to obscure the U-Boot data, so it cannot be seen or used
  77 +by unauthorized users. This mechanism protects the U-Boot code residing on
  78 +flash or external memory and also ensures that the final image is unique
  79 +per device.
  80 +
  81 +The process can be divided into two protection mechanisms. The first mechanism
  82 +is the bootloader code encryption which provides data confidentiality and the
  83 +second mechanism is the digital signature, which authenticates the encrypted
  84 +image.
  85 +
  86 +Keep in mind that the encrypted boot makes use of both mechanisms whatever the
  87 +order is (sign and then encrypt, or encrypt and then sign), both operations
  88 +can be applied on the same region with exception of the U-Boot Header (IVT,
  89 +boot data and DCD) which can only be signed, not encrypted.
  90 +
  91 +The diagram below illustrate the encrypted boot process overview:
  92 +
  93 + Host PC + CST i.MX + HAB
  94 + +------------+ +--------------+
  95 + | U-Boot | | U-Boot |
  96 + +------------+ +--------------+
  97 + | ^
  98 + | |
  99 + v DEK +--------------+
  100 + +------------+ | ----> | Decrypt |
  101 + | Encrypt | <--- | +--------------+
  102 + +------------+ DEK | ^
  103 + | | |
  104 + | Private | |
  105 + v Key +------+ +--------------+
  106 + +------------+ | | CAAM | | Authenticate |
  107 + | Sign | <--- +------+ +--------------+
  108 + +------------+ DEK ^ ^
  109 + | + OTPMK DEK \ / U-Boot
  110 + | | Blob \ / + CSF
  111 + v v \ /
  112 + +------------+ +----------+ +------------+
  113 + | Enc U-Boot | | | | Enc U-Boot |
  114 + | + CSF | ----> | i.MX | -------> | + CSF |
  115 + | + DEK Blob | | | | + DEK Blob |
  116 + +------------+ +----------+ +------------+
  117 + ^ |
  118 + | |
  119 + ---------------------
  120 + DEK Blob
  121 + (CAAM)
  122 +
  123 +The Code Signing Tool automatically generates a random AES Data Encryption Key
  124 +(DEK) when encrypting an image. This key is used in both encrypt and decrypt
  125 +operations and should be present in the final image structure encapsulated
  126 +by a CAAM blob.
  127 +
  128 +The OTP Master Key (OTPMK) is used to encrypt and wrap the DEK in a blob
  129 +structure. The OTPMK is unique per device and can be accessed by CAAM only.
  130 +To further add to the security of the DEK, the blob is decapsulated and
  131 +decrypted inside a secure memory partition that can only be accessed by CAAM.
  132 +
  133 +During the design of encrypted boot using DEK blob, it is necessary to inhibit
  134 +any modification or replacement of DEK blob with a counterfeit one allowing
  135 +execution of malicious code. The PRIBLOB setting in CAAM allows secure boot
  136 +software to have its own private blobs that cannot be decapsulated or
  137 +encapsulated by any other user code, including any software running in trusted
  138 +mode.
  139 +
  140 +Details about DEK Blob generation and PRIBLOB setting can be found in the
  141 +encrypted boot guide and application note AN12056[3] .
  142 +
  143 +2. Generating a PKI tree
  144 +-------------------------
  145 +
  146 +The first step is to generate the private keys and public keys certificates.
  147 +The HAB architecture is based in a Public Key Infrastructure (PKI) tree.
  148 +
  149 +The Code Signing Tools package contains an OpenSSL based key generation script
  150 +under keys/ directory. The hab4_pki_tree.sh script is able to generate a PKI
  151 +tree containing up to 4 Super Root Keys (SRK) as well as their subordinated
  152 +IMG and CSF keys.
  153 +
  154 +A new PKI tree can be generated by following the example below:
  155 +
  156 +- Generating 2048-bit PKI tree on CST v3.1.0:
  157 +
  158 + $ ./hab4_pki_tree.sh
  159 + ...
  160 + Do you want to use an existing CA key (y/n)?: n
  161 + Do you want to use Elliptic Curve Cryptography (y/n)?: n
  162 + Enter key length in bits for PKI tree: 2048
  163 + Enter PKI tree duration (years): 5
  164 + How many Super Root Keys should be generated? 4
  165 + Do you want the SRK certificates to have the CA flag set? (y/n)?: y
  166 +
  167 +The diagram below illustrate the PKI tree:
  168 +
  169 + +---------+
  170 + | CA |
  171 + +---------+
  172 + |
  173 + |
  174 + ---------------------------------------------------
  175 + | | | |
  176 + | | | |
  177 + v v v v
  178 + +--------+ +--------+ +--------+ +--------+
  179 + | SRK1 | | SRK2 | | SRK3 | | SRK4 |
  180 + +--------+ +--------+ +--------+ +--------+
  181 + / \ / \ / \ / \
  182 + v v v v v v v v
  183 + +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+
  184 + |CSF1| |IMG1| |CSF2| |IMG2| |CSF3| |IMG3| |CSF4| |IMG4|
  185 + +----+ +----+ +----+ +----+ +----+ +----+ +----+ +----+
  186 +
  187 +After running the script users can check the private keys under keys/ directory
  188 +and their respective X.509v3 public key certificates under crts/ directory.
  189 +Those files will be used during the signing and authentication process.
  190 +
  191 +2.1 Generating a fast authentication PKI tree
  192 +----------------------------------------------
  193 +
  194 +Starting in HAB v4.1.2 users can use a single SRK key to authenticate the both
  195 +CSF and IMG contents. This reduces the number of key pair authentications that
  196 +must occur during the ROM/HAB boot stage, thus providing a faster boot process.
  197 +
  198 +The script hab4_pki_tree.sh is also able to generate a Public Key Infrastructure
  199 +(PKI) tree which only contains SRK Keys, users should not set the CA flag when
  200 +generating the SRK certificates.
  201 +
  202 +- Generating 2048-bit fast authentication PKI tree on CST v3.1.0:
  203 +
  204 + $ ./hab4_pki_tree.sh
  205 + ...
  206 + Do you want to use an existing CA key (y/n)?: n
  207 + Do you want to use Elliptic Curve Cryptography (y/n)?: n
  208 + Enter key length in bits for PKI tree: 2048
  209 + Enter PKI tree duration (years): 5
  210 + How many Super Root Keys should be generated? 4
  211 + Do you want the SRK certificates to have the CA flag set? (y/n)?: n
  212 +
  213 +The diagram below illustrate the PKI tree generated:
  214 +
  215 + +---------+
  216 + | CA |
  217 + +---------+
  218 + |
  219 + |
  220 + ---------------------------------------------------
  221 + | | | |
  222 + | | | |
  223 + v v v v
  224 + +--------+ +--------+ +--------+ +--------+
  225 + | SRK1 | | SRK2 | | SRK3 | | SRK4 |
  226 + +--------+ +--------+ +--------+ +--------+
  227 +
  228 +2.2 Generating a SRK Table and SRK Hash
  229 +----------------------------------------
  230 +
  231 +The next step is to generated the SRK Table and its respective SRK Table Hash
  232 +from the SRK public key certificates created in one of the steps above.
  233 +
  234 +In the HAB architecture, the SRK Table is included in the CSF binary and the
  235 +SRK Hash is programmed in the SoC SRK_HASH[255:0] fuses.
  236 +
  237 +On the target device during the authentication process the HAB code verify the
  238 +SRK Table against the SoC SRK_HASH fuses, in case the verification success the
  239 +root of trust is established and the HAB code can progress with the image
  240 +authentication.
  241 +
  242 +The srktool can be used for generating the SRK Table and its respective SRK
  243 +Table Hash.
  244 +
  245 +- Generating SRK Table and SRK Hash in Linux 64-bit machines:
  246 +
  247 + $ ../linux64/bin/srktool -h 4 -t SRK_1_2_3_4_table.bin -e \
  248 + SRK_1_2_3_4_fuse.bin -d sha256 -c \
  249 + SRK1_sha256_2048_65537_v3_ca_crt.pem,\
  250 + SRK2_sha256_2048_65537_v3_ca_crt.pem,\
  251 + SRK3_sha256_2048_65537_v3_ca_crt.pem,\
  252 + SRK4_sha256_2048_65537_v3_ca_crt.pem
  253 +
  254 +The SRK_1_2_3_4_table.bin and SRK_1_2_3_4_fuse.bin files can be used in further
  255 +steps as explained in HAB guides available under doc/imx/habv4/guides/
  256 +directory.
  257 +
  258 +References:
  259 +[1] CST: i.MX High Assurance Boot Reference Code Signing Tool.
  260 +[2] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using
  261 + HABv4" - Rev 2.
  262 +[3] AN12056: "Encrypted Boot on HABv4 and CAAM Enabled Devices" - Rev. 1