Eric Lee / smarc-uboot

14
Download as
Browse Code ยป

Commit 7c46caba3b528b0399242f99612e5b094b1a4703

Authored by Clement Le Marquis
Committed by Ye Li
1 parent 6e9ceb2526
Exists in smarc_8mm-imx_v2018.03_4.14.98_2.0.0_ga and in 4 other branches smarc-imx6_v2018.03_4.14.98_2.0.0_ga, smarc-imx7_v2018.03_4.14.98_2.0.0_ga, smarc_8m-imx_v2018.03_4.14.98_2.0.0_ga, smarc_8m_00d0-imx_v2018.03_4.14.98_2.0.0_ga

MLK-20553-2 doc: imx: ahab: Add AHAB secure boot documentation for i.MX 8 and 8X families 

Add AHAB secure boot step-by-step guide for i.MX8 and i.MX8x families
devices.

Add 3 CSF example files:
- Example to sign flash.bin only using SRK keys.
- Example to sign flash.bin using a subordinate SGK key.
- Example to sign Linux image only using SRK keys.

Signed-off-by: Clement Le Marquis <clement.lemarquis@nxp.com>
Reviewed-by: Frank Zhang <frank.zhang@nxp.com>
Reviewed-by: Marius Grigoras <marius.grigoras@nxp.com>
Reviewed-by: Utkarsh Gupta <utkarsh.gupta@nxp.com>

Showing 4 changed files with 468 additions and 0 deletions Side-by-side Diff

doc/imx/hab/ahab/csf_examples/csf_boot_image.txt
Diff comments   View file @ 7c46cab
  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
doc/imx/hab/ahab/csf_examples/csf_boot_image_sgk.txt
Diff comments   View file @ 7c46cab
  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_ca_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 +# Optional subordinate SGK key
  18 +[Install Certificate]
  19 +# Public key certificate in PEM format
  20 +File = "./release/crts/SGK1_sha384_secp384r1_v3_usr_crt.pem"
  21 +# bitmask of the permissions
  22 +Permissions = 0x1
  23 +
  24 +[Authenticate Data]
  25 +# Binary to be signed generated by mkimage
  26 +File = "flash.bin"
  27 +# Offsets = Container header Signature block (printed out by mkimage)
  28 +Offsets = 0x400 0x590
doc/imx/hab/ahab/csf_examples/csf_linux_img.txt
Diff comments   View file @ 7c46cab
  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_os.bin"
  20 +# Offsets = Container header Signature block (printed out by mkimage)
  21 +Offsets = 0x0 0x110
