mirror of
https://github.com/u-boot/u-boot.git
synced 2024-11-24 04:34:22 +08:00
doc: ahab: Add encrypted boot documentation for i.MX8/8x devices
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>
This commit is contained in:
Breno Lima
Stefano Babic
parent
7247974643
commit
ba13973479
27
doc/imx/ahab/csf_examples/csf_enc_boot_image.txt
Normal file
27
doc/imx/ahab/csf_examples/csf_enc_boot_image.txt
Normal file
@ -0,0 +1,27 @@
|
||||
[Header]
|
||||
Target = AHAB
|
||||
Version = 1.0
|
||||
|
||||
[Install SRK]
|
||||
# SRK table generated by srktool
|
||||
File = "./release/crts/SRK_1_2_3_4_table.bin"
|
||||
# Public key certificate in PEM format
|
||||
Source = "./release/crts/SRK1_sha384_secp384r1_v3_usr_crt.pem"
|
||||
# Index of the public key certificate within the SRK table (0 .. 3)
|
||||
Source index = 0
|
||||
# Type of SRK set (NXP or OEM)
|
||||
Source set = OEM
|
||||
# bitmask of the revoked SRKs
|
||||
Revocations = 0x0
|
||||
|
||||
[Authenticate Data]
|
||||
# Binary to be signed generated by mkimage
|
||||
File = "flash.bin"
|
||||
# Offsets = Container header Signature block (printed out by mkimage)
|
||||
Offsets = 0x400 0x590
|
||||
|
||||
[Install Secret Key]
|
||||
Key = "dek.bin"
|
||||
Key Length = 128
|
||||
#Key Identifier = 0x1234CAFE
|
||||
Image Indexes = 0xFFFFFFFE
|
||||
293
doc/imx/ahab/guides/mx8_mx8x_encrypted_boot.txt
Normal file
293
doc/imx/ahab/guides/mx8_mx8x_encrypted_boot.txt
Normal file
@ -0,0 +1,293 @@
|
||||
+=========================================================+
|
||||
+ 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"
|
||||
Loading…
Reference in New Issue
Block a user