123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293 |
- +=========================================================+
- + 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"
|