Eric Lee / smarc-uboot

Download as
Browse Code ยป

Commit cba7ec79bb014fe7c107313187448c7c74a1de82

Authored by Breno Lima
Committed by Ye Li
1 parent a83dc28dee
Exists in smarc-imx_v2018.03_4.14.78_1.0.0_ga

MLK-20553-3 doc: imx: ahab: Add Secure Boot documentation for i.MX8 and i.MX8x SPL targets 

The current U-Boot implementation includes SPL targets for i.MX8QM and
i.MXQXP MEK boards:

- imx8qxp_mek_spl_defconfig
- imx8qxp_mek_spl_fspi_defconfig
- imx8qm_mek_spl_defconfig
- imx8qm_mek_spl_fspi_defconfig

The U-Boot proper and ATF are included in an additional container being
necessary a different procedure for signing the flash.bin image.

Add a step-by-step guide covering the signing procedure.
Add a CSF example for the 3rd container.

Signed-off-by: Breno Lima <breno.lima@nxp.com>
Reviewed-by: Frank Zhang <frank.zhang@nxp.com>
Reviewed-by: Marius Grigoras <marius.grigoras@nxp.com>
Reviewed-by: Utkarsh Gupta <utkarsh.gupta@nxp.com>
(cherry picked from commit 04505024d38eebbb5f39133b502c8e450ca40215)

Showing 2 changed files with 379 additions and 0 deletions Inline Diff

doc/imx/hab/ahab/csf_examples/cst_uboot_atf.txt
Diff comments   View file @ cba7ec7
File was created 1 [Header]
2 Target = AHAB
3 Version = 1.0
4
5 [Install SRK]
6 # SRK table generated by srktool
7 File = "../crts/SRK_1_2_3_4_table.bin"
8 # Public key certificate in PEM format on this example only using SRK key
9 Source = "../crts/SRK1_sha384_secp384r1_v3_usr_crt.pem"
10 # Index of the public key certificate within the SRK table (0 .. 3)
11 Source index = 0
12 # Type of SRK set (NXP or OEM)
13 Source set = OEM
14 # bitmask of the revoked SRKs
15 Revocations = 0x0
16
17 [Authenticate Data]
18 # Binary to be signed generated by mkimage
19 File = "u-boot-atf-container.img"
20 # Offsets = Container header Signature block (printed out by mkimage)
21 Offsets = 0x0 0x110
22
doc/imx/hab/ahab/guides/mx8_mx8x_spl_secure_boot.txt
Diff comments   View file @ cba7ec7
File was created 1 +=========================================================+
2 + i.MX 8, i.MX 8X AHAB guide on SPL targets +
3 +=========================================================+
4
5 1. AHAB secure boot process
6 ----------------------------
7
8 This document provides a step-by-step guide on how securely boot a flash.bin
9 image generated by Secondary Program Loader (SPL) targets. It is assumed that
10 the reader is familiar with basic AHAB concepts and with the PKI tree
11 generation.
12
13 Details about AHAB can be found in the introduction_ahab.txt document and in
14 processors Security Reference Manual Document (SRM).
15
16 1.1 Preparing the environment to build a secure boot image
17 -----------------------------------------------------------
18
19 The following files and projects are used to prepare a secure boot image
20 for i.MX8/8x device:
21
22 - imx-mkimage.
23 - SECO Firmware.
24 - U-Boot proper and SPL. (Please refer to section 1.2)
25 - ARM Trusted Firmware (ATF).
26 - System Controller Firmware (SCFW) with debug monitor enabled.
27 - Cortex M binary. (Optional)
28 - Kernel image. (Optional)
29 - Code signing tools (CST).
30
31 The procedure to download the SECO firmware and build U-Boot, SCFW and ATF are
32 out of the scope of this document, please refer to the Linux BSP Release Notes
33 and AN12212[1] for further details.
34
35 1.2 Preparing U-Boot to support AHAB secure boot features
36 ----------------------------------------------------------
37
38 The U-Boot provides an alternative SPL target for i.MX8 and i.MX8x devices. The
39 SPL is intended to be used by applications that requires a initial bootloader
40 prior to initialize the ARM Trusted Firmware (ATF) and the U-Boot proper.
41
42 The U-Boot support AHAB functions that are essential to completely authenticate
43 the flash.bin image. On SPL targets only the SCFW, SPL and M4 IMG are
44 authenticated at SCU ROM level, in order to authenticate the ATF and U-Boot
45 proper it's necessary to call the SCU API sc_misc_seco_authenticate() function
46 at SPL level.
47
48 The support is enabled by adding CONFIG_AHAB_BOOT to the defconfig file used
49 by your target:
50
51 - Defconfig:
52 CONFIG_AHAB_BOOT=y
53 - Kconfig:
54 ARM architecture -> Support i.MX 8 AHAB features
55
56 1.3 Building a SPL image supporting secure boot
57 ------------------------------------------------
58
59 The boot image generated by SPL targets has three containers:
60
61 +---------------------------+ ---------
62 | 1st Container header | ^
63 | and signature | |
64 +---------------------------+ |
65 | Padding for 1kB alignment | |
66 +---------------------------+ |
67 | 2nd Container header | |
68 | and signature | |
69 +---------------------------+ |
70 | Padding | | Authenticated at
71 +---------------------------+ | SCU ROM Level
72 | SECO FW | |
73 +---------------------------+ |
74 | Padding | |
75 +---------------------------+ |
76 | SCU FW + DCD Table | |
77 +---------------------------+ |
78 | Cortex-M Image | |
79 +---------------------------+ |
80 | SPL Image | v
81 +---------------------------+ ---------
82 | 3rd Container header | ^
83 | and signature | |
84 +---------------------------+ |
85 | Padding | | Authenticated
86 +---------------------------+ | at SPL Level
87 | U-Boot Proper IMG | |
88 +---------------------------+ |
89 | ARM Trusted FW (ATF) | v
90 +---------------------------+ ---------
91
92 The first container includes the SECO firmware which is signed using NXP keys,
93 this container is authenticated by SECO ROM at SCU ROM level.
94
95 The second container includes the SCFW, SPL and Cortex M SW images which are
96 signed using OEM keys, this container is authenticated by SECO FW at SCU ROM
97 level.
98
99 The third container includes the U-Boot proper and the ATF. The SPL is in
100 charge to load this container and also to interface with SCU requesting
101 SECO FW to authenticate the additional container.
102
103 The signing procedure is slightly different when compared with HABv4 series. On
104 AHAB the signature is directly included in the container, the CST is
105 responsible to sign and handle the "Signature Block":
106
107 +----------------------------+ ---------
108 | | ^
109 | | |
110 | Container header | |
111 | | |
112 | | |
113 +---+----------------------- + |
114 | S | Signature block header | | Signed
115 | i +------------------------+ |
116 | g | | |
117 | n | | |
118 | a | SRK table | |
119 | t | | |
120 | u | | v
121 | r +------------------------+ ---------
122 | e | Signature |
123 | +------------------------+
124 | B | |
125 | l | SGK Key |
126 | o | Certificate (optional) |
127 | c | |
128 | k | |
129 +---+------------------------+
130
131 In case using the optional subordinate SGK key, the container signature is
132 verified against the SGK key certificate. This certificate is verified
133 against the SRK table.
134
135 In case not using the subordinate key, the container signature is verified
136 against the SRK keys directly.
137
138 1.4 Preparing the boot image
139 -----------------------------
140
141 1.4.1 Preparing the 3rd container
142 ----------------------------------
143
144 The first step is to generate the third container including the U-Boot proper
145 and ATF images.
146
147 The imx-mkimage project includes a target which only generates this third
148 container:
149
150 - Generating the U-Boot proper + ATF container:
151
152 $ make SOC=<SoC Name> u-boot-atf-container.img
153
154 The mkimage log provides the container and signature block offsets used by the
155 CSF description file:
156
157 CST: CONTAINER 0 offset: 0x0
158 CST: CONTAINER 0: Signature Block: offset is at 0x110
159
160 The u-boot-atf-container.img file is the third container which have to be
161 signed using the Code Signing Tool (CST).
162
163 1.4.2 Signing the 3rd container
164 --------------------------------
165
166 The CSF description file contains all the commands that the SECO executes
167 during the secure boot procedure. These commands instruct the AHAB code on
168 which memory areas of the image to authenticate, which keys to install, use
169 and etc.
170
171 CSF examples are available under doc/imx/hab/ahab/csf_examples/ directory.
172
173 As explained in section above the mkimage log provides the container and
174 signature block offsets used by the CSF description file:
175
176 - "Authenticate Data" command in cst_uboot_atf.txt file:
177
178 [Authenticate Data]
179 # Binary to be signed generated by mkimage
180 File = "u-boot-atf-container.img"
181 # Offsets = Container header Signature block
182 Offsets = 0x0 0x110
183
184 - Sign the third container:
185
186 $ ./cst -i cst_uboot_atf.txt -o signed-u-boot-atf-container.img
187
188 The signed-u-boot-atf-container.img have to be copied to imx-mkimage directory
189 and renamed to u-boot-atf-container.img.
190
191 1.4.3 Preparing the flash.bin image
192 ------------------------------------
193
194 The signed 3rd container can be now used to create the final flash.bin image,
195 be sure that your signed container were successfully replaced and is named
196 as u-boot-atf-container.img.
197
198 - Generating the flash.bin image:
199
200 $ make SOC=<SoC Name> flash_spl_container
201
202 The mkimage log provides the container and signature block offsets used by the
203 CSF description file:
204
205 CST: CONTAINER 0 offset: 0x400
206 CST: CONTAINER 0: Signature Block: offset is at 0x510
207
208 The flash.bin file include three containers and the second container have to be
209 signed using the Code Signing Tool (CST).
210
211 1.4.4 Signing the flash.bin image
212 ----------------------------------
213
214 As mentioned above the CSF description file contains all the commands that
215 the SECO executes during the secure boot procedure.
216
217 The procedure for signing the flash.bin image is similar as documented in
218 mx8_mx8x_secure_boot.txt guide.
219
220 - "Authenticate Data" command in csf_boot_image.txt file:
221
222 [Authenticate Data]
223 # Binary to be signed generated by mkimage
224 File = "flash.bin"
225 # Offsets = Container header Signature block
226 Offsets = 0x400 0x510
227
228 - Sign the flash.bin container:
229
230 $ ./cst -i csf_boot_image.txt -o signed-flash.bin
231
232 The signed-flash.bin image contains all the signatures and can be flashed in
233 the device.
234
235 1.5 Flashing the signed image
236 ------------------------------
237
238 After completing all steps in section "1.4 Preparing the boot image" the
239 signed flash.bin image can be flashed in the device:
240
241 $ sudo dd if=signed-flash.bin of=/dev/sd<X> bs=1k seek=32 && sync
242
243 For the next steps you should be able to see U-Boot and SCFW consoles in your
244 host PC. Please note that SCU console may be replaced by the M4 console, in
245 case the M4 image is needed a base board will be required to access the SCU
246 console.
247
248 1.6 Programming SRK Hash
249 -------------------------
250
251 As explained in introduction_ahab.txt document the SRK Hash fuse values are
252 generated by the srktool and should be programmed in the SoC SRK_HASH[511:0]
253 fuses.
254
255 Be careful when programming these values, as this data is the basis
256 for the root of trust. An error in SRK Hash results in a part that
257 does not boot.
258
259 The U-Boot fuse tool can be used for programming eFuses on i.MX SoCs.
260
261 - Dump SRK Hash fuses values in host machine:
262
263 $ od -t x4 SRK_1_2_3_4_fuse.bin
264 0000000 d436cc46 8ecccda9 b89e1601 5fada3db
265 0000020 d454114a b6cd51f4 77384870 c50ee4b2
266 0000040 a27e5132 eba887cf 592c1e2b bb501799
267 0000060 ee702e07 cf8ce73e fb55e2d5 eba6bbd2
268
269 - Program SRK_HASH[511:0] fuses:
270
271 * On i.MX 8 QXP:
272
273 => fuse prog 0 730 0xd436cc46
274 => fuse prog 0 731 0x8ecccda9
275 => fuse prog 0 732 0xb89e1601
276 => fuse prog 0 733 0x5fada3db
277 => fuse prog 0 734 0xd454114a
278 => fuse prog 0 735 0xb6cd51f4
279 => fuse prog 0 736 0x77384870
280 => fuse prog 0 737 0xc50ee4b2
281 => fuse prog 0 738 0xa27e5132
282 => fuse prog 0 739 0xeba887cf
283 => fuse prog 0 740 0x592c1e2b
284 => fuse prog 0 741 0xbb501799
285 => fuse prog 0 742 0xee702e07
286 => fuse prog 0 743 0xcf8ce73e
287 => fuse prog 0 744 0xfb55e2d5
288 => fuse prog 0 745 0xeba6bbd2
289
290 * On i.MX 8 QM:
291
292 => fuse prog 0 722 0xd436cc46
293 => fuse prog 0 723 0x8ecccda9
294 => fuse prog 0 724 0xb89e1601
295 => fuse prog 0 725 0x5fada3db
296 => fuse prog 0 726 0xd454114a
297 => fuse prog 0 727 0xb6cd51f4
298 => fuse prog 0 728 0x77384870
299 => fuse prog 0 729 0xc50ee4b2
300 => fuse prog 0 730 0xa27e5132
301 => fuse prog 0 731 0xeba887cf
302 => fuse prog 0 732 0x592c1e2b
303 => fuse prog 0 733 0xbb501799
304 => fuse prog 0 734 0xee702e07
305 => fuse prog 0 735 0xcf8ce73e
306 => fuse prog 0 736 0xfb55e2d5
307 => fuse prog 0 737 0xeba6bbd2
308
309 1.7 Verify SECO events
310 -----------------------
311
312 If the fuses have been written properly, there should be no SECO events
313 after boot. To validate this, power on the board, and run the following
314 command on the SCFW terminal:
315
316 >$ seco events
317
318 Nothing should be returned after this command. If you get an error, please
319 refer to examples below:
320
321 0x0087EE00 = The container image is not signed.
322 0x0087FA00 = The container image was signed with wrong key which are not
323 matching the OTP SRK hashes.
324
325 In case your SRK fuses are not programmed yet the event 0x0087FA00 may also
326 be displayed.
327
328 Note: The SECO FW v1.1.0 is not logging an invalid image integrity as an event
329 in open mode, in case your image does not boot after moving the lifecycle
330 please review your image setup.
331
332 1.8 Close the device
333 ---------------------
334
335 After the device successfully boots a signed image without generating any
336 SECO security events, it is safe to close the device. The SECO lifecycle
337 should be changed from 32 (0x20) NXP open to 128 (0x80) OEM closed. Be
338 aware this step can damage your board if a previous step failed. It is
339 also irreversible. Run on the SCFW terminal:
340
341 >$ seco lifecycle 16
342
343 Now reboot the target, and on the same terminal, run:
344
345 >$ seco info
346
347 The lifecycle value should now be 128 (0x80) OEM closed.
348
349 2. Authenticating the OS container
350 -----------------------------------
351
352 The procedure for authenticating the OS container is similar as in Non-SPL
353 targets, for a complete procedure please refer to mx8_mx8x_secure_boot.txt
354 document available under doc/imx/hab/ahab/guides/ directory.
355
356 References:
357 [1] AN12212: "Software Solutions for Migration Guide from Aarch32 to
358 Aarch64" - Rev 0."
359