Eric Lee / smarc-uboot

Download as
Browse Code ยป

Commit cfb50207e5d75e86088e4bbb8f94614ce41b7afb

Authored by Breno Matheus Lima
Committed by Stefano Babic
1 parent 872cfa20cd
Exists in smarc_8mq_lf_v2020.04 and in 11 other branches 8qm-imx_v2020.04_5.4.70_2.3.0, emb_lf_v2022.04, pitx_8mp_lf_v2020.04, smarc-8m-android-10.0.0_2.6.0, smarc-8m-android-11.0.0_2.0.0, smarc-8mp-android-11.0.0_2.0.0, smarc_8m-imx_v2019.04_4.19.35_1.1.0, smarc_8mm-imx_v2019.04_4.19.35_1.1.0, smarc_8mm-imx_v2020.04_5.4.24_2.1.0, smarc_8mp_lf_v2020.04, smarc_8mq-imx_v2020.04_5.4.24_2.1.0

doc: imx: habv4: Add Secure Boot guide for i.MX6 and i.MX7 SPL targets 

The current U-Boot implementation includes SPL targets for
some NXP development boards:

- mx6sabreauto_defconfig
- mx6sabresd_defconfig
- mx6ul_14x14_evk_defconfig
- mx6ul_9x9_evk_defconfig

Add additional steps needed to completly secure the
bootloader image.

Signed-off-by: Breno Lima <breno.lima@nxp.com>

Showing 1 changed file with 181 additions and 0 deletions Side-by-side Diff

doc/imx/habv4/guides/mx6_mx7_spl_secure_boot.txt
Diff comments   View file @ cfb5020
  1 + +===============================================================+
  2 + + i.MX6, i.MX7 U-Boot HABv4 Secure Boot guide for SPL targets +
  3 + +===============================================================+
  4 +
  5 +1. HABv4 secure boot process
  6 +-----------------------------
  7 +
  8 +This document is an addendum of mx6_mx7_secure_boot.txt guide describing a
  9 +step-by-step procedure on how to sign and securely boot an U-Boot image for
  10 +SPL targets.
  11 +
  12 +Details about HAB can be found in the application note AN4581[1] and in the
  13 +introduction_habv4.txt document.
  14 +
  15 +1.1 Building a SPL target supporting secure boot
  16 +-------------------------------------------------
  17 +
  18 +The U-Boot provides Second Program Loader (SPL) support which generates two
  19 +final images, SPL and U-Boot proper. The HABv4 can be used to authenticate
  20 +both binaries.
  21 +
  22 +Out of reset the ROM code authenticates the SPL which is responsible for
  23 +initializing essential features such as DDR, UART, PMIC and clock
  24 +enablement. Once the DDR is available, the SPL code loads the U-Boot proper
  25 +image to its specific execution address and call the HAB APIs to extend the
  26 +root of trust.
  27 +
  28 +The U-Boot provides support to secure boot configuration and also provide
  29 +access to the HAB APIs exposed by the ROM vector table, the support is
  30 +enabled by selecting the CONFIG_SECURE_BOOT option.
  31 +
  32 +When built with this configuration the U-Boot correctly pads the final SPL
  33 +image by aligning to the next 0xC00 address, so the CSF signature data
  34 +generated by CST can be concatenated to the image.
  35 +
  36 +The U-Boot also append an Image Vector Table (IVT) in the final U-Boot proper
  37 +binary (u-boot-ivt.img) so it can be used by HAB API in a post ROM stage.
  38 +
  39 +The diagram below illustrate a signed SPL image layout:
  40 +
  41 + ------- +-----------------------------+ <-- *start
  42 + ^ | Image Vector Table |
  43 + | +-----------------------------+ <-- *boot_data
  44 + | | Boot Data |
  45 + | +-----------------------------+
  46 + Signed | | Padding |
  47 + Data | +-----------------------------+ <-- *entry
  48 + | | |
  49 + | | SPL |
  50 + | | |
  51 + | +-----------------------------+
  52 + v | Padding |
  53 + ------- +-----------------------------+ <-- *csf
  54 + | |
  55 + | Command Sequence File (CSF) |
  56 + | |
  57 + +-----------------------------+
  58 + | Padding (optional) |
  59 + +-----------------------------+
  60 +
  61 +The diagram below illustrate a signed u-boot-ivt.img image layout:
  62 +
  63 + ------- +-----------------------------+ <-- *load_address
  64 + ^ | |
  65 + | | |
  66 + | | u-boot.img |
  67 + Signed | | |
  68 + Data | | |
  69 + | +-----------------------------+
  70 + | | Padding Next Boundary |
  71 + | +-----------------------------+ <-- *ivt
  72 + v | Image Vector Table |
  73 + ------- +-----------------------------+ <-- *csf
  74 + | |
  75 + | Command Sequence File (CSF) |
  76 + | |
  77 + +-----------------------------+
  78 + | Padding (optional) |
  79 + +-----------------------------+
  80 +
  81 +1.2 Enabling the secure boot support
  82 +-------------------------------------
  83 +
  84 +The first step is to generate an U-Boot image supporting the HAB features
  85 +mentioned above, this can be achieved by adding CONFIG_SECURE_BOOT to the
  86 +build configuration:
  87 +
  88 +- Defconfig:
  89 +
  90 + CONFIG_SECURE_BOOT=y
  91 +
  92 +- Kconfig:
  93 +
  94 + ARM architecture -> Support i.MX HAB features
  95 +
  96 +1.3 Creating the CSF description file
  97 +--------------------------------------
  98 +
  99 +The CSF contains all the commands that the HAB executes during the secure
  100 +boot. These commands instruct the HAB code on which memory areas of the image
  101 +to authenticate, which keys to install, use and etc.
  102 +
  103 +CSF examples are available under doc/imx/habv4/csf_examples/ directory.
  104 +
  105 +Build logs containing the "Authenticate Data" parameters are available after
  106 +the U-Boot build, the example below is a log for mx6sabresd_defconfig target:
  107 +
  108 +- SPL build log:
  109 +
  110 + $ cat SPL.log
  111 + Image Type: Freescale IMX Boot Image
  112 + Image Ver: 2 (i.MX53/6/7 compatible)
  113 + Mode: DCD
  114 + Data Size: 69632 Bytes = 68.00 KiB = 0.07 MiB
  115 + Load Address: 00907420
  116 + Entry Point: 00908000
  117 + HAB Blocks: 0x00907400 0x00000000 0x0000ec00
  118 +
  119 +- u-boot-ivt.img build log:
  120 +
  121 + $ cat u-boot-ivt.img.log
  122 + Image Name: U-Boot 2019.01-00003-g78ee492eb3
  123 + Created: Mon Jan 14 17:58:10 2019
  124 + Image Type: ARM U-Boot Firmware with HABv4 IVT (uncompressed)
  125 + Data Size: 458688 Bytes = 447.94 KiB = 0.44 MiB
  126 + Load Address: 17800000
  127 + Entry Point: 00000000
  128 + HAB Blocks: 0x177fffc0 0x0000 0x0006e020
  129 +
  130 +As explained in section above the SPL is first authenticated by the ROM code
  131 +and the root of trust is extended to the U-Boot image, hence two CSF files are
  132 +necessary to completely sign a bootloader image.
  133 +
  134 +In "Authenticate Data" CSF command users can copy and past the output
  135 +addresses, the csf_uboot.txt can be used as example:
  136 +
  137 +- In csf_SPL.txt:
  138 +
  139 + Block = 0x00907400 0x00000000 0x0000ec00 "SPL"
  140 +
  141 +- In csf_uboot-ivt.txt:
  142 +
  143 + Block = 0x177fffc0 0x0000 0x0006e020 "u-boot-ivt.img"
  144 +
  145 +1.4 Signing the images
  146 +-----------------------
  147 +
  148 +The CST tool is used for singing the U-Boot binary and generating a CSF binary,
  149 +users should input the CSF description file created in the step above and
  150 +receive a CSF binary, which contains the CSF commands, SRK table, signatures
  151 +and certificates.
  152 +
  153 +- Create SPL CSF binary file:
  154 +
  155 + $ ./cst -i csf_SPL.txt -o csf_SPL.bin
  156 +
  157 +- Append CSF signature to the end of SPL image:
  158 +
  159 + $ cat SPL csf_SPL.bin > SPL-signed
  160 +
  161 +- Create U-Boot proper CSF binary file:
  162 +
  163 + $ ./cst -i csf_uboot-ivt.txt -o csf_uboot-ivt.bin
  164 +
  165 +- Append CSF signature to the end of U-Boot proper image:
  166 +
  167 + $ cat u-boot-ivt.img csf_uboot-ivt.bin > u-boot-signed.img
  168 +
  169 +The bootloader is signed and can be flashed into the boot media.
  170 +
  171 +1.5 Closing the device
  172 +-----------------------
  173 +
  174 +The procedure for closing the device is similar as in Non-SPL targets, for a
  175 +complete procedure please refer to section "1.5 Programming SRK Hash" in
  176 +mx6_mx7_secure_boot.txt document available under doc/imx/habv4/guides/
  177 +directory.
  178 +
  179 +References:
  180 +[1] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using
  181 + HABv4" - Rev 2.