mirror of
https://github.com/smaeul/u-boot.git
synced 2025-10-30 19:48:19 +00:00
ba13973479
Add AHAB encrypted boot documentation for i.MX8/8x family devices covering the following topics: - How to encrypt and sign the 2nd container in flash.bin image. - How to encrypt and sign a standalone container image. Include a CSF example to encrypt 2nd container in flash.bin image. Reviewed-by: Fabio Estevam <festevam@gmail.com> Signed-off-by: Catia Han <yaqian.han@nxp.com> Signed-off-by: Breno Lima <breno.lima@nxp.com> Signed-off-by: Peng Fan <peng.fan@nxp.com>
294 lines
10 KiB
Plaintext
294 lines
10 KiB
Plaintext
+=========================================================+
|
|
+ i.MX 8, i.MX 8X Encrypted Boot guide using AHAB +
|
|
+=========================================================+
|
|
|
|
1. AHAB Encrypted Boot process
|
|
-------------------------------
|
|
|
|
This document describes a step-by-step procedure on how to encrypt and sign a
|
|
bootloader image for i.MX8/8x family devices. It is assumed that the reader
|
|
is familiar with basic AHAB concepts and has already closed the device,
|
|
step-by-step procedure can be found in mx8_mx8x_secure_boot.txt and
|
|
mx8_mx8x_spl_secure_boot.txt guides.
|
|
|
|
The steps described in this document were based in i.MX8QM device, the same
|
|
concept can be applied to others processors in i.MX8/8X family devices.
|
|
|
|
1.1 Understanding the encrypted image signature block
|
|
------------------------------------------------------
|
|
|
|
As described in mx8_mx8x_secure_boot.txt guide a single binary is used to boot
|
|
the device. The imx-mkimage tool combines all the input images in a container
|
|
structure, generating a flash.bin binary.
|
|
|
|
AHAB is able to decrypt image containers by calling SECO authentication
|
|
functions, the image must be encrypted by CST and the resulting DEK (Data
|
|
Encryption Key) must be encapsulated and included into the container signature
|
|
block:
|
|
|
|
+----------------------------+
|
|
| | ^
|
|
| | |
|
|
| Container header | |
|
|
| | |
|
|
| | |
|
|
+---+------------------------+ |
|
|
| S | Signature block header | | Signed
|
|
| i +------------------------+ |
|
|
| g | | |
|
|
| n | | |
|
|
| a | SRK table | |
|
|
| t | | |
|
|
| u | | v
|
|
| r +------------------------+
|
|
| e | Signature |
|
|
| +------------------------+
|
|
| B | |
|
|
| l | SGK Key |
|
|
| o | Certificate (optional) |
|
|
| c | |
|
|
| k +------------------------+
|
|
| | DEK Blob |
|
|
+---+------------------------+
|
|
|
|
1.1.1 Understanding and generating the DEK blob
|
|
------------------------------------------------
|
|
|
|
The encrypted boot image requires a DEK blob on each time AHAB is used to
|
|
decrypt an image. The DEK blob is used as a security layer to wrap and store
|
|
the DEK off-chip using the OTPMK which is unique per device.
|
|
|
|
On i.MX8/8x devices the DEK blob is generated using the SECO API, the following
|
|
funtion is available in U-Boot and can be executed through dek_blob command:
|
|
|
|
- sc_seco_gen_key_blob(sc_ipc_t ipc, uint32_t id, sc_faddr_t load_addr,
|
|
sc_faddr_t export_addr, uint16_t max_size)
|
|
|
|
Details in API usage can be found in SCFW API guide [1].
|
|
|
|
1.2 Enabling the encrypted boot support in U-Boot
|
|
--------------------------------------------------
|
|
|
|
For deploying an encrypted boot image additional U-Boot tools are needed,
|
|
please be sure to have the following features enabled, this can be achieved
|
|
by following one of the methods below:
|
|
|
|
- Defconfig:
|
|
|
|
CONFIG_AHAB_BOOT=y
|
|
CONFIG_CMD_DEKBLOB=y
|
|
CONFIG_IMX_SECO_DEK_ENCAP=y
|
|
CONFIG_FAT_WRITE=y
|
|
|
|
- Kconfig:
|
|
|
|
ARM architecture -> Support i.MX8 AHAB features
|
|
ARM architecture -> Support the 'dek_blob' command
|
|
File systems -> Enable FAT filesystem support-> Enable FAT filesystem
|
|
write support
|
|
|
|
1.3 Enabling the encrypted boot support in CST
|
|
-----------------------------------------------
|
|
|
|
The encryption feature is not enabled by default in Code Signing tools (CST).
|
|
The CST backend must be recompiled, execute the following commands to enable
|
|
encryption support in CST:
|
|
|
|
$ sudo apt-get install libssl-dev openssl
|
|
$ cd <CST install directory>/code/back_end/src
|
|
$ gcc -o cst_encrypted -I ../hdr -L ../../../linux64/lib *.c
|
|
-lfrontend -lcrypto
|
|
$ cp cst_encrypted ../../../linux64/bin/
|
|
|
|
1.4 Preparing the image container
|
|
----------------------------------
|
|
|
|
The container generation is explained in and mx8_mx8x_secure_boot.txt and
|
|
mx8_mx8x_spl_secure_boot.txt guides. This document is based in imx-mkimage
|
|
flash target (2 containers in flash.bin).
|
|
|
|
- Assembly flash.bin binary:
|
|
|
|
$ make SOC=<SoC Name> flash
|
|
|
|
The mkimage log is used during the encrypted boot procedure to create the
|
|
Command Sequence File (CSF):
|
|
|
|
CST: CONTAINER 0 offset: 0x400
|
|
CST: CONTAINER 0: Signature Block: offset is at 0x590
|
|
DONE.
|
|
Note: Please copy image to offset: IVT_OFFSET + IMAGE_OFFSET
|
|
|
|
1.6 Creating the CSF description to encrypt the 2nd container
|
|
--------------------------------------------------------------
|
|
|
|
The csf_enc_boot_image.txt available under ahab/csf_examples/ can be used as
|
|
example for encrypting the flash.bin binary, the main change is the Install
|
|
Secret Key command that must be added after Authenticate Data command.
|
|
|
|
[Install Secret Key]
|
|
Key = "dek.bin"
|
|
Key Length = 128
|
|
#Key Identifier = 0x1234CAFE
|
|
Image Indexes = 0xFFFFFFFE
|
|
|
|
By default all images are encrypted and image indexes parameter can be used
|
|
to mask the images indexes that must be encrypted, on this example only the
|
|
2nd container will be encrypted.
|
|
|
|
Optionally users can provide a key identifier that must match the value
|
|
provided during the blob generation, by default its value is zero.
|
|
|
|
1.7 Encrypting the 2nd container
|
|
---------------------------------
|
|
|
|
The image is encrypted using the Code Signing Tool. The tool generates the
|
|
encrypted image and a random dek.bin file.
|
|
|
|
- Encrypt flash.bin binary:
|
|
|
|
$ ./cst_encrypted -i csf_enc_boot_image.txt -o enc_flash.bin
|
|
The DEK BLOB must be inserted at offset 0x7c0 (its expected size is 72 bytes)
|
|
CSF Processed successfully and signed image available in enc_boot_image.bin
|
|
|
|
The output log will be used in a later step to insert the DEK blob into the
|
|
signature block.
|
|
|
|
1.8 Generating the DEK Blob
|
|
----------------------------
|
|
|
|
The DEK must be encapsulated into a CAAM blob so it can be included into the
|
|
final encrypted binary. The U-Boot provides a tool called dek_blob which is
|
|
calling the SECO blob encapsulation API.
|
|
|
|
Copy the dek.bin in SDCard FAT partition and run the following commands from
|
|
U-Boot prompt:
|
|
|
|
=> mmc list
|
|
FSL_SDHC: 1 (SD)
|
|
FSL_SDHC: 2
|
|
=> fatload mmc 1:1 0x80280000 dek.bin
|
|
=> dek_blob 0x80280000 0x80280100 128
|
|
=> fatwrite mmc 1:1 0x80280100 dek_blob.bin 0x48
|
|
|
|
In host PC copy the generated dek_blob.bin to the CST directory.
|
|
|
|
1.9 Assembling the encrypted image
|
|
-----------------------------------
|
|
|
|
The DEK blob generated in the step above have to be inserted into the container
|
|
signature block.
|
|
|
|
The CSF log is used to determine the DEK Blob offset:
|
|
|
|
The DEK BLOB must be inserted at offset 0x7c0 (its expected size is 72 bytes)
|
|
CSF Processed successfully and signed image available in enc_boot_image.bin
|
|
|
|
- Insert DEK Blob into container signature block:
|
|
|
|
$ dd if=dek_blob.bin of=enc_flash.bin bs=1 seek=$((0x7c0)) conv=notrunc
|
|
|
|
1.10 Flashing the encrypted boot image
|
|
---------------------------------------
|
|
|
|
The same offset is used for encrypted boot images, in case booting from
|
|
eMMC/SDCard the offset is 32K.
|
|
|
|
- Flash encrypted image in SDCard:
|
|
|
|
$ sudo dd if=enc_flash.bin of=/dev/sd<x> bs=1K seek=32 && sync
|
|
|
|
2.0 Encrypting a standalone container
|
|
--------------------------------------
|
|
|
|
CST is also able to encrypt additional images containers, the steps documented
|
|
in this section are based in OS container but can be also applied to SPL
|
|
targets and 3rd containers.
|
|
|
|
2.1 Creating the OS container
|
|
------------------------------
|
|
|
|
As explained in mx8_mx8x_secure_boot.txt guide the imx-mkimage tool is used to
|
|
generate an image container for OS images, the mkimage log is used during the
|
|
encrypted boot procedure to create the Command Sequence File (CSF).
|
|
|
|
- Creating OS container:
|
|
|
|
$ make SOC=<SoC Name> flash_kernel
|
|
...
|
|
CST: CONTAINER 0 offset: 0x0
|
|
CST: CONTAINER 0: Signature Block: offset is at 0x110
|
|
|
|
2.2 Creating the CSF description file for standalone container
|
|
---------------------------------------------------------------
|
|
|
|
The Image Indexes parameter is used to mask the images that are encrypted by
|
|
CST, as a single container is used for OS images the Image Indexes command can
|
|
be commented or set to 0xFFFFFFFF.
|
|
|
|
[Install Secret Key]
|
|
Key = "dek_os.bin"
|
|
Key Length = 128
|
|
#Key Identifier = 0x1234CAFE
|
|
Image Indexes = 0xFFFFFFFF
|
|
|
|
2.3 Encrypting the standalone container
|
|
----------------------------------------
|
|
|
|
As explained in section 1.7 the CST generates the encrypted image and a random
|
|
dek.bin file.
|
|
|
|
- Encrypt the standalone container:
|
|
|
|
$ ./cst_encrypted -i csf_linux_img.txt -o enc_flash_os.bin
|
|
The DEK BLOB must be inserted at offset 0x340 (its expected size is 72 bytes)
|
|
CSF Processed successfully and signed image available in enc_flash_os.bin
|
|
|
|
The output log will be used in a later step to insert the DEK blob into the
|
|
signature block.
|
|
|
|
2.4 Generating the DEK Blob for standalone container
|
|
----------------------------------------------------
|
|
|
|
Similar to section 1.8 the DEK must be encapsulated into a CAAM blob so it can
|
|
be included into the final encrypted binary.
|
|
|
|
Copy the dek_os.bin in SDCard FAT partition and run the following commands from
|
|
U-Boot prompt:
|
|
|
|
=> mmc list
|
|
FSL_SDHC: 1 (SD)
|
|
FSL_SDHC: 2
|
|
=> fatload mmc 1:1 0x80280000 dek_os.bin
|
|
=> dek_blob 0x80280000 0x80280100 128
|
|
=> fatwrite mmc 1:1 0x80280100 dek_blob_os.bin 0x48
|
|
|
|
In host PC copy the generated dek_blob_os.bin to the CST directory.
|
|
|
|
2.5 Assembling the encrypted image
|
|
-----------------------------------
|
|
|
|
The DEK blob generated in the step above have to be inserted into the container
|
|
signature block.
|
|
|
|
The CSF log is used to determine the DEK Blob offset:
|
|
|
|
The DEK BLOB must be inserted at offset 0x340 (its expected size is 72 bytes)
|
|
CSF Processed successfully and signed image available in enc_flash_os.bin
|
|
|
|
- Insert DEK Blob into container signature block:
|
|
|
|
$ dd if=dek_blob_os.bin of=enc_flash_os.bin bs=1 seek=$((0x340)) conv=notrunc
|
|
|
|
2.6 Copy encrypted image to SDCard
|
|
-----------------------------------
|
|
|
|
The encrypted container can be copied to SDCard FAT partition, please note
|
|
that U-Boot requires signed and encrypted containers to be named as
|
|
os_cntr_signed.bin.
|
|
|
|
$ sudo cp enc_flash_os.bin /media/UserID/Boot\ imx8/os_cntr_signed.bin
|
|
|
|
References:
|
|
[1] SCFW API guide: "System Controller Firmware API Reference Guide - Rev 1.5"
|