Eric Lee / smarc-uboot

Download as
Browse Code ยป

Commit d857a7b9af7f3e518714eb7606f45a33c93d45a9

Authored by Breno Lima
Committed by Ye Li
1 parent 8f2a1e1901
Exists in smarc_8mq-imx_v2020.04_5.4.24_2.1.0 and in 3 other branches 8qm-imx_v2020.04_5.4.70_2.3.0, smarc-8m-android-10.0.0_2.6.0, smarc_8mm-imx_v2020.04_5.4.24_2.1.0

MLK-23092 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.

Signed-off-by: Catia Han <yaqian.han@nxp.com>
Signed-off-by: Breno Lima <breno.lima@nxp.com>
(cherry picked from commit dc18ee2c6c06ab9364dc08c70830acc8c6dcceac)

Showing 2 changed files with 320 additions and 0 deletions Side-by-side Diff

doc/imx/ahab/csf_examples/csf_enc_boot_image.txt
Diff comments   View file @ d857a7b
  1 +[Header]
  2 +Target = AHAB
  3 +Version = 1.0
  4 +
  5 +[Install SRK]
  6 +# SRK table generated by srktool
  7 +File = "./release/crts/SRK_1_2_3_4_table.bin"
  8 +# Public key certificate in PEM format
  9 +Source = "./release/crts/SRK1_sha384_secp384r1_v3_usr_crt.pem"
  10 +# Index of the public key certificate within the SRK table (0 .. 3)
  11 +Source index = 0
  12 +# Type of SRK set (NXP or OEM)
  13 +Source set = OEM
  14 +# bitmask of the revoked SRKs
  15 +Revocations = 0x0
  16 +
  17 +[Authenticate Data]
  18 +# Binary to be signed generated by mkimage
  19 +File = "flash.bin"
  20 +# Offsets = Container header Signature block (printed out by mkimage)
  21 +Offsets = 0x400 0x590
  22 +
  23 +[Install Secret Key]
  24 +Key = "dek.bin"
  25 +Key Length = 128
  26 +#Key Identifier = 0x1234CAFE
  27 +Image Indexes = 0xFFFFFFFE
