1         +=======================================================+
2         +   i.MX6, i.MX7 U-Boot Secure Boot guide using HABv4   +
3         +=======================================================+
4
51. HABv4 secure boot process
6-----------------------------
7
8This document describes a step-by-step procedure on how to sign and securely
9boot an U-Boot image for non-SPL targets. It is assumed that the reader is
10familiar with basic HAB concepts and with the PKI tree generation.
11
12Details about HAB can be found in the application note AN4581[1] and in the
13introduction_habv4.txt document.
14
151.1 Building a u-boot-dtb.imx image supporting secure boot
16-----------------------------------------------------------
17
18The U-Boot provides support to secure boot configuration and also provide
19access to the HAB APIs exposed by the ROM vector table, the support is
20enabled by selecting the CONFIG_SECURE_BOOT option.
21
22When built with this configuration, the U-Boot provides extra functions for
23HAB, such as the HAB status logs retrievement through the hab_status command
24and support for extending the root of trust.
25
26The U-Boot also correctly pads the final image by aligning to the next 0xC00
27address, so the CSF signature data generated by CST can be concatenated to
28image.
29
30The diagram below illustrate a signed u-boot-dtb.imx image layout:
31
32            ------- +-----------------------------+ <-- *start
33                ^   |      Image Vector Table     |
34                |   +-----------------------------+ <-- *boot_data
35                |   |          Boot Data          |
36                |   +-----------------------------+ <-- *dcd
37                |   |          DCD Table          |
38                |   +-----------------------------+
39         Signed |   |           Padding           |
40          Data  |   +-----------------------------+ <-- *entry
41                |   |                             |
42                |   |                             |
43                |   |       u-boot-dtb.bin        |
44                |   |                             |
45                |   |                             |
46                |   +-----------------------------+
47                v   |           Padding           |
48            ------- +-----------------------------+ <-- *csf
49                    |                             |
50                    | Command Sequence File (CSF) |
51                    |                             |
52                    +-----------------------------+
53                    |      Padding (optional)     |
54                    +-----------------------------+
55
561.2 Enabling the secure boot support
57-------------------------------------
58
59The first step is to generate an U-Boot image supporting the HAB features
60mentioned above, this can be achieved by adding CONFIG_SECURE_BOOT to the
61build configuration:
62
63- Defconfig:
64
65  CONFIG_SECURE_BOOT=y
66
67- Kconfig:
68
69  ARM architecture -> Support i.MX HAB features
70
711.3 Creating the CSF description file
72--------------------------------------
73
74The CSF contains all the commands that the HAB executes during the secure
75boot. These commands instruct the HAB on which memory areas of the image
76to authenticate, which keys to install, use and etc.
77
78CSF examples are available under doc/imx/habv4/csf_examples/ directory.
79
80A build log containing the "Authenticate Data" parameters is available after
81the U-Boot build, the example below is a log for mx7dsabresd_defconfig target:
82
83- mkimage build log:
84
85  $ cat u-boot-dtb.imx.log
86
87  Image Type:   Freescale IMX Boot Image
88  Image Ver:    2 (i.MX53/6/7 compatible)
89  Mode:         DCD
90  Data Size:    667648 Bytes = 652.00 KiB = 0.64 MiB
91  Load Address: 877ff420
92  Entry Point:  87800000
93  HAB Blocks:   0x877ff400 0x00000000 0x0009ec00
94                ^^^^^^^^^^ ^^^^^^^^^^ ^^^^^^^^^^
95                |          |          |
96                |          |          ------- (1)
97                |          |
98                |          ------------------ (2)
99                |
100                ----------------------------- (3)
101
102  (1)   Size of area in file u-boot-dtb.imx to sign.
103        This area should include the IVT, the Boot Data the DCD
104        and the U-Boot itself.
105  (2)   Start of area in u-boot-dtb.imx to sign.
106  (3)   Start of area in RAM to authenticate.
107
108- In "Authenticate Data" CSF command users can copy and past the output
109  addresses:
110
111  Block = 0x877ff400 0x00000000 0x0009ec00 "u-boot-dtb.imx"
112
1131.4 Signing the U-Boot binary
114------------------------------
115
116The CST tool is used for singing the U-Boot binary and generating a CSF binary,
117users should input the CSF description file created in the step above and
118should receive a CSF binary, which contains the CSF commands, SRK table,
119signatures and certificates.
120
121- Create CSF binary file:
122
123  $ ./cst -i csf_uboot.txt -o csf_uboot.bin
124
125- Append CSF signature to the end of U-Boot image:
126
127  $ cat u-boot-dtb.imx csf_uboot.bin > u-boot-signed.imx
128
129The u-boot-signed.imx is the signed binary and should be flashed into the boot
130media.
131
132- Flash signed U-Boot binary:
133
134  $ sudo dd if=u-boot-signed.imx of=/dev/sd<x> bs=1K seek=1 && sync
135
1361.5 Programming SRK Hash
137-------------------------
138
139As explained in AN4581[1] and in introduction_habv4.txt document the SRK Hash
140fuse values are generated by the srktool and should be programmed in the
141SoC SRK_HASH[255:0] fuses.
142
143Be careful when programming these values, as this data is the basis for the
144root of trust. An error in SRK Hash results in a part that does not boot.
145
146The U-Boot fuse tool can be used for programming eFuses on i.MX SoCs.
147
148- Dump SRK Hash fuses values in host machine:
149
150  $ hexdump -e '/4 "0x"' -e '/4 "%X""\n"' SRK_1_2_3_4_fuse.bin
151  0x20593752
152  0x6ACE6962
153  0x26E0D06C
154  0xFC600661
155  0x1240E88F
156  0x1209F144
157  0x831C8117
158  0x1190FD4D
159
160- Program SRK_HASH[255:0] fuses, using i.MX6 series as example:
161
162  => fuse prog 3 0 0x20593752
163  => fuse prog 3 1 0x6ACE6962
164  => fuse prog 3 2 0x26E0D06C
165  => fuse prog 3 3 0xFC600661
166  => fuse prog 3 4 0x1240E88F
167  => fuse prog 3 5 0x1209F144
168  => fuse prog 3 6 0x831C8117
169  => fuse prog 3 7 0x1190FD4D
170
171The table below lists the SRK_HASH bank and word according to the i.MX device:
172
173    +-------------------+---------------+---------------+---------------+
174    |                   |  i.MX6 Series |    i.MX7D/S   |    i.MX7ULP   |
175    +-------------------+---------------+---------------+---------------+
176    | SRK_HASH[31:00]   | bank 3 word 0 | bank 6 word 0 | bank 5 word 0 |
177    +-------------------+---------------+---------------+---------------+
178    | SRK_HASH[63:32]   | bank 3 word 1 | bank 6 word 1 | bank 5 word 1 |
179    +-------------------+---------------+---------------+---------------+
180    | SRK_HASH[95:64]   | bank 3 word 2 | bank 6 word 2 | bank 5 word 2 |
181    +-------------------+---------------+---------------+---------------+
182    | SRK_HASH[127:96]  | bank 3 word 3 | bank 6 word 3 | bank 5 word 3 |
183    +-------------------+---------------+---------------+---------------+
184    | SRK_HASH[159:128] | bank 3 word 4 | bank 7 word 0 | bank 5 word 4 |
185    +-------------------+---------------+---------------+---------------+
186    | SRK_HASH[191:160] | bank 3 word 5 | bank 7 word 1 | bank 5 word 5 |
187    +-------------------+---------------+---------------+---------------+
188    | SRK_HASH[223:192] | bank 3 word 6 | bank 7 word 2 | bank 5 word 6 |
189    +-------------------+---------------+---------------+---------------+
190    | SRK_HASH[255:224] | bank 3 word 7 | bank 7 word 3 | bank 5 word 7 |
191    +-------------------+---------------+---------------+---------------+
192
1931.6 Verifying HAB events
194-------------------------
195
196The next step is to verify that the signature attached to U-Boot is
197successfully processed without errors. HAB generates events when processing
198the commands if it encounters issues.
199
200The hab_status U-Boot command call the hab_report_event() and hab_status()
201HAB API functions to verify the processor security configuration and status.
202This command displays any events that were generated during the process.
203
204Prior to closing the device users should ensure no HAB events were found, as
205the example below:
206
207- Verify HAB events:
208
209  => hab_status
210
211  Secure boot disabled
212
213  HAB Configuration: 0xf0, HAB State: 0x66
214  No HAB Events Found!
215
2161.7 Closing the device
217-----------------------
218
219After the device successfully boots a signed image without generating any HAB
220events, it is safe to close the device. This is the last step in the HAB
221process, and is achieved by programming the SEC_CONFIG[1] fuse bit.
222
223Once the fuse is programmed, the chip does not load an image that has not been
224signed using the correct PKI tree.
225
226- Program SEC_CONFIG[1] fuse, using i.MX6 series as example:
227
228  => fuse prog 0 6 0x00000002
229
230The table below list the SEC_CONFIG[1] bank and word according to the i.MX
231device:
232
233             +--------------+-----------------+------------+
234             |    Device    |  Bank and Word  |    Value   |
235             +--------------+-----------------+------------+
236             | i.MX6 Series |  bank 0 word 6  | 0x00000002 |
237             +--------------+-----------------+------------+
238             | i.MX7D/S     |  bank 1 word 3  | 0x02000000 |
239             +--------------+-----------------+------------+
240             | i.MX7ULP     |  bank 29 word 6 | 0x80000000 |
241             +--------------+-----------------+------------+
242
2431.8 Completely secure the device
244---------------------------------
245
246Additional fuses can be programmed for completely secure the device, more
247details about these fuses and their possible impact can be found at AN4581[1].
248
249- Program SRK_LOCK, using i.MX6 series as example:
250
251  => fuse prog 0 0 0x4000
252
253- Program DIR_BT_DIS, using i.MX6 series as example:
254
255  => fuse prog 0 6 0x8
256
257- Program SJC_DISABLE, using i.MX6 series as example:
258
259  => fuse prog 0 6 0x100000
260
261- JTAG_SMODE, using i.MX6 series as example:
262
263  => fuse prog 0 6 0xC00000
264
265The table below list the SRK_LOCK, DIR_BT_DIS, SJC_DISABLE, and JTAG_SMODE bank
266and word according to the i.MX device:
267
268              +--------------+---------------+------------+
269              |    Device    | Bank and Word |   Value    |
270              +--------------+---------------+------------+
271              |                  SRK_LOCK                 |
272              +-------------------------------------------+
273              | i.MX6 Series | bank 0 word 0 | 0x00004000 |
274              +--------------+---------------+------------+
275              | i.MX7D/S     | bank 0 word 0 | 0x00000200 |
276              +--------------+---------------+------------+
277              | i.MX7ULP     | bank 1 word 1 | 0x00000080 |
278              +--------------+---------------+------------+
279              |                 DIR_BT_DIS                |
280              +-------------------------------------------+
281              | i.MX6 Series | bank 0 word 6 | 0x00000008 |
282              +--------------+---------------+------------+
283              | i.MX7D/S     | bank 1 word 3 | 0x08000000 |
284              +--------------+---------------+------------+
285              | i.MX7ULP     | bank 1 word 1 | 0x00002000 |
286              +--------------+---------------+------------+
287              |                 SJC_DISABLE               |
288              +-------------------------------------------+
289              | i.MX6 Series | bank 0 word 6 | 0x00100000 |
290              +--------------+---------------+------------+
291              | i.MX7D/S     | bank 1 word 3 | 0x00200000 |
292              +--------------+---------------+------------+
293              | i.MX7ULP     | bank 1 word 1 | 0x00000020 |
294              +--------------+---------------+------------+
295              |                 JTAG_SMODE                |
296              +-------------------------------------------+
297              | i.MX6 Series | bank 0 word 6 | 0x00C00000 |
298              +--------------+---------------+------------+
299              | i.MX7D/S     | bank 1 word 3 | 0x00C00000 |
300              +--------------+---------------+------------+
301              | i.MX7ULP     | bank 1 word 1 | 0x000000C0 |
302              +--------------+---------------+------------+
303
3042. Extending the root of trust
305-------------------------------
306
307The High Assurance Boot (HAB) code located in the on-chip ROM provides an
308Application Programming Interface (API) making it possible to call back
309into the HAB code for authenticating additional boot images.
310
311The U-Boot supports this feature and can be used to authenticate the Linux
312Kernel Image.
313
314The process of signing an additional image is similar to the U-Boot.
315The diagram below illustrate the zImage layout:
316
317            ------- +-----------------------------+ <-- *load_address
318                ^   |                             |
319                |   |                             |
320                |   |                             |
321                |   |                             |
322                |   |           zImage            |
323         Signed |   |                             |
324          Data  |   |                             |
325                |   |                             |
326                |   +-----------------------------+
327                |   |    Padding Next Boundary    |
328                |   +-----------------------------+ <-- *ivt
329                v   |     Image Vector Table      |
330            ------- +-----------------------------+ <-- *csf
331                    |                             |
332                    | Command Sequence File (CSF) |
333                    |                             |
334                    +-----------------------------+
335                    |     Padding (optional)      |
336                    +-----------------------------+
337
3382.1 Padding the image
339----------------------
340
341The zImage must be padded to the next boundary address (0x1000), for instance
342if the image size is 0x649920 it must be padded to 0x64A000.
343
344The tool objcopy can be used for padding the image.
345
346- Pad the zImage:
347
348  $ objcopy -I binary -O binary --pad-to 0x64A000 --gap-fill=0x00 \
349	zImage zImage_pad.bin
350
3512.2 Generating Image Vector Table
352----------------------------------
353
354The HAB code requires an Image Vector Table (IVT) for determining the image
355length and the CSF location. Since zImage does not include an IVT this has
356to be manually created and appended to the end of the padded zImage, the
357script genIVT.pl in script_examples directory can be used as reference.
358
359- Generate IVT:
360
361  $ genIVT.pl
362
363Note: The load Address may change depending on the device.
364
365- Append the ivt.bin at the end of the padded zImage:
366
367  $ cat zImage_pad.bin ivt.bin > zImage_pad_ivt.bin
368
3692.3 Signing the image
370----------------------
371
372A CSF file has to be created to sign the image. HAB does not allow to change
373the SRK once the first image is authenticated, so the same SRK key used in
374U-Boot must be used when extending the root of trust.
375
376CSF examples are available in ../csf_examples/additional_images/
377directory.
378
379- Create CSF binary file:
380
381  $ ./cst --i csf_additional_images.txt --o csf_zImage.bin
382
383- Attach the CSF binary to the end of the image:
384
385  $ cat zImage_pad_ivt.bin csf_zImage.bin > zImage_signed.bin
386
3872.4 Verifying HAB events
388-------------------------
389
390The U-Boot includes the hab_auth_img command which can be used for
391authenticating and troubleshooting the signed image, zImage must be
392loaded at the load address specified in the IVT.
393
394- Authenticate additional image:
395
396  => hab_auth_img <Load Address> <Image Size> <IVT Offset>
397
398If no HAB events were found the zImage is successfully signed.
399
400References:
401[1] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using
402 HABv4" - Rev 2.
403