1         +=========================================================+
2         +      i.MX 8, i.MX 8X Encrypted Boot guide using AHAB    +
3         +=========================================================+
4
51. AHAB Encrypted Boot process
6-------------------------------
7
8This document describes a step-by-step procedure on how to encrypt and sign a
9bootloader image for i.MX8/8x family devices. It is assumed that the reader
10is familiar with basic AHAB concepts and has already closed the device,
11step-by-step procedure can be found in mx8_mx8x_secure_boot.txt and
12mx8_mx8x_spl_secure_boot.txt guides.
13
14The steps described in this document were based in i.MX8QM device, the same
15concept can be applied to others processors in i.MX8/8X family devices.
16
171.1 Understanding the encrypted image signature block
18------------------------------------------------------
19
20As described in mx8_mx8x_secure_boot.txt guide a single binary is used to boot
21the device. The imx-mkimage tool combines all the input images in a container
22structure, generating a flash.bin binary.
23
24AHAB is able to decrypt image containers by calling SECO authentication
25functions, the image must be encrypted by CST and the resulting DEK (Data
26Encryption Key) must be encapsulated and included into the container signature
27block:
28
29                +----------------------------+
30                |                            |  ^
31                |                            |  |
32                |      Container header      |  |
33                |                            |  |
34                |                            |  |
35                +---+------------------------+  |
36                | S | Signature block header |  | Signed
37                | i +------------------------+  |
38                | g |                        |  |
39                | n |                        |  |
40                | a |        SRK table       |  |
41                | t |                        |  |
42                | u |                        |  v
43                | r +------------------------+
44                | e |       Signature        |
45                |   +------------------------+
46                | B |                        |
47                | l |        SGK Key         |
48                | o | Certificate (optional) |
49                | c |                        |
50                | k +------------------------+
51                |   |        DEK Blob        |
52                +---+------------------------+
53
541.1.1 Understanding and generating the DEK blob
55------------------------------------------------
56
57The encrypted boot image requires a DEK blob on each time AHAB is used to
58decrypt an image. The DEK blob is used as a security layer to wrap and store
59the DEK off-chip using the OTPMK which is unique per device.
60
61On i.MX8/8x devices the DEK blob is generated using the SECO API, the following
62funtion is available in U-Boot and can be executed through dek_blob command:
63
64- sc_seco_gen_key_blob(sc_ipc_t ipc, uint32_t id, sc_faddr_t load_addr,
65		       sc_faddr_t export_addr, uint16_t max_size)
66
67Details in API usage can be found in SCFW API guide [1].
68
691.2 Enabling the encrypted boot support in U-Boot
70--------------------------------------------------
71
72For deploying an encrypted boot image additional U-Boot tools are needed,
73please be sure to have the following features enabled, this can be achieved
74by following one of the methods below:
75
76- Defconfig:
77
78  CONFIG_AHAB_BOOT=y
79  CONFIG_CMD_DEKBLOB=y
80  CONFIG_IMX_SECO_DEK_ENCAP=y
81  CONFIG_FAT_WRITE=y
82
83- Kconfig:
84
85  ARM architecture -> Support i.MX8 AHAB features
86  ARM architecture -> Support the 'dek_blob' command
87  File systems -> Enable FAT filesystem support-> Enable FAT filesystem
88  write support
89
901.3 Enabling the encrypted boot support in CST
91-----------------------------------------------
92
93The encryption feature is not enabled by default in Code Signing tools (CST).
94The CST backend must be recompiled, execute the following commands to enable
95encryption support in CST:
96
97  $ sudo apt-get install libssl-dev openssl
98  $ cd <CST install directory>/code/back_end/src
99  $ gcc -o cst_encrypted -I ../hdr -L ../../../linux64/lib *.c
100    -lfrontend -lcrypto
101  $ cp cst_encrypted ../../../linux64/bin/
102
1031.4 Preparing the image container
104----------------------------------
105
106The container generation is explained in and mx8_mx8x_secure_boot.txt and
107mx8_mx8x_spl_secure_boot.txt guides. This document is based in imx-mkimage
108flash target (2 containers in flash.bin).
109
110- Assembly flash.bin binary:
111
112  $ make SOC=<SoC Name> flash
113
114The mkimage log is used during the encrypted boot procedure to create the
115Command Sequence File (CSF):
116
117  CST: CONTAINER 0 offset: 0x400
118  CST: CONTAINER 0: Signature Block: offset is at 0x590
119  DONE.
120  Note: Please copy image to offset: IVT_OFFSET + IMAGE_OFFSET
121
1221.6 Creating the CSF description to encrypt the 2nd container
123--------------------------------------------------------------
124
125The csf_enc_boot_image.txt available under ahab/csf_examples/ can be used as
126example for encrypting the flash.bin binary, the main change is the Install
127Secret Key command that must be added after Authenticate Data command.
128
129  [Install Secret Key]
130  Key = "dek.bin"
131  Key Length = 128
132  #Key Identifier = 0x1234CAFE
133  Image Indexes = 0xFFFFFFFE
134
135By default all images are encrypted and image indexes parameter can be used
136to mask the images indexes that must be encrypted, on this example only the
1372nd container will be encrypted.
138
139Optionally users can provide a key identifier that must match the value
140provided during the blob generation, by default its value is zero.
141
1421.7 Encrypting the 2nd container
143---------------------------------
144
145The image is encrypted using the Code Signing Tool. The tool generates the
146encrypted image and a random dek.bin file.
147
148- Encrypt flash.bin binary:
149
150  $ ./cst_encrypted -i csf_enc_boot_image.txt -o enc_flash.bin
151   The DEK BLOB must be inserted at offset 0x7c0 (its expected size is 72 bytes)
152   CSF Processed successfully and signed image available in enc_boot_image.bin
153
154The output log will be used in a later step to insert the DEK blob into the
155signature block.
156
1571.8 Generating the DEK Blob
158----------------------------
159
160The DEK must be encapsulated into a CAAM blob so it can be included into the
161final encrypted binary. The U-Boot provides a tool called dek_blob which is
162calling the SECO blob encapsulation API.
163
164Copy the dek.bin in SDCard FAT partition and run the following commands from
165U-Boot prompt:
166
167  => mmc list
168     FSL_SDHC: 1 (SD)
169     FSL_SDHC: 2
170  => fatload mmc 1:1 0x80280000 dek.bin
171  => dek_blob 0x80280000 0x80280100 128
172  => fatwrite mmc 1:1 0x80280100 dek_blob.bin 0x48
173
174In host PC copy the generated dek_blob.bin to the CST directory.
175
1761.9 Assembling the encrypted image
177-----------------------------------
178
179The DEK blob generated in the step above have to be inserted into the container
180signature block.
181
182The CSF log is used to determine the DEK Blob offset:
183
184  The DEK BLOB must be inserted at offset 0x7c0 (its expected size is 72 bytes)
185  CSF Processed successfully and signed image available in enc_boot_image.bin
186
187- Insert DEK Blob into container signature block:
188
189  $ dd if=dek_blob.bin of=enc_flash.bin bs=1 seek=$((0x7c0)) conv=notrunc
190
1911.10 Flashing the encrypted boot image
192---------------------------------------
193
194The same offset is used for encrypted boot images, in case booting from
195eMMC/SDCard the offset is 32K.
196
197- Flash encrypted image in SDCard:
198
199  $ sudo dd if=enc_flash.bin of=/dev/sd<x> bs=1K seek=32 && sync
200
2012.0 Encrypting a standalone container
202--------------------------------------
203
204CST is also able to encrypt additional images containers, the steps documented
205in this section are based in OS container but can be also applied to SPL
206targets and 3rd containers.
207
2082.1 Creating the OS container
209------------------------------
210
211As explained in mx8_mx8x_secure_boot.txt guide the imx-mkimage tool is used to
212generate an image container for OS images, the mkimage log is used during the
213encrypted boot procedure to create the Command Sequence File (CSF).
214
215- Creating OS container:
216
217  $ make SOC=<SoC Name> flash_kernel
218   ...
219   CST: CONTAINER 0 offset: 0x0
220   CST: CONTAINER 0: Signature Block: offset is at 0x110
221
2222.2 Creating the CSF description file for standalone container
223---------------------------------------------------------------
224
225The Image Indexes parameter is used to mask the images that are encrypted by
226CST, as a single container is used for OS images the Image Indexes command can
227be commented or set to 0xFFFFFFFF.
228
229  [Install Secret Key]
230  Key = "dek_os.bin"
231  Key Length = 128
232  #Key Identifier = 0x1234CAFE
233  Image Indexes = 0xFFFFFFFF
234
2352.3 Encrypting the standalone container
236----------------------------------------
237
238As explained in section 1.7 the CST generates the encrypted image and a random
239dek.bin file.
240
241- Encrypt the standalone container:
242
243  $ ./cst_encrypted -i csf_linux_img.txt -o enc_flash_os.bin
244   The DEK BLOB must be inserted at offset 0x340 (its expected size is 72 bytes)
245   CSF Processed successfully and signed image available in enc_flash_os.bin
246
247The output log will be used in a later step to insert the DEK blob into the
248signature block.
249
2502.4 Generating the DEK Blob for standalone container
251----------------------------------------------------
252
253Similar to section 1.8 the DEK must be encapsulated into a CAAM blob so it can
254be included into the final encrypted binary.
255
256Copy the dek_os.bin in SDCard FAT partition and run the following commands from
257U-Boot prompt:
258
259  => mmc list
260     FSL_SDHC: 1 (SD)
261     FSL_SDHC: 2
262  => fatload mmc 1:1 0x80280000 dek_os.bin
263  => dek_blob 0x80280000 0x80280100 128
264  => fatwrite mmc 1:1 0x80280100 dek_blob_os.bin 0x48
265
266In host PC copy the generated dek_blob_os.bin to the CST directory.
267
2682.5 Assembling the encrypted image
269-----------------------------------
270
271The DEK blob generated in the step above have to be inserted into the container
272signature block.
273
274The CSF log is used to determine the DEK Blob offset:
275
276   The DEK BLOB must be inserted at offset 0x340 (its expected size is 72 bytes)
277   CSF Processed successfully and signed image available in enc_flash_os.bin
278
279- Insert DEK Blob into container signature block:
280
281  $ dd if=dek_blob_os.bin of=enc_flash_os.bin bs=1 seek=$((0x340)) conv=notrunc
282
2832.6 Copy encrypted image to SDCard
284-----------------------------------
285
286The encrypted container can be copied to SDCard FAT partition, please note
287that U-Boot requires signed and encrypted containers to be named as
288os_cntr_signed.bin.
289
290  $ sudo cp enc_flash_os.bin /media/UserID/Boot\ imx8/os_cntr_signed.bin
291
292References:
293[1] SCFW API guide: "System Controller Firmware API Reference Guide - Rev 1.5"
294