Eric Lee / smarc-uboot

Download as
Browse Code ยป

Commit 5cf826345d21f11c745c78df55af8cec29ec4779

Authored by Breno Lima
Committed by Ye Li
1 parent aedc4dfa08
Exists in smarc_8mm-imx_v2018.03_4.14.98_2.0.0_ga and in 5 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-imx_v2018.03_4.14.78_1.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-19970-2 doc: imx: habv4: Add Secure Boot documentation for i.MX6 and i.MX7 family devices 

Add HABv4 documentation for u-boot-dtb.imx targets covering the
following topics:

- How to sign an securely boot an u-boot-dtb.imx image.
- How to extend the root of trust for additional boot images.
- Add 3 CSF examples.
- Add IVT generation script example.

Reviewed-by: Ye Li <ye.li@nxp.com>
Reviewed-by: Utkarsh Gupta <utkarsh.gupta@nxp.com>
Signed-off-by: Breno Lima <breno.lima@nxp.com>

Showing 5 changed files with 503 additions and 0 deletions Side-by-side Diff

doc/imx/hab/habv4/csf_examples/additional_images/csf_additional_images.txt
Diff comments   View file @ 5cf8263
  1 +[Header]
  2 + Version = 4.2
  3 + Hash Algorithm = sha256
  4 + Engine Configuration = 0
  5 + Certificate Format = X509
  6 + Signature Format = CMS
  7 + Engine = CAAM
  8 +
  9 +[Install SRK]
  10 + # Index of the key location in the SRK table to be installed
  11 + File = "../crts/SRK_1_2_3_4_table.bin"
  12 + Source index = 0
  13 +
  14 +[Install CSFK]
  15 + # Key used to authenticate the CSF data
  16 + File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem"
  17 +
  18 +[Authenticate CSF]
  19 +
  20 +[Install Key]
  21 + # Key slot index used to authenticate the key to be installed
  22 + Verification index = 0
  23 + # Target key slot in HAB key store where key will be installed
  24 + Target Index = 2
  25 + # Key to install
  26 + File= "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem"
  27 +
  28 +[Authenticate Data]
  29 + # Key slot index used to authenticate the image data
  30 + Verification index = 2
  31 + # Authenticate Start Address, Offset, Length and file
  32 + Blocks = 0x80800000 0x00000000 0x80EEA020 "zImage", \
  33 + 0x83800000 0x00000000 0x8380B927 "imx7d-sdb.dtb", \
  34 + 0x84000000 0x00000000 0x840425B8 "uTee-7dsdb"
doc/imx/hab/habv4/csf_examples/mx6_mx7/csf_uboot.txt
Diff comments   View file @ 5cf8263
  1 +[Header]
  2 + Version = 4.2
  3 + Hash Algorithm = sha256
  4 + Engine Configuration = 0
  5 + Certificate Format = X509
  6 + Signature Format = CMS
  7 + Engine = CAAM
  8 +
  9 +[Install SRK]
  10 + # Index of the key location in the SRK table to be installed
  11 + File = "../crts/SRK_1_2_3_4_table.bin"
  12 + Source index = 0
  13 +
  14 +[Install CSFK]
  15 + # Key used to authenticate the CSF data
  16 + File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem"
  17 +
  18 +[Authenticate CSF]
  19 +
  20 +[Install Key]
  21 + # Key slot index used to authenticate the key to be installed
  22 + Verification index = 0
  23 + # Target key slot in HAB key store where key will be installed
  24 + Target Index = 2
  25 + # Key to install
  26 + File= "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem"
  27 +
  28 +[Authenticate Data]
  29 + # Key slot index used to authenticate the image data
  30 + Verification index = 2
  31 + # Authenticate Start Address, Offset, Length and file
  32 + Blocks = 0x877ff400 0x00000000 0x0009ec00 "u-boot-dtb.imx"