doc/imx/hab/ahab/guides/mx8_mx8x_secure_boot.txt
Diff comments   View file @ 7c46cab
  1 + +=========================================================+
  2 + + i.MX 8, i.MX 8X Secure Boot guide using AHAB +
  3 + +=========================================================+
  4 +
  5 +1. AHAB secure boot process
  6 +----------------------------
  7 +
  8 +This document describes a step-by-step procedure on how to sign and
  9 +securely boot a flash.bin image. It is assumed that the reader is
  10 +familiar with basic AHAB concepts and with the PKI tree generation.
  11 +
  12 +It is also assumed that the reader is familiar with all pieces of
  13 +software needed. The procedure to built SCFW, ATF and download the
  14 +firmwares are out of scope of this document, please refer to the Linux
  15 +BSP Release Notes and AN12212[1] for further details.
  16 +
  17 +Details about AHAB can be found in the introduction_ahab.txt document
  18 +and in processors Security Reference Manual Document (SRM).
  19 +
  20 +1.1 Preparing the environment to build a secure boot image
  21 +-----------------------------------------------------------
  22 +
  23 +Before continuing, be sure to have already downloaded and built the
  24 +following:
  25 +
  26 +- imx-mkimage downloaded and built with i.MX 8 container support.
  27 +- SECO firmware downloaded.
  28 +- U-Boot downloaded and built. Please check section 1.2.
  29 +- ARM Trusted Firmware (ATF) downloaded and built for your target.
  30 +- System Controller Firmware (SCFW) downloaded and built for your board
  31 + with debug monitor enabled.
  32 +- Kernel image.
  33 +
  34 +You should also have downloaded the Code Signing Tool, available on NXP
  35 +website.
  36 +
  37 +In the following sections, <work> designates the repository where all
  38 +parts have been downloaded and built.
  39 +
  40 +1.2 Preparing U-Boot to support AHAB secure boot features
  41 +----------------------------------------------------------
  42 +
  43 +The U-Boot provides extra functions for AHAB, such as the ability to
  44 +authenticate additional container images by calling the SCU API
  45 +sc_misc_seco_authenticate() function.
  46 +
  47 +The support is enabled by adding CONFIG_AHAB_BOOT to the defconfig file used
  48 +for your target:
  49 +
  50 + - Defconfig:
  51 + CONFIG_AHAB_BOOT=y
  52 + - Kconfig:
  53 + ARM architecture -> Support i.MX 8 AHAB features
  54 +
  55 +1.3 Building an image supporting secure boot
  56 +---------------------------------------------
  57 +
  58 +The boot image is composed of different layers:
  59 +
  60 + +---------------------------+ <-- *start
  61 + | 1st Container header |
  62 + | and signature |
  63 + +---------------------------+
  64 + | Padding for 1kB alignment |
  65 + +---------------------------+ <-- *start + 0x400
  66 + | 2nd Container header |
  67 + | and signature |
  68 + +---------------------------+
  69 + | Padding |
  70 + +---------------------------+
  71 + | SECO FW |
  72 + +---------------------------+
  73 + | Padding |
  74 + +---------------------------+
  75 + | SCU FW with DDR |
  76 + | initialization Image |
  77 + | embedded |
  78 + +---------------------------+
  79 + | Cortex-M4 Image |
  80 + +---------------------------+
  81 + | Cortex-A bootloader |
  82 + +---------------------------+
  83 +
  84 +It contains two containers, one for the SECO firmware (AHAB), and one for
  85 +the SCFW, the ATF, U-Boot and M4 Image. They are preceded by their headers.
  86 +The first one, containing the SECO firmware image, is padded to 0x1000 to
  87 +fix the start address of the second one, which can contain one or multiple
  88 +images.
  89 +
  90 +If you are familiar with secure boot process with HABv4, you will notice
  91 +there is no need for CSF in this architecture. The CST is responsible to
  92 +handle the Signature block:
  93 +
  94 + +----------------------------+ ^
  95 + | | |
  96 + | | |
  97 + | Container header | |
  98 + | | |
  99 + | | |
  100 + +---+------------------------+ |
  101 + | S | Signature block header | | Signed
  102 + | i +------------------------+ |
  103 + | g | | |
  104 + | n | | |
  105 + | a | SRK table | |
  106 + | t | | |
  107 + | u | | |
  108 + | r +------------------------+ v
  109 + | e | Signature |
  110 + | +------------------------+
  111 + | b | |
  112 + | l | SGK Key |
  113 + | o | Certificate (optional) |
  114 + | c | |
  115 + | k | |
  116 + +---+------------------------+
  117 +
  118 +The certificate block is divided into:
  119 +
  120 + +---------------+ ^
  121 + | Public key | | Signed
  122 + | Permission | |
  123 + +---------------+ v
  124 + | Signature |
  125 + +---------------+
  126 +
  127 +The first block (public key permission) verify the Signature block
  128 +preceding (between SRK table and Certificate blocks), while the second
  129 +block (signature) is verified by the SRK table block.
  130 +
  131 +1.4 Prepare the boot image layout
  132 +----------------------------------
  133 +
  134 +To generate the flash.bin file:
  135 +
  136 +- On i.MX 8 QXP:
  137 +
  138 + $ cd <work>/imx-mkimage
  139 + $ make SOC=iMX8QX flash
  140 +
  141 +- On i.MX 8 QM:
  142 +
  143 + $ cd <work>/imx-mkimage
  144 + $ make SOC=iMX8QM flash
  145 +
  146 +If the command ends successfully, the end of the result should look
  147 +like:
  148 +
  149 + CST: CONTAINER 0 offset: 0x400
  150 + CST: CONTAINER 0: Signature Block: offset is at 0x590
  151 + DONE.
  152 + Note: Please copy image to offset: IVT_OFFSET + IMAGE_OFFSET
  153 +
  154 +Keep in mind the offsets above to be used with CST/CSF.
  155 +
  156 +Please note that on this example we not including an Cortex-M4 Image, on
  157 +i.MX8/8x MEK boards the SCU console may be replaced by the M4 console not
  158 +being possible to run the steps documented in section "1.5.5 Verify SECO
  159 +events".
  160 +
  161 +1.5 Secure boot setup with the CST
  162 +-----------------------------------
  163 +
  164 +1.5.1 Creating the CSF description file for the second container
  165 +-----------------------------------------------------------------
  166 +
  167 +The CSF contains all the commands that the AHAB executes during the secure
  168 +boot. These commands instruct the AHAB on which memory areas of the image
  169 +to authenticate, which keys to install, use and etc.
  170 +
  171 +CSF examples are available under doc/imx/hab/ahab/csf_examples/
  172 +directory.
  173 +
  174 +This csf_boot_image.txt file example should be updated with the offset values
  175 +of the 1.4 section and the path to your flash.bin file. It is the last part
  176 +of the file:
  177 +
  178 + [Authenticate Data]
  179 + # Binary to be signed generated by mkimage
  180 + File = "flash.bin"
  181 + # Offsets = Container header Signature block (printed out by mkimage)
  182 + Offsets = 0x400 0x590
  183 +
  184 +1.5.2 Signing the boot image
  185 +-----------------------------
  186 +
  187 +Now you use the CST to generate the signed boot image from the previously
  188 +created csf_boot_image.txt Commands Sequence File:
  189 +
  190 + $ cd <work>
  191 + $ ./release/linux64/bin/cst -i csf_boot_image.txt -o flash.signed.bin
  192 +
  193 +1.5.3 Flash the signed image
  194 +-----------------------------
  195 +
  196 +Write the signed U-Boot image:
  197 +
  198 + $ sudo dd if=flash.signed.bin of=/dev/sdX bs=1k seek=32 ; sync
  199 +
  200 +Then insert the SD Card into the board and plug your device to your computer
  201 +with an USB serial cable. When you power on the board, you should have two
  202 +serial consoles: one for U-Boot, another one for SCFW.
  203 +
  204 +Please note that SCU console may be replaced by the M4 console. In case the M4
  205 +image is needed, a base board will be required to access the SCU console.
  206 +
  207 +1.5.4 Programming SRK Hash
  208 +---------------------------
  209 +
  210 +As explained in introduction_ahab.txt document the SRK Hash fuse values are
  211 +generated by the srktool and should be programmed in the SoC SRK_HASH[511:0]
  212 +fuses.
  213 +
  214 +Be careful when programming these values, as this data is the basis for the
  215 +root of trust. An error in SRK Hash results in a part that does not boot.
  216 +
  217 +The U-Boot fuse tool can be used for programming eFuses on i.MX SoCs.
  218 +
  219 +- Dump SRK Hash fuses values in host machine:
  220 +
  221 + $ od -t x4 SRK_1_2_3_4_fuse.bin
  222 + 0000000 d436cc46 8ecccda9 b89e1601 5fada3db
  223 + 0000020 d454114a b6cd51f4 77384870 c50ee4b2
  224 + 0000040 a27e5132 eba887cf 592c1e2b bb501799
  225 + 0000060 ee702e07 cf8ce73e fb55e2d5 eba6bbd2
  226 +
  227 +- Program SRK_HASH[511:0] fuses:
  228 +
  229 + * On i.MX 8 QXP:
  230 +
  231 + => fuse prog 0 730 0xd436cc46
  232 + => fuse prog 0 731 0x8ecccda9
  233 + => fuse prog 0 732 0xb89e1601
  234 + => fuse prog 0 733 0x5fada3db
  235 + => fuse prog 0 734 0xd454114a
  236 + => fuse prog 0 735 0xb6cd51f4
  237 + => fuse prog 0 736 0x77384870
  238 + => fuse prog 0 737 0xc50ee4b2
  239 + => fuse prog 0 738 0xa27e5132
  240 + => fuse prog 0 739 0xeba887cf
  241 + => fuse prog 0 740 0x592c1e2b
  242 + => fuse prog 0 741 0xbb501799
  243 + => fuse prog 0 742 0xee702e07
  244 + => fuse prog 0 743 0xcf8ce73e
  245 + => fuse prog 0 744 0xfb55e2d5
  246 + => fuse prog 0 745 0xeba6bbd2
  247 +
  248 + * On i.MX 8 QM:
  249 +
  250 + => fuse prog 0 722 0xd436cc46
  251 + => fuse prog 0 723 0x8ecccda9
  252 + => fuse prog 0 724 0xb89e1601
  253 + => fuse prog 0 725 0x5fada3db
  254 + => fuse prog 0 726 0xd454114a
  255 + => fuse prog 0 727 0xb6cd51f4
  256 + => fuse prog 0 728 0x77384870
  257 + => fuse prog 0 729 0xc50ee4b2
  258 + => fuse prog 0 730 0xa27e5132
  259 + => fuse prog 0 731 0xeba887cf
  260 + => fuse prog 0 732 0x592c1e2b
  261 + => fuse prog 0 733 0xbb501799
  262 + => fuse prog 0 734 0xee702e07
  263 + => fuse prog 0 735 0xcf8ce73e
  264 + => fuse prog 0 736 0xfb55e2d5
  265 + => fuse prog 0 737 0xeba6bbd2
  266 +
  267 +1.5.5 Verify SECO events
  268 +-------------------------
  269 +
  270 +If the fuses have been written properly, there should be no SECO events after
  271 +boot. To validate this, power on the board, and run the following command on
  272 +the SCFW terminal:
  273 +
  274 + >$ seco events
  275 +
  276 +Nothing should be returned after this command. If you get an error, please
  277 +refer to examples below:
  278 +
  279 +0x0087EE00 = The container image is not signed.
  280 +0x0087FA00 = The container image was signed with wrong key which are not
  281 + matching the OTP SRK hashes.
  282 +
  283 +In case your SRK fuses are not programmed yet the event 0x0087FA00 may also
  284 +be displayed.
  285 +
  286 +Note: The SECO FW v1.1.0 is not logging an invalid image integrity as an event
  287 +in open mode, in case your image does not boot after moving the lifecycle
  288 +please review your image setup.
  289 +
  290 +1.5.6 Close the device
  291 +-----------------------
  292 +
  293 +After the device successfully boots a signed image without generating any
  294 +SECO security events, it is safe to close the device. The SECO lifecycle
  295 +should be changed from 32 (0x20) NXP open to 128 (0x80) OEM closed. Be
  296 +aware this step can damage your board if a previous step failed. It is
  297 +also irreversible. Run on the SCFW terminal:
  298 +
  299 + >$ seco lifecycle 16
  300 +
  301 +Now reboot the target, and on the same terminal, run:
  302 +
  303 + >$ seco info
  304 +
  305 +The lifecycle value should now be 128 (0x80) OEM closed.
  306 +
  307 +2. Authenticating the OS container
  308 +-----------------------------------
  309 +
  310 +Note that the following section is not mandatory. If you do not plan to
  311 +authenticate the kernel image, you can disable this behavior by setting
  312 +sec_boot=no in U-Boot environment variable.
  313 +
  314 +Note, you can also authenticate the OS image by running a U-Boot command:
  315 +
  316 + => auth_cntr <Container address>
  317 +
  318 +2.1 Prepare the OS container image
  319 +-----------------------------------
  320 +
  321 +You need to generate the OS container image. First, copy the binary previously
  322 +generated to the <work> directory to save it for later:
  323 +
  324 +- On i.MX 8 QXP
  325 +
  326 + $ cd <work>/imx-mkimage
  327 + $ cp iMX8QX/flash.bin ..
  328 + $ make SOC=iMX8QX flash_linux
  329 + $ mv i.MX8QX/flash.bin iMX8QX/flash_os.bin
  330 + $ cp iMX8QX/flash_os.bin ..
  331 +
  332 +- On i.MX 8 QM
  333 +
  334 + $ cd <work>/imx-mkimage
  335 + $ cp iMX8QM/flash.bin ..
  336 + $ make SOC=iMX8QM flash_linux
  337 + $ mv i.MX8QM/flash.bin iMX8QM/flash_os.bin
  338 + $ cp iMX8QM/flash_os.bin ..
  339 +
  340 +If the make command ends successfully, the end of the result should look
  341 +like:
  342 +
  343 + CST: CONTAINER 0 offset: 0x0
  344 + CST: CONTAINER 0: Signature Block: offset is at 0x110
  345 + DONE.
  346 + Note: Please copy image to offset: IVT_OFFSET + IMAGE_OFFSET
  347 +
  348 +Keep in mind the offsets above to be used with CST/CSF
  349 +
  350 +2.2 Creating the CSF description file for OS container image
  351 +-------------------------------------------------------------
  352 +
  353 +CSF examples are available under doc/imx/hab/ahab/csf_examples/
  354 +directory.
  355 +
  356 +This csf_linux_img.txt file example should be updated with the offset values
  357 +of the 2.1 chapter and the path to your flash_os.bin file. It it the last
  358 +part of the file:
  359 +
  360 + [Authenticate Data]
  361 + # Binary to be signed generated by mkimage
  362 + File = "flash_os.bin"
  363 + # Offsets = Container header Signature block (printed out by mkimage)
  364 + Offsets = 0x0 0x110
  365 +
  366 +2.3 Authenticating container image
  367 +-----------------------------------
  368 +
  369 +Now you use the CST to signed the OS image using the previously
  370 +created csf_linux_img.txt Commands Sequence File:
  371 +
  372 + $ cd <work>
  373 + $ ./release/linux64/bin/cst -i csf_linux_img.txt -o os_cntr_signed.bin
  374 +
  375 +2.4 Copy OS container
  376 +----------------------
  377 +
  378 +Mount the SD Card:
  379 +
  380 + $ sudo mount /dev/sdX1 partition
  381 +
  382 +Copy the OS signed image on the SD Card:
  383 +
  384 +- For i.MX 8 QXP
  385 +
  386 + $ sudo cp os_cntr_signed.bin /media/UserID/Boot\ imx8qx
  387 +
  388 +- For i.MX 8 QM
  389 +
  390 + $ sudo cp os_cntr_signed.bin /media/UserID/Boot\ imx8qm
  391 +
  392 +Finally:
  393 +
  394 + $ sudo umount partition
  395 +
  396 +References:
  397 +[1] AN12212: "Software Solutions for Migration Guide from Aarch32 to
  398 + Aarch64" - Rev 0."