From: Breno Lima breno.lima@nxp.com
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.
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 --- doc/imx/ahab/csf_examples/csf_enc_boot_image.txt | 27 +++ doc/imx/ahab/guides/mx8_mx8x_encrypted_boot.txt | 293 +++++++++++++++++++++++ 2 files changed, 320 insertions(+) create mode 100644 doc/imx/ahab/csf_examples/csf_enc_boot_image.txt create mode 100644 doc/imx/ahab/guides/mx8_mx8x_encrypted_boot.txt
diff --git a/doc/imx/ahab/csf_examples/csf_enc_boot_image.txt b/doc/imx/ahab/csf_examples/csf_enc_boot_image.txt new file mode 100644 index 0000000000..6c70db657b --- /dev/null +++ b/doc/imx/ahab/csf_examples/csf_enc_boot_image.txt @@ -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 diff --git a/doc/imx/ahab/guides/mx8_mx8x_encrypted_boot.txt b/doc/imx/ahab/guides/mx8_mx8x_encrypted_boot.txt new file mode 100644 index 0000000000..dfea4c8277 --- /dev/null +++ b/doc/imx/ahab/guides/mx8_mx8x_encrypted_boot.txt @@ -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"