Eric Lee / smarc-uboot

Download as
Browse Code ยป

Commit cba7ec79bb014fe7c107313187448c7c74a1de82

Authored by Breno Lima
Committed by Ye Li
1 parent a83dc28dee
Exists in smarc-imx_v2018.03_4.14.78_1.0.0_ga

MLK-20553-3 doc: imx: ahab: Add Secure Boot documentation for i.MX8 and i.MX8x SPL targets 

The current U-Boot implementation includes SPL targets for i.MX8QM and
i.MXQXP MEK boards:

- imx8qxp_mek_spl_defconfig
- imx8qxp_mek_spl_fspi_defconfig
- imx8qm_mek_spl_defconfig
- imx8qm_mek_spl_fspi_defconfig

The U-Boot proper and ATF are included in an additional container being
necessary a different procedure for signing the flash.bin image.

Add a step-by-step guide covering the signing procedure.
Add a CSF example for the 3rd container.

Signed-off-by: Breno Lima <breno.lima@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>
(cherry picked from commit 04505024d38eebbb5f39133b502c8e450ca40215)

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

doc/imx/hab/ahab/csf_examples/cst_uboot_atf.txt
Diff comments   View file @ cba7ec7
  1 +[Header]
  2 +Target = AHAB
  3 +Version = 1.0
  4 +
  5 +[Install SRK]
  6 +# SRK table generated by srktool
  7 +File = "../crts/SRK_1_2_3_4_table.bin"
  8 +# Public key certificate in PEM format on this example only using SRK key
  9 +Source = "../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 = "u-boot-atf-container.img"
  20 +# Offsets = Container header Signature block (printed out by mkimage)
  21 +Offsets = 0x0 0x110
doc/imx/hab/ahab/guides/mx8_mx8x_spl_secure_boot.txt
Diff comments   View file @ cba7ec7
  1 + +=========================================================+
  2 + + i.MX 8, i.MX 8X AHAB guide on SPL targets +
  3 + +=========================================================+
  4 +
  5 +1. AHAB secure boot process
  6 +----------------------------
  7 +
  8 +This document provides a step-by-step guide on how securely boot a flash.bin
  9 +image generated by Secondary Program Loader (SPL) targets. It is assumed that
  10 +the reader is familiar with basic AHAB concepts and with the PKI tree
  11 +generation.
  12 +
  13 +Details about AHAB can be found in the introduction_ahab.txt document and in
  14 +processors Security Reference Manual Document (SRM).
  15 +
  16 +1.1 Preparing the environment to build a secure boot image
  17 +-----------------------------------------------------------
  18 +
  19 +The following files and projects are used to prepare a secure boot image
  20 +for i.MX8/8x device:
  21 +
  22 +- imx-mkimage.
  23 +- SECO Firmware.
  24 +- U-Boot proper and SPL. (Please refer to section 1.2)
  25 +- ARM Trusted Firmware (ATF).
  26 +- System Controller Firmware (SCFW) with debug monitor enabled.
  27 +- Cortex M binary. (Optional)
  28 +- Kernel image. (Optional)
  29 +- Code signing tools (CST).
  30 +
  31 +The procedure to download the SECO firmware and build U-Boot, SCFW and ATF are
  32 +out of the scope of this document, please refer to the Linux BSP Release Notes
  33 +and AN12212[1] for further details.
  34 +
  35 +1.2 Preparing U-Boot to support AHAB secure boot features
  36 +----------------------------------------------------------
  37 +
  38 +The U-Boot provides an alternative SPL target for i.MX8 and i.MX8x devices. The
  39 +SPL is intended to be used by applications that requires a initial bootloader
  40 +prior to initialize the ARM Trusted Firmware (ATF) and the U-Boot proper.
  41 +
  42 +The U-Boot support AHAB functions that are essential to completely authenticate
  43 +the flash.bin image. On SPL targets only the SCFW, SPL and M4 IMG are
  44 +authenticated at SCU ROM level, in order to authenticate the ATF and U-Boot
  45 +proper it's necessary to call the SCU API sc_misc_seco_authenticate() function
  46 +at SPL level.
  47 +
  48 +The support is enabled by adding CONFIG_AHAB_BOOT to the defconfig file used
  49 +by your target:
  50 +
  51 + - Defconfig:
  52 + CONFIG_AHAB_BOOT=y
  53 + - Kconfig:
  54 + ARM architecture -> Support i.MX 8 AHAB features
  55 +
  56 +1.3 Building a SPL image supporting secure boot
  57 +------------------------------------------------
  58 +
  59 +The boot image generated by SPL targets has three containers:
  60 +
  61 + +---------------------------+ ---------
  62 + | 1st Container header | ^
  63 + | and signature | |
  64 + +---------------------------+ |
  65 + | Padding for 1kB alignment | |
  66 + +---------------------------+ |
  67 + | 2nd Container header | |
  68 + | and signature | |
  69 + +---------------------------+ |
  70 + | Padding | | Authenticated at
  71 + +---------------------------+ | SCU ROM Level
  72 + | SECO FW | |
  73 + +---------------------------+ |
  74 + | Padding | |
  75 + +---------------------------+ |
  76 + | SCU FW + DCD Table | |
  77 + +---------------------------+ |
  78 + | Cortex-M Image | |
  79 + +---------------------------+ |
  80 + | SPL Image | v
  81 + +---------------------------+ ---------
  82 + | 3rd Container header | ^
  83 + | and signature | |
  84 + +---------------------------+ |
  85 + | Padding | | Authenticated
  86 + +---------------------------+ | at SPL Level
  87 + | U-Boot Proper IMG | |
  88 + +---------------------------+ |
  89 + | ARM Trusted FW (ATF) | v
  90 + +---------------------------+ ---------
  91 +
  92 +The first container includes the SECO firmware which is signed using NXP keys,
  93 +this container is authenticated by SECO ROM at SCU ROM level.
  94 +
  95 +The second container includes the SCFW, SPL and Cortex M SW images which are
  96 +signed using OEM keys, this container is authenticated by SECO FW at SCU ROM
  97 +level.
  98 +
  99 +The third container includes the U-Boot proper and the ATF. The SPL is in
  100 +charge to load this container and also to interface with SCU requesting
  101 +SECO FW to authenticate the additional container.
  102 +
  103 +The signing procedure is slightly different when compared with HABv4 series. On
  104 +AHAB the signature is directly included in the container, the CST is
  105 +responsible to sign and handle the "Signature Block":
  106 +
  107 + +----------------------------+ ---------
  108 + | | ^
  109 + | | |
  110 + | Container header | |
  111 + | | |
  112 + | | |
  113 + +---+----------------------- + |
  114 + | S | Signature block header | | Signed
  115 + | i +------------------------+ |
  116 + | g | | |
  117 + | n | | |
  118 + | a | SRK table | |
  119 + | t | | |
  120 + | u | | v
  121 + | r +------------------------+ ---------
  122 + | e | Signature |
  123 + | +------------------------+
  124 + | B | |
  125 + | l | SGK Key |
  126 + | o | Certificate (optional) |
  127 + | c | |
  128 + | k | |
  129 + +---+------------------------+
  130 +
  131 +In case using the optional subordinate SGK key, the container signature is
  132 +verified against the SGK key certificate. This certificate is verified
  133 +against the SRK table.
  134 +
  135 +In case not using the subordinate key, the container signature is verified
  136 +against the SRK keys directly.
  137 +
  138 +1.4 Preparing the boot image
  139 +-----------------------------
  140 +
  141 +1.4.1 Preparing the 3rd container
  142 +----------------------------------
  143 +
  144 +The first step is to generate the third container including the U-Boot proper
  145 +and ATF images.
  146 +
  147 +The imx-mkimage project includes a target which only generates this third
  148 +container:
  149 +
  150 +- Generating the U-Boot proper + ATF container:
  151 +
  152 + $ make SOC=<SoC Name> u-boot-atf-container.img
  153 +
  154 +The mkimage log provides the container and signature block offsets used by the
  155 +CSF description file:
  156 +
  157 + CST: CONTAINER 0 offset: 0x0
  158 + CST: CONTAINER 0: Signature Block: offset is at 0x110
  159 +
  160 +The u-boot-atf-container.img file is the third container which have to be
  161 +signed using the Code Signing Tool (CST).
  162 +
  163 +1.4.2 Signing the 3rd container
  164 +--------------------------------
  165 +
  166 +The CSF description file contains all the commands that the SECO executes
  167 +during the secure boot procedure. These commands instruct the AHAB code on
  168 +which memory areas of the image to authenticate, which keys to install, use
  169 +and etc.
  170 +
  171 +CSF examples are available under doc/imx/hab/ahab/csf_examples/ directory.
  172 +
  173 +As explained in section above the mkimage log provides the container and
  174 +signature block offsets used by the CSF description file:
  175 +
  176 +- "Authenticate Data" command in cst_uboot_atf.txt file:
  177 +
  178 + [Authenticate Data]
  179 + # Binary to be signed generated by mkimage
  180 + File = "u-boot-atf-container.img"
  181 + # Offsets = Container header Signature block
  182 + Offsets = 0x0 0x110
  183 +
  184 +- Sign the third container:
  185 +
  186 + $ ./cst -i cst_uboot_atf.txt -o signed-u-boot-atf-container.img
  187 +
  188 +The signed-u-boot-atf-container.img have to be copied to imx-mkimage directory
  189 +and renamed to u-boot-atf-container.img.
  190 +
  191 +1.4.3 Preparing the flash.bin image
  192 +------------------------------------
  193 +
  194 +The signed 3rd container can be now used to create the final flash.bin image,
  195 +be sure that your signed container were successfully replaced and is named
  196 +as u-boot-atf-container.img.
  197 +
  198 +- Generating the flash.bin image:
  199 +
  200 + $ make SOC=<SoC Name> flash_spl_container
  201 +
  202 +The mkimage log provides the container and signature block offsets used by the
  203 +CSF description file:
  204 +
  205 + CST: CONTAINER 0 offset: 0x400
  206 + CST: CONTAINER 0: Signature Block: offset is at 0x510
  207 +
  208 +The flash.bin file include three containers and the second container have to be
  209 +signed using the Code Signing Tool (CST).
  210 +
  211 +1.4.4 Signing the flash.bin image
  212 +----------------------------------
  213 +
  214 +As mentioned above the CSF description file contains all the commands that
  215 +the SECO executes during the secure boot procedure.
  216 +
  217 +The procedure for signing the flash.bin image is similar as documented in
  218 +mx8_mx8x_secure_boot.txt guide.
  219 +
  220 +- "Authenticate Data" command in csf_boot_image.txt file:
  221 +
  222 + [Authenticate Data]
  223 + # Binary to be signed generated by mkimage
  224 + File = "flash.bin"
  225 + # Offsets = Container header Signature block
  226 + Offsets = 0x400 0x510
  227 +
  228 +- Sign the flash.bin container:
  229 +
  230 + $ ./cst -i csf_boot_image.txt -o signed-flash.bin
  231 +
  232 +The signed-flash.bin image contains all the signatures and can be flashed in
  233 +the device.
  234 +
  235 +1.5 Flashing the signed image
  236 +------------------------------
  237 +
  238 +After completing all steps in section "1.4 Preparing the boot image" the
  239 +signed flash.bin image can be flashed in the device:
  240 +
  241 + $ sudo dd if=signed-flash.bin of=/dev/sd<X> bs=1k seek=32 && sync
  242 +
  243 +For the next steps you should be able to see U-Boot and SCFW consoles in your
  244 +host PC. Please note that SCU console may be replaced by the M4 console, in
  245 +case the M4 image is needed a base board will be required to access the SCU
  246 +console.
  247 +
  248 +1.6 Programming SRK Hash
  249 +-------------------------
  250 +
  251 +As explained in introduction_ahab.txt document the SRK Hash fuse values are
  252 +generated by the srktool and should be programmed in the SoC SRK_HASH[511:0]
  253 +fuses.
  254 +
  255 +Be careful when programming these values, as this data is the basis
  256 +for the root of trust. An error in SRK Hash results in a part that
  257 +does not boot.
  258 +
  259 +The U-Boot fuse tool can be used for programming eFuses on i.MX SoCs.
  260 +
  261 +- Dump SRK Hash fuses values in host machine:
  262 +
  263 + $ od -t x4 SRK_1_2_3_4_fuse.bin
  264 + 0000000 d436cc46 8ecccda9 b89e1601 5fada3db
  265 + 0000020 d454114a b6cd51f4 77384870 c50ee4b2
  266 + 0000040 a27e5132 eba887cf 592c1e2b bb501799
  267 + 0000060 ee702e07 cf8ce73e fb55e2d5 eba6bbd2
  268 +
  269 +- Program SRK_HASH[511:0] fuses:
  270 +
  271 + * On i.MX 8 QXP:
  272 +
  273 + => fuse prog 0 730 0xd436cc46
  274 + => fuse prog 0 731 0x8ecccda9
  275 + => fuse prog 0 732 0xb89e1601
  276 + => fuse prog 0 733 0x5fada3db
  277 + => fuse prog 0 734 0xd454114a
  278 + => fuse prog 0 735 0xb6cd51f4
  279 + => fuse prog 0 736 0x77384870
  280 + => fuse prog 0 737 0xc50ee4b2
  281 + => fuse prog 0 738 0xa27e5132
  282 + => fuse prog 0 739 0xeba887cf
  283 + => fuse prog 0 740 0x592c1e2b
  284 + => fuse prog 0 741 0xbb501799
  285 + => fuse prog 0 742 0xee702e07
  286 + => fuse prog 0 743 0xcf8ce73e
  287 + => fuse prog 0 744 0xfb55e2d5
  288 + => fuse prog 0 745 0xeba6bbd2
  289 +
  290 + * On i.MX 8 QM:
  291 +
  292 + => fuse prog 0 722 0xd436cc46
  293 + => fuse prog 0 723 0x8ecccda9
  294 + => fuse prog 0 724 0xb89e1601
  295 + => fuse prog 0 725 0x5fada3db
  296 + => fuse prog 0 726 0xd454114a
  297 + => fuse prog 0 727 0xb6cd51f4
  298 + => fuse prog 0 728 0x77384870
  299 + => fuse prog 0 729 0xc50ee4b2
  300 + => fuse prog 0 730 0xa27e5132
  301 + => fuse prog 0 731 0xeba887cf
  302 + => fuse prog 0 732 0x592c1e2b
  303 + => fuse prog 0 733 0xbb501799
  304 + => fuse prog 0 734 0xee702e07
  305 + => fuse prog 0 735 0xcf8ce73e
  306 + => fuse prog 0 736 0xfb55e2d5
  307 + => fuse prog 0 737 0xeba6bbd2
  308 +
  309 +1.7 Verify SECO events
  310 +-----------------------
  311 +
  312 +If the fuses have been written properly, there should be no SECO events
  313 +after boot. To validate this, power on the board, and run the following
  314 +command on the SCFW terminal:
  315 +
  316 + >$ seco events
  317 +
  318 +Nothing should be returned after this command. If you get an error, please
  319 +refer to examples below:
  320 +
  321 +0x0087EE00 = The container image is not signed.
  322 +0x0087FA00 = The container image was signed with wrong key which are not
  323 + matching the OTP SRK hashes.
  324 +
  325 +In case your SRK fuses are not programmed yet the event 0x0087FA00 may also
  326 +be displayed.
  327 +
  328 +Note: The SECO FW v1.1.0 is not logging an invalid image integrity as an event
  329 +in open mode, in case your image does not boot after moving the lifecycle
  330 +please review your image setup.
  331 +
  332 +1.8 Close the device
  333 +---------------------
  334 +
  335 +After the device successfully boots a signed image without generating any
  336 +SECO security events, it is safe to close the device. The SECO lifecycle
  337 +should be changed from 32 (0x20) NXP open to 128 (0x80) OEM closed. Be
  338 +aware this step can damage your board if a previous step failed. It is
  339 +also irreversible. Run on the SCFW terminal:
  340 +
  341 + >$ seco lifecycle 16
  342 +
  343 +Now reboot the target, and on the same terminal, run:
  344 +
  345 + >$ seco info
  346 +
  347 +The lifecycle value should now be 128 (0x80) OEM closed.
  348 +
  349 +2. Authenticating the OS container
  350 +-----------------------------------
  351 +
  352 +The procedure for authenticating the OS container is similar as in Non-SPL
  353 +targets, for a complete procedure please refer to mx8_mx8x_secure_boot.txt
  354 +document available under doc/imx/hab/ahab/guides/ directory.
  355 +
  356 +References:
  357 +[1] AN12212: "Software Solutions for Migration Guide from Aarch32 to
  358 + Aarch64" - Rev 0."