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