doc/imx/ahab/guides/mx8_mx8x_encrypted_boot.txt
Diff comments   View file @ d857a7b
  1 + +=========================================================+
  2 + + i.MX 8, i.MX 8X Encrypted Boot guide using AHAB +
  3 + +=========================================================+
  4 +
  5 +1. AHAB Encrypted Boot process
  6 +-------------------------------
  7 +
  8 +This document describes a step-by-step procedure on how to encrypt and sign a
  9 +bootloader image for i.MX8/8x family devices. It is assumed that the reader
  10 +is familiar with basic AHAB concepts and has already closed the device,
  11 +step-by-step procedure can be found in mx8_mx8x_secure_boot.txt and
  12 +mx8_mx8x_spl_secure_boot.txt guides.
  13 +
  14 +The steps described in this document were based in i.MX8QM device, the same
  15 +concept can be applied to others processors in i.MX8/8X family devices.
  16 +
  17 +1.1 Understanding the encrypted image signature block
  18 +------------------------------------------------------
  19 +
  20 +As described in mx8_mx8x_secure_boot.txt guide a single binary is used to boot
  21 +the device. The imx-mkimage tool combines all the input images in a container
  22 +structure, generating a flash.bin binary.
  23 +
  24 +AHAB is able to decrypt image containers by calling SECO authentication
  25 +functions, the image must be encrypted by CST and the resulting DEK (Data
  26 +Encryption Key) must be encapsulated and included into the container signature
  27 +block:
  28 +
  29 + +----------------------------+
  30 + | | ^
  31 + | | |
  32 + | Container header | |
  33 + | | |
  34 + | | |
  35 + +---+------------------------+ |
  36 + | S | Signature block header | | Signed
  37 + | i +------------------------+ |
  38 + | g | | |
  39 + | n | | |
  40 + | a | SRK table | |
  41 + | t | | |
  42 + | u | | v
  43 + | r +------------------------+
  44 + | e | Signature |
  45 + | +------------------------+
  46 + | B | |
  47 + | l | SGK Key |
  48 + | o | Certificate (optional) |
  49 + | c | |
  50 + | k +------------------------+
  51 + | | DEK Blob |
  52 + +---+------------------------+
  53 +
  54 +1.1.1 Understanding and generating the DEK blob
  55 +------------------------------------------------
  56 +
  57 +The encrypted boot image requires a DEK blob on each time AHAB is used to
  58 +decrypt an image. The DEK blob is used as a security layer to wrap and store
  59 +the DEK off-chip using the OTPMK which is unique per device.
  60 +
  61 +On i.MX8/8x devices the DEK blob is generated using the SECO API, the following
  62 +funtion is available in U-Boot and can be executed through dek_blob command:
  63 +
  64 +- sc_seco_gen_key_blob(sc_ipc_t ipc, uint32_t id, sc_faddr_t load_addr,
  65 + sc_faddr_t export_addr, uint16_t max_size)
  66 +
  67 +Details in API usage can be found in SCFW API guide [1].
  68 +
  69 +1.2 Enabling the encrypted boot support in U-Boot
  70 +--------------------------------------------------
  71 +
  72 +For deploying an encrypted boot image additional U-Boot tools are needed,
  73 +please be sure to have the following features enabled, this can be achieved
  74 +by following one of the methods below:
  75 +
  76 +- Defconfig:
  77 +
  78 + CONFIG_AHAB_BOOT=y
  79 + CONFIG_CMD_DEKBLOB=y
  80 + CONFIG_IMX_SECO_DEK_ENCAP=y
  81 + CONFIG_FAT_WRITE=y
  82 +
  83 +- Kconfig:
  84 +
  85 + ARM architecture -> Support i.MX8 AHAB features
  86 + ARM architecture -> Support the 'dek_blob' command
  87 + File systems -> Enable FAT filesystem support-> Enable FAT filesystem
  88 + write support
  89 +
  90 +1.3 Enabling the encrypted boot support in CST
  91 +-----------------------------------------------
  92 +
  93 +The encryption feature is not enabled by default in Code Signing tools (CST).
  94 +The CST backend must be recompiled, execute the following commands to enable
  95 +encryption support in CST:
  96 +
  97 + $ sudo apt-get install libssl-dev openssl
  98 + $ cd <CST install directory>/code/back_end/src
  99 + $ gcc -o cst_encrypted -I ../hdr -L ../../../linux64/lib *.c
  100 + -lfrontend -lcrypto
  101 + $ cp cst_encrypted ../../../linux64/bin/
  102 +
  103 +1.4 Preparing the image container
  104 +----------------------------------
  105 +
  106 +The container generation is explained in and mx8_mx8x_secure_boot.txt and
  107 +mx8_mx8x_spl_secure_boot.txt guides. This document is based in imx-mkimage
  108 +flash target (2 containers in flash.bin).
  109 +
  110 +- Assembly flash.bin binary:
  111 +
  112 + $ make SOC=<SoC Name> flash
  113 +
  114 +The mkimage log is used during the encrypted boot procedure to create the
  115 +Command Sequence File (CSF):
  116 +
  117 + CST: CONTAINER 0 offset: 0x400
  118 + CST: CONTAINER 0: Signature Block: offset is at 0x590
  119 + DONE.
  120 + Note: Please copy image to offset: IVT_OFFSET + IMAGE_OFFSET
  121 +
  122 +1.6 Creating the CSF description to encrypt the 2nd container
  123 +--------------------------------------------------------------
  124 +
  125 +The csf_enc_boot_image.txt available under ahab/csf_examples/ can be used as
  126 +example for encrypting the flash.bin binary, the main change is the Install
  127 +Secret Key command that must be added after Authenticate Data command.
  128 +
  129 + [Install Secret Key]
  130 + Key = "dek.bin"
  131 + Key Length = 128
  132 + #Key Identifier = 0x1234CAFE
  133 + Image Indexes = 0xFFFFFFFE
  134 +
  135 +By default all images are encrypted and image indexes parameter can be used
  136 +to mask the images indexes that must be encrypted, on this example only the
  137 +2nd container will be encrypted.
  138 +
  139 +Optionally users can provide a key identifier that must match the value
  140 +provided during the blob generation, by default its value is zero.
  141 +
  142 +1.7 Encrypting the 2nd container
  143 +---------------------------------
  144 +
  145 +The image is encrypted using the Code Signing Tool. The tool generates the
  146 +encrypted image and a random dek.bin file.
  147 +
  148 +- Encrypt flash.bin binary:
  149 +
  150 + $ ./cst_encrypted -i csf_enc_boot_image.txt -o enc_flash.bin
  151 + The DEK BLOB must be inserted at offset 0x7c0 (its expected size is 72 bytes)
  152 + CSF Processed successfully and signed image available in enc_boot_image.bin
  153 +
  154 +The output log will be used in a later step to insert the DEK blob into the
  155 +signature block.
  156 +
  157 +1.8 Generating the DEK Blob
  158 +----------------------------
  159 +
  160 +The DEK must be encapsulated into a CAAM blob so it can be included into the
  161 +final encrypted binary. The U-Boot provides a tool called dek_blob which is
  162 +calling the SECO blob encapsulation API.
  163 +
  164 +Copy the dek.bin in SDCard FAT partition and run the following commands from
  165 +U-Boot prompt:
  166 +
  167 + => mmc list
  168 + FSL_SDHC: 1 (SD)
  169 + FSL_SDHC: 2
  170 + => fatload mmc 1:1 0x80280000 dek.bin
  171 + => dek_blob 0x80280000 0x80280100 128
  172 + => fatwrite mmc 1:1 0x80280100 dek_blob.bin 0x48
  173 +
  174 +In host PC copy the generated dek_blob.bin to the CST directory.
  175 +
  176 +1.9 Assembling the encrypted image
  177 +-----------------------------------
  178 +
  179 +The DEK blob generated in the step above have to be inserted into the container
  180 +signature block.
  181 +
  182 +The CSF log is used to determine the DEK Blob offset:
  183 +
  184 + The DEK BLOB must be inserted at offset 0x7c0 (its expected size is 72 bytes)
  185 + CSF Processed successfully and signed image available in enc_boot_image.bin
  186 +
  187 +- Insert DEK Blob into container signature block:
  188 +
  189 + $ dd if=dek_blob.bin of=enc_flash.bin bs=1 seek=$((0x7c0)) conv=notrunc
  190 +
  191 +1.10 Flashing the encrypted boot image
  192 +---------------------------------------
  193 +
  194 +The same offset is used for encrypted boot images, in case booting from
  195 +eMMC/SDCard the offset is 32K.
  196 +
  197 +- Flash encrypted image in SDCard:
  198 +
  199 + $ sudo dd if=enc_flash.bin of=/dev/sd<x> bs=1K seek=32 && sync
  200 +
  201 +2.0 Encrypting a standalone container
  202 +--------------------------------------
  203 +
  204 +CST is also able to encrypt additional images containers, the steps documented
  205 +in this section are based in OS container but can be also applied to SPL
  206 +targets and 3rd containers.
  207 +
  208 +2.1 Creating the OS container
  209 +------------------------------
  210 +
  211 +As explained in mx8_mx8x_secure_boot.txt guide the imx-mkimage tool is used to
  212 +generate an image container for OS images, the mkimage log is used during the
  213 +encrypted boot procedure to create the Command Sequence File (CSF).
  214 +
  215 +- Creating OS container:
  216 +
  217 + $ make SOC=<SoC Name> flash_kernel
  218 + ...
  219 + CST: CONTAINER 0 offset: 0x0
  220 + CST: CONTAINER 0: Signature Block: offset is at 0x110
  221 +
  222 +2.2 Creating the CSF description file for standalone container
  223 +---------------------------------------------------------------
  224 +
  225 +The Image Indexes parameter is used to mask the images that are encrypted by
  226 +CST, as a single container is used for OS images the Image Indexes command can
  227 +be commented or set to 0xFFFFFFFF.
  228 +
  229 + [Install Secret Key]
  230 + Key = "dek_os.bin"
  231 + Key Length = 128
  232 + #Key Identifier = 0x1234CAFE
  233 + Image Indexes = 0xFFFFFFFF
  234 +
  235 +2.3 Encrypting the standalone container
  236 +----------------------------------------
  237 +
  238 +As explained in section 1.7 the CST generates the encrypted image and a random
  239 +dek.bin file.
  240 +
  241 +- Encrypt the standalone container:
  242 +
  243 + $ ./cst_encrypted -i csf_linux_img.txt -o enc_flash_os.bin
  244 + The DEK BLOB must be inserted at offset 0x340 (its expected size is 72 bytes)
  245 + CSF Processed successfully and signed image available in enc_flash_os.bin
  246 +
  247 +The output log will be used in a later step to insert the DEK blob into the
  248 +signature block.
  249 +
  250 +2.4 Generating the DEK Blob for standalone container
  251 +----------------------------------------------------
  252 +
  253 +Similar to section 1.8 the DEK must be encapsulated into a CAAM blob so it can
  254 +be included into the final encrypted binary.
  255 +
  256 +Copy the dek_os.bin in SDCard FAT partition and run the following commands from
  257 +U-Boot prompt:
  258 +
  259 + => mmc list
  260 + FSL_SDHC: 1 (SD)
  261 + FSL_SDHC: 2
  262 + => fatload mmc 1:1 0x80280000 dek_os.bin
  263 + => dek_blob 0x80280000 0x80280100 128
  264 + => fatwrite mmc 1:1 0x80280100 dek_blob_os.bin 0x48
  265 +
  266 +In host PC copy the generated dek_blob_os.bin to the CST directory.
  267 +
  268 +2.5 Assembling the encrypted image
  269 +-----------------------------------
  270 +
  271 +The DEK blob generated in the step above have to be inserted into the container
  272 +signature block.
  273 +
  274 +The CSF log is used to determine the DEK Blob offset:
  275 +
  276 + The DEK BLOB must be inserted at offset 0x340 (its expected size is 72 bytes)
  277 + CSF Processed successfully and signed image available in enc_flash_os.bin
  278 +
  279 +- Insert DEK Blob into container signature block:
  280 +
  281 + $ dd if=dek_blob_os.bin of=enc_flash_os.bin bs=1 seek=$((0x340)) conv=notrunc
  282 +
  283 +2.6 Copy encrypted image to SDCard
  284 +-----------------------------------
  285 +
  286 +The encrypted container can be copied to SDCard FAT partition, please note
  287 +that U-Boot requires signed and encrypted containers to be named as
  288 +os_cntr_signed.bin.
  289 +
  290 + $ sudo cp enc_flash_os.bin /media/UserID/Boot\ imx8/os_cntr_signed.bin
  291 +
  292 +References:
  293 +[1] SCFW API guide: "System Controller Firmware API Reference Guide - Rev 1.5"