1      +===============================================================+
2      +  i.MX6, i.MX7 U-Boot HABv4 Secure Boot guide for SPL targets  +
3      +===============================================================+
4
51. HABv4 secure boot process
6-----------------------------
7
8This document is an addendum of mx6_mx7_secure_boot.txt guide describing a
9step-by-step procedure on how to sign and securely boot an U-Boot image for
10SPL targets.
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 SPL target supporting secure boot
16-------------------------------------------------
17
18The U-Boot provides Second Program Loader (SPL) support which generates two
19final images, SPL and U-Boot proper. The HABv4 can be used to authenticate
20both binaries.
21
22Out of reset the ROM code authenticates the SPL which is responsible for
23initializing essential features such as DDR, UART, PMIC and clock
24enablement. Once the DDR is available, the SPL code loads the U-Boot proper
25image to its specific execution address and call the HAB APIs to extend the
26root of trust.
27
28The U-Boot provides support to secure boot configuration and also provide
29access to the HAB APIs exposed by the ROM vector table, the support is
30enabled by selecting the CONFIG_SECURE_BOOT option.
31
32When built with this configuration the U-Boot correctly pads the final SPL
33image by aligning to the next 0xC00 address, so the CSF signature data
34generated by CST can be concatenated to the image.
35
36The U-Boot also append an Image Vector Table (IVT) in the final U-Boot proper
37binary (u-boot-ivt.img) so it can be used by HAB API in a post ROM stage.
38
39The diagram below illustrate a signed SPL image layout:
40
41            ------- +-----------------------------+ <-- *start
42                ^   |      Image Vector Table     |
43                |   +-----------------------------+ <-- *boot_data
44                |   |          Boot Data          |
45                |   +-----------------------------+
46         Signed |   |           Padding           |
47          Data  |   +-----------------------------+ <-- *entry
48                |   |                             |
49                |   |            SPL              |
50                |   |                             |
51                |   +-----------------------------+
52                v   |           Padding           |
53            ------- +-----------------------------+ <-- *csf
54                    |                             |
55                    | Command Sequence File (CSF) |
56                    |                             |
57                    +-----------------------------+
58                    |      Padding (optional)     |
59                    +-----------------------------+
60
61The diagram below illustrate a signed u-boot-ivt.img image layout:
62
63            ------- +-----------------------------+ <-- *load_address
64                ^   |                             |
65                |   |                             |
66                |   |         u-boot.img          |
67         Signed |   |                             |
68          Data  |   |                             |
69                |   +-----------------------------+
70                |   |    Padding Next Boundary    |
71                |   +-----------------------------+ <-- *ivt
72                v   |     Image Vector Table      |
73            ------- +-----------------------------+ <-- *csf
74                    |                             |
75                    | Command Sequence File (CSF) |
76                    |                             |
77                    +-----------------------------+
78                    |     Padding (optional)      |
79                    +-----------------------------+
80
811.2 Enabling the secure boot support
82-------------------------------------
83
84The first step is to generate an U-Boot image supporting the HAB features
85mentioned above, this can be achieved by adding CONFIG_SECURE_BOOT to the
86build configuration:
87
88- Defconfig:
89
90  CONFIG_SECURE_BOOT=y
91
92- Kconfig:
93
94  ARM architecture -> Support i.MX HAB features
95
961.3 Creating the CSF description file
97--------------------------------------
98
99The CSF contains all the commands that the HAB executes during the secure
100boot. These commands instruct the HAB code on which memory areas of the image
101to authenticate, which keys to install, use and etc.
102
103CSF examples are available under doc/imx/habv4/csf_examples/ directory.
104
105Build logs containing the "Authenticate Data" parameters are available after
106the U-Boot build, the example below is a log for mx6sabresd_defconfig target:
107
108- SPL build log:
109
110  $ cat SPL.log
111  Image Type:   Freescale IMX Boot Image
112  Image Ver:    2 (i.MX53/6/7 compatible)
113  Mode:         DCD
114  Data Size:    69632 Bytes = 68.00 KiB = 0.07 MiB
115  Load Address: 00907420
116  Entry Point:  00908000
117  HAB Blocks:   0x00907400 0x00000000 0x0000ec00
118
119- u-boot-ivt.img build log:
120
121  $ cat u-boot-ivt.img.log
122  Image Name:   U-Boot 2019.01-00003-g78ee492eb3
123  Created:      Mon Jan 14 17:58:10 2019
124  Image Type:   ARM U-Boot Firmware with HABv4 IVT (uncompressed)
125  Data Size:    458688 Bytes = 447.94 KiB = 0.44 MiB
126  Load Address: 17800000
127  Entry Point:  00000000
128  HAB Blocks:   0x177fffc0   0x0000   0x0006e020
129
130As explained in section above the SPL is first authenticated by the ROM code
131and the root of trust is extended to the U-Boot image, hence two CSF files are
132necessary to completely sign a bootloader image.
133
134In "Authenticate Data" CSF command users can copy and past the output
135addresses, the csf_uboot.txt can be used as example:
136
137- In csf_SPL.txt:
138
139  Block = 0x00907400 0x00000000 0x0000ec00 "SPL"
140
141- In csf_uboot-ivt.txt:
142
143  Block = 0x177fffc0 0x0000 0x0006e020 "u-boot-ivt.img"
144
1451.4 Signing the images
146-----------------------
147
148The CST tool is used for singing the U-Boot binary and generating a CSF binary,
149users should input the CSF description file created in the step above and
150receive a CSF binary, which contains the CSF commands, SRK table, signatures
151and certificates.
152
153- Create SPL CSF binary file:
154
155  $ ./cst -i csf_SPL.txt -o csf_SPL.bin
156
157- Append CSF signature to the end of SPL image:
158
159  $ cat SPL csf_SPL.bin > SPL-signed
160
161- Create U-Boot proper CSF binary file:
162
163  $ ./cst -i csf_uboot-ivt.txt -o csf_uboot-ivt.bin
164
165- Append CSF signature to the end of U-Boot proper image:
166
167  $ cat u-boot-ivt.img csf_uboot-ivt.bin > u-boot-signed.img
168
169The bootloader is signed and can be flashed into the boot media.
170
1711.5 Closing the device
172-----------------------
173
174The procedure for closing the device is similar as in Non-SPL targets, for a
175complete procedure please refer to section "1.5 Programming SRK Hash" in
176mx6_mx7_secure_boot.txt document available under doc/imx/habv4/guides/
177directory.
178
179References:
180[1] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using
181 HABv4" - Rev 2.
182