doc/imx/hab/habv4/csf_examples/mx6_mx7/csf_uboot_fast_authentication.txt
Diff comments   View file @ 5cf8263
  1 +[Header]
  2 + Version = 4.2
  3 + Hash Algorithm = sha256
  4 + Engine Configuration = 0
  5 + Certificate Format = X509
  6 + Signature Format = CMS
  7 + Engine = CAAM
  8 +
  9 +[Install SRK]
  10 + # Index of the key location in the SRK table to be installed
  11 + File = "../crts/SRK_1_2_3_4_table.bin"
  12 + Source index = 0
  13 +
  14 +[Install NOCAK]
  15 + File = "../crts/SRK1_sha256_2048_65537_v3_usr_crt.pem"
  16 +
  17 +[Authenticate CSF]
  18 +
  19 +[Authenticate Data]
  20 + # Key slot index 0 used to authenticate the image data
  21 + Verification index = 0
  22 + # Authenticate Start Address, Offset, Length and file
  23 + Blocks = 0x877ff400 0x00000000 0x0009ec00 "u-boot-dtb.imx"
doc/imx/hab/habv4/guides/mx6_mx7_secure_boot.txt
Diff comments   View file @ 5cf8263
  1 + +=======================================================+
  2 + + i.MX6, i.MX7 U-Boot Secure Boot guide using HABv4 +
  3 + +=======================================================+
  4 +
  5 +1. HABv4 secure boot process
  6 +-----------------------------
  7 +
  8 +This document describes a step-by-step procedure on how to sign and securely
  9 +boot an U-Boot image. It is assumed that the reader is familiar with basic
  10 +HAB concepts and with the PKI tree generation.
  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 u-boot-dtb.imx image supporting secure boot
  16 +-----------------------------------------------------------
  17 +
  18 +The U-Boot provides support to secure boot configuration and also provide
  19 +access to the HAB APIs exposed by the ROM vector table, the support is
  20 +enabled by selecting the CONFIG_SECURE_BOOT option.
  21 +
  22 +When built with this configuration, the U-Boot provides extra functions for
  23 +HAB, such as the HAB status logs retrievement through the hab_status command
  24 +and support for extending the root of trust.
  25 +
  26 +The U-Boot also correctly pads the final image by aligning to the next 0xC00
  27 +address, so the CSF signature data generated by CST can be concatenated to
  28 +image.
  29 +
  30 +The diagram below illustrate a signed u-boot-dtb.imx image layout:
  31 +
  32 + ------- +-----------------------------+ <-- *start
  33 + ^ | Image Vector Table |
  34 + | +-----------------------------+ <-- *boot_data
  35 + | | Boot Data |
  36 + | +-----------------------------+ <-- *dcd
  37 + | | DCD Table |
  38 + | +-----------------------------+
  39 + Signed | | Padding |
  40 + Data | +-----------------------------+ <-- *entry
  41 + | | |
  42 + | | |
  43 + | | u-boot-dtb.bin |
  44 + | | |
  45 + | | |
  46 + | +-----------------------------+
  47 + v | Padding |
  48 + ------- +-----------------------------+ <-- *csf
  49 + | |
  50 + | Command Sequence File (CSF) |
  51 + | |
  52 + +-----------------------------+
  53 + | Padding (optional) |
  54 + +-----------------------------+
  55 +
  56 +1.2 Enabling the secure boot support
  57 +-------------------------------------
  58 +
  59 +The first step is to generate an U-Boot image supporting the HAB features
  60 +mentioned above, this can be achieved by adding CONFIG_SECURE_BOOT to the
  61 +build configuration:
  62 +
  63 +- Defconfig:
  64 +
  65 + CONFIG_SECURE_BOOT=y
  66 +
  67 +- Kconfig:
  68 +
  69 + ARM architecture -> Support i.MX HAB features
  70 +
  71 +1.3 Creating the CSF description file
  72 +--------------------------------------
  73 +
  74 +The CSF contains all the commands that the ROM executes during the secure
  75 +boot. These commands instruct the HAB on which memory areas of the image
  76 +to authenticate, which keys to install, use and etc.
  77 +
  78 +CSF examples are available under doc/imx/hab/habv4/csf_examples/ directory.
  79 +
  80 +A build log containing the "Authenticate Data" parameters is available after
  81 +the U-Boot build, the example below is a log for mx7dsabresd_defconfig target:
  82 +
  83 +- mkimage build log:
  84 +
  85 + $ cat u-boot-dtb.imx.log
  86 +
  87 + Image Type: Freescale IMX Boot Image
  88 + Image Ver: 2 (i.MX53/6/7 compatible)
  89 + Mode: DCD
  90 + Data Size: 667648 Bytes = 652.00 KiB = 0.64 MiB
  91 + Load Address: 877ff420
  92 + Entry Point: 87800000
  93 + HAB Blocks: 877ff400 00000000 0009ec00
  94 + ^^^^^^^^ ^^^^^^^^ ^^^^^^^^
  95 + | | |
  96 + | | ------- (1)
  97 + | |
  98 + | ---------------- (2)
  99 + |
  100 + ------------------------- (3)
  101 +
  102 + (1) Size of area in file u-boot-dtb.imx to sign.
  103 + This area should include the IVT, the Boot Data the DCD
  104 + and the U-Boot itself.
  105 + (2) Start of area in u-boot-dtb.imx to sign.
  106 + (3) Start of area in RAM to authenticate.
  107 +
  108 +- In "Authenticate Data" CSF command users can copy and past the output
  109 + addresses:
  110 +
  111 + Block = 0x877ff400 0x00000000 0x0009ec00 "u-boot-dtb.imx"
  112 +
  113 +1.4 Signing the U-Boot binary
  114 +------------------------------
  115 +
  116 +The CST tool is used for singing the U-Boot binary and generating a CSF binary,
  117 +users should input the CSF description file created in the step above and
  118 +should receive a CSF binary, which contains the CSF commands, SRK table,
  119 +signatures and certificates.
  120 +
  121 +- Create CSF binary file:
  122 +
  123 + $ ./cst -i csf_uboot.txt -o csf_uboot.bin
  124 +
  125 +- Append CSF signature to the end of U-Boot image:
  126 +
  127 + $ cat u-boot-dtb.imx csf_uboot.bin > u-boot-signed.imx
  128 +
  129 +The u-boot-signed.imx is the signed binary and should be flashed into the boot
  130 +media.
  131 +
  132 +- Flash signed U-Boot binary:
  133 +
  134 + $ sudo dd if=u-boot-signed.imx of=/dev/sd<x> bs=1K seek=1 && sync
  135 +
  136 +1.5 Programming SRK Hash
  137 +-------------------------
  138 +
  139 +As explained in AN4581[1] and in introduction_habv4.txt document the SRK Hash
  140 +fuse values are generated by the srktool and should be programmed in the
  141 +SoC SRK_HASH[255:0] fuses.
  142 +
  143 +Be careful when programming these values, as this data is the basis for the
  144 +root of trust. An error in SRK Hash results in a part that does not boot.
  145 +
  146 +The U-Boot fuse tool can be used for programming eFuses on i.MX SoCs.
  147 +
  148 +- Dump SRK Hash fuses values in host machine:
  149 +
  150 + $ hexdump -e '/4 "0x"' -e '/4 "%X""\n"' SRK_1_2_3_4_fuse.bin
  151 + 0x20593752
  152 + 0x6ACE6962
  153 + 0x26E0D06C
  154 + 0xFC600661
  155 + 0x1240E88F
  156 + 0x1209F144
  157 + 0x831C8117
  158 + 0x1190FD4D
  159 +
  160 +- Program SRK_HASH[255:0] fuses, using i.MX6 series as example:
  161 +
  162 + => fuse prog 3 0 0x20593752
  163 + => fuse prog 3 1 0x6ACE6962
  164 + => fuse prog 3 2 0x26E0D06C
  165 + => fuse prog 3 3 0xFC600661
  166 + => fuse prog 3 4 0x1240E88F
  167 + => fuse prog 3 5 0x1209F144
  168 + => fuse prog 3 6 0x831C8117
  169 + => fuse prog 3 7 0x1190FD4D
  170 +
  171 +The table below lists the SRK_HASH bank and word according to the i.MX device:
  172 +
  173 + +-------------------+---------------+---------------+---------------+
  174 + | | i.MX6 Series | i.MX7D/S | i.MX7ULP |
  175 + +-------------------+---------------+---------------+---------------+
  176 + | SRK_HASH[31:00] | bank 3 word 0 | bank 6 word 0 | bank 5 word 0 |
  177 + +-------------------+---------------+---------------+---------------+
  178 + | SRK_HASH[63:32] | bank 3 word 1 | bank 6 word 1 | bank 5 word 1 |
  179 + +-------------------+---------------+---------------+---------------+
  180 + | SRK_HASH[95:64] | bank 3 word 2 | bank 6 word 2 | bank 5 word 2 |
  181 + +-------------------+---------------+---------------+---------------+
  182 + | SRK_HASH[127:96] | bank 3 word 3 | bank 6 word 3 | bank 5 word 3 |
  183 + +-------------------+---------------+---------------+---------------+
  184 + | SRK_HASH[159:128] | bank 3 word 4 | bank 7 word 0 | bank 5 word 4 |
  185 + +-------------------+---------------+---------------+---------------+
  186 + | SRK_HASH[191:160] | bank 3 word 5 | bank 7 word 1 | bank 5 word 5 |
  187 + +-------------------+---------------+---------------+---------------+
  188 + | SRK_HASH[223:192] | bank 3 word 6 | bank 7 word 2 | bank 5 word 6 |
  189 + +-------------------+---------------+---------------+---------------+
  190 + | SRK_HASH[255:224] | bank 3 word 7 | bank 7 word 3 | bank 5 word 7 |
  191 + +-------------------+---------------+---------------+---------------+
  192 +
  193 +1.6 Verifying HAB events
  194 +-------------------------
  195 +
  196 +The next step is to verify that the signature attached to U-Boot is
  197 +successfully processed without errors. HAB generates events when processing
  198 +the commands if it encounters issues.
  199 +
  200 +The hab_status U-Boot command call the hab_report_event() and hab_status()
  201 +HAB API functions to verify the processor security configuration and status.
  202 +This command displays any events that were generated during the process.
  203 +
  204 +Prior to closing the device users should ensure no HAB events were found, as
  205 +the example below:
  206 +
  207 +- Verify HAB events:
  208 +
  209 + => hab_status
  210 +
  211 + Secure boot disabled
  212 +
  213 + HAB Configuration: 0xf0, HAB State: 0x66
  214 + No HAB Events Found!
  215 +
  216 +1.7 Closing the device
  217 +-----------------------
  218 +
  219 +After the device successfully boots a signed image without generating any HAB
  220 +events, it is safe to close the device. This is the last step in the HAB
  221 +process, and is achieved by programming the SEC_CONFIG[1] fuse bit.
  222 +
  223 +Once the fuse is programmed, the chip does not load an image that has not been
  224 +signed using the correct PKI tree.
  225 +
  226 +- Program SEC_CONFIG[1] fuse, using i.MX6 series as example:
  227 +
  228 + => fuse prog 0 6 0x00000002
  229 +
  230 +The table below list the SEC_CONFIG[1] bank and word according to the i.MX
  231 +device:
  232 +
  233 + +--------------+-----------------+------------+
  234 + | Device | Bank and Word | Value |
  235 + +--------------+-----------------+------------+
  236 + | i.MX6 Series | bank 0 word 6 | 0x00000002 |
  237 + +--------------+-----------------+------------+
  238 + | i.MX7D/S | bank 1 word 3 | 0x02000000 |
  239 + +--------------+-----------------+------------+
  240 + | i.MX7ULP | bank 29 word 6 | 0x80000000 |
  241 + +--------------+-----------------+------------+
  242 +
  243 +1.8 Completely secure the device
  244 +---------------------------------
  245 +
  246 +Additional fuses can be programmed for completely secure the device, more
  247 +details about these fuses and their possible impact can be found at AN4581[1].
  248 +
  249 +- Program SRK_LOCK, using i.MX6 series as example:
  250 +
  251 + => fuse prog 0 0 0x4000
  252 +
  253 +- Program DIR_BT_DIS, using i.MX6 series as example:
  254 +
  255 + => fuse prog 0 6 0x8
  256 +
  257 +- Program SJC_DISABLE, using i.MX6 series as example:
  258 +
  259 + => fuse prog 0 6 0x100000
  260 +
  261 +- JTAG_SMODE, using i.MX6 series as example:
  262 +
  263 + => fuse prog 0 6 0xC00000
  264 +
  265 +The table below list the SRK_LOCK, DIR_BT_DIS, SJC_DISABLE, and JTAG_SMODE bank
  266 +and word according to the i.MX device:
  267 +
  268 + +--------------+---------------+------------+
  269 + | Device | Bank and Word | Value |
  270 + +--------------+---------------+------------+
  271 + | SRK_LOCK |
  272 + +-------------------------------------------+
  273 + | i.MX6 Series | bank 0 word 0 | 0x00004000 |
  274 + +--------------+---------------+------------+
  275 + | i.MX7D/S | bank 0 word 0 | 0x00000200 |
  276 + +--------------+---------------+------------+
  277 + | i.MX7ULP | bank 1 word 1 | 0x00000080 |
  278 + +--------------+---------------+------------+
  279 + | DIR_BT_DIS |
  280 + +-------------------------------------------+
  281 + | i.MX6 Series | bank 0 word 6 | 0x00000008 |
  282 + +--------------+---------------+------------+
  283 + | i.MX7D/S | bank 1 word 3 | 0x08000000 |
  284 + +--------------+---------------+------------+
  285 + | i.MX7ULP | bank 1 word 1 | 0x00002000 |
  286 + +--------------+---------------+------------+
  287 + | SJC_DISABLE |
  288 + +-------------------------------------------+
  289 + | i.MX6 Series | bank 0 word 6 | 0x00100000 |
  290 + +--------------+---------------+------------+
  291 + | i.MX7D/S | bank 1 word 3 | 0x00200000 |
  292 + +--------------+---------------+------------+
  293 + | i.MX7ULP | bank 1 word 1 | 0x00000020 |
  294 + +--------------+---------------+------------+
  295 + | JTAG_SMODE |
  296 + +-------------------------------------------+
  297 + | i.MX6 Series | bank 0 word 6 | 0x00C00000 |
  298 + +--------------+---------------+------------+
  299 + | i.MX7D/S | bank 1 word 3 | 0x00C00000 |
  300 + +--------------+---------------+------------+
  301 + | i.MX7ULP | bank 1 word 1 | 0x000000C0 |
  302 + +--------------+---------------+------------+
  303 +
  304 +2. Extending the root of trust
  305 +-------------------------------
  306 +
  307 +The High Assurance Boot (HAB) code located in the on-chip ROM provides an
  308 +Application Programming Interface (API) making it possible to call back
  309 +into the HAB code for authenticating additional boot images.
  310 +
  311 +The U-Boot supports this feature and can be used to authenticate the Linux
  312 +Kernel Image.
  313 +
  314 +The process of signing an additional image is similar to the U-Boot.
  315 +The diagram below illustrate the zImage layout:
  316 +
  317 + ------- +-----------------------------+ <-- *load_address
  318 + ^ | |
  319 + | | |
  320 + | | |
  321 + | | |
  322 + | | zImage |
  323 + Signed | | |
  324 + Data | | |
  325 + | | |
  326 + | +-----------------------------+
  327 + | | Padding Next Boundary |
  328 + | +-----------------------------+ <-- *ivt
  329 + v | Image Vector Table |
  330 + ------- +-----------------------------+ <-- *csf
  331 + | |
  332 + | Command Sequence File (CSF) |
  333 + | |
  334 + +-----------------------------+
  335 + | Padding (optional) |
  336 + +-----------------------------+
  337 +
  338 +2.1 Padding the image
  339 +----------------------
  340 +
  341 +The zImage must be padded to the next boundary address (0x1000), for instance
  342 +if the image size is 0x649920 it must be padded to 0x64A000.
  343 +
  344 +The tool objcopy can be used for padding the image.
  345 +
  346 +- Pad the zImage:
  347 +
  348 + $ objcopy -I binary -O binary --pad-to 0x6EA000 --gap-fill=0x00 \
  349 + zImage zImage_pad.bin
  350 +
  351 +2.2 Generating Image Vector Table
  352 +----------------------------------
  353 +
  354 +The HAB code requires an Image Vector Table (IVT) for determining the image
  355 +length and the CSF location. Since zImage does not include an IVT this has
  356 +to be manually created and appended to the end of the padded zImage, the
  357 +script genIVT.pl in script_examples directory can be used as reference.
  358 +
  359 +- Generate IVT:
  360 +
  361 + $ genIVT.pl
  362 +
  363 +Note: The load Address may change depending on the device.
  364 +
  365 +- Append the ivt.bin at the end of the padded zImage:
  366 +
  367 + $ cat zImage_pad.bin ivt.bin > zImage_pad_ivt.bin
  368 +
  369 +2.3 Signing the image
  370 +----------------------
  371 +
  372 +A CSF file has to be created to sign the image. HAB does not allow to change
  373 +the SRK once the first image is authenticated, so the same SRK key used in
  374 +U-Boot must be used when extending the root of trust.
  375 +
  376 +CSF examples are available in ../csf_examples/additional_images/
  377 +directory.
  378 +
  379 +- Create CSF binary file:
  380 +
  381 + $ ./cst --i csf_additional_images.txt --o csf_zImage.bin
  382 +
  383 +- Attach the CSF binary to the end of the image:
  384 +
  385 + $ cat zImage_pad_ivt.bin csf_zImage.bin > zImage_signed.bin
  386 +
  387 +2.4 Verifying HAB events
  388 +-------------------------
  389 +
  390 +The U-Boot includes the hab_auth_img command which can be used for
  391 +authenticating and troubleshooting the signed image, zImage must be
  392 +loaded at the load address specified in the IVT.
  393 +
  394 +- Authenticate additional image:
  395 +
  396 + => hab_auth_img <Load Address> <Image Size> <IVT Offset>
  397 +
  398 +If no HAB events were found the zImage is successfully signed.
  399 +
  400 +References:
  401 +[1] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using
  402 + HABv4" - Rev 2.
doc/imx/hab/habv4/script_examples/genIVT.pl
Diff comments   View file @ 5cf8263
  1 +#! /usr/bin/perl -w
  2 +use strict;
  3 +open(my $out, '>:raw', 'ivt.bin') or die "Unable to open: $!";
  4 +print $out pack("V", 0x412000D1); # Signature
  5 +print $out pack("V", 0x80800000); # Load Address (*load_address)
  6 +print $out pack("V", 0x0); # Reserved
  7 +print $out pack("V", 0x0); # DCD pointer
  8 +print $out pack("V", 0x0); # Boot Data
  9 +print $out pack("V", 0x80EEA000); # Self Pointer (*ivt)
  10 +print $out pack("V", 0x80EEA020); # CSF Pointer (*csf)
  11 +print $out pack("V", 0x0); # Reserved
  12 +close($out);