[J-u-boot.git] / doc / imx / habv4 / introduction_habv4.txt

          +=======================================================+
          +     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 (certificate filenames must be separated by ',' without spaces).

- Generating SRK Table and SRK Hash in Linux 64-bit machines:

  $ CA_CRT="sha256_2048_65537_v3_ca_crt.pem"
  $ ../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_"$CA_CRT",SRK2_"$CA_CRT",SRK3_"$CA_CRT",SRK4_"$CA_CRT"

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
Commit	Line	Data
cbc4b041 BML	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
7cf57825	243	Table Hash (certificate filenames must be separated by ',' without spaces).
cbc4b041 BML	244
	245	- Generating SRK Table and SRK Hash in Linux 64-bit machines:
	246
7cf57825	247	$ CA_CRT="sha256_2048_65537_v3_ca_crt.pem"
cbc4b041 BML	248	$ ../linux64/bin/srktool -h 4 -t SRK_1_2_3_4_table.bin -e \
cbc4b041 BML	249	SRK_1_2_3_4_fuse.bin -d sha256 -c \
7cf57825	250	SRK1_"$CA_CRT",SRK2_"$CA_CRT",SRK3_"$CA_CRT",SRK4_"$CA_CRT"
cbc4b041 BML	251
	252	The SRK_1_2_3_4_table.bin and SRK_1_2_3_4_fuse.bin files can be used in further
	253	steps as explained in HAB guides available under doc/imx/habv4/guides/
	254	directory.
	255
	256	References:
	257	[1] CST: i.MX High Assurance Boot Reference Code Signing Tool.
	258	[2] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using
	259	HABv4" - Rev 2.
	260	[3] AN12056: "Encrypted Boot on HABv4 and CAAM Enabled Devices" - Rev. 1