[U-Boot] [PATCH 3/6] doc: imx: habv4: Add Secure Boot guide for i.MX6 and i.MX7 non-SPL targets
Breno Matheus Lima
breno.lima at nxp.com
Wed Jan 23 19:29:59 UTC 2019
Add HABv4 documentation for non-SPL 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 at nxp.com>
Reviewed-by: Utkarsh Gupta <utkarsh.gupta at nxp.com>
Signed-off-by: Breno Lima <breno.lima at nxp.com>
---
.../csf_additional_images.txt | 34 ++
.../habv4/csf_examples/mx6_mx7/csf_uboot.txt | 32 ++
.../mx6_mx7/csf_uboot_fast_authentication.txt | 23 +
doc/imx/habv4/guides/mx6_mx7_secure_boot.txt | 402 ++++++++++++++++++
doc/imx/habv4/script_examples/genIVT.pl | 12 +
5 files changed, 503 insertions(+)
create mode 100644 doc/imx/habv4/csf_examples/additional_images/csf_additional_images.txt
create mode 100644 doc/imx/habv4/csf_examples/mx6_mx7/csf_uboot.txt
create mode 100644 doc/imx/habv4/csf_examples/mx6_mx7/csf_uboot_fast_authentication.txt
create mode 100644 doc/imx/habv4/guides/mx6_mx7_secure_boot.txt
create mode 100644 doc/imx/habv4/script_examples/genIVT.pl
diff --git a/doc/imx/habv4/csf_examples/additional_images/csf_additional_images.txt b/doc/imx/habv4/csf_examples/additional_images/csf_additional_images.txt
new file mode 100644
index 0000000000..bbe489714b
--- /dev/null
+++ b/doc/imx/habv4/csf_examples/additional_images/csf_additional_images.txt
@@ -0,0 +1,34 @@
+[Header]
+ Version = 4.2
+ Hash Algorithm = sha256
+ Engine Configuration = 0
+ Certificate Format = X509
+ Signature Format = CMS
+ Engine = CAAM
+
+[Install SRK]
+ # Index of the key location in the SRK table to be installed
+ File = "../crts/SRK_1_2_3_4_table.bin"
+ Source index = 0
+
+[Install CSFK]
+ # Key used to authenticate the CSF data
+ File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate CSF]
+
+[Install Key]
+ # Key slot index used to authenticate the key to be installed
+ Verification index = 0
+ # Target key slot in HAB key store where key will be installed
+ Target Index = 2
+ # Key to install
+ File= "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate Data]
+ # Key slot index used to authenticate the image data
+ Verification index = 2
+ # Authenticate Start Address, Offset, Length and file
+ Blocks = 0x80800000 0x00000000 0x80EEA020 "zImage", \
+ 0x83800000 0x00000000 0x8380B927 "imx7d-sdb.dtb", \
+ 0x84000000 0x00000000 0x840425B8 "uTee-7dsdb"
diff --git a/doc/imx/habv4/csf_examples/mx6_mx7/csf_uboot.txt b/doc/imx/habv4/csf_examples/mx6_mx7/csf_uboot.txt
new file mode 100644
index 0000000000..39986243e4
--- /dev/null
+++ b/doc/imx/habv4/csf_examples/mx6_mx7/csf_uboot.txt
@@ -0,0 +1,32 @@
+[Header]
+ Version = 4.2
+ Hash Algorithm = sha256
+ Engine Configuration = 0
+ Certificate Format = X509
+ Signature Format = CMS
+ Engine = CAAM
+
+[Install SRK]
+ # Index of the key location in the SRK table to be installed
+ File = "../crts/SRK_1_2_3_4_table.bin"
+ Source index = 0
+
+[Install CSFK]
+ # Key used to authenticate the CSF data
+ File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate CSF]
+
+[Install Key]
+ # Key slot index used to authenticate the key to be installed
+ Verification index = 0
+ # Target key slot in HAB key store where key will be installed
+ Target Index = 2
+ # Key to install
+ File= "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate Data]
+ # Key slot index used to authenticate the image data
+ Verification index = 2
+ # Authenticate Start Address, Offset, Length and file
+ Blocks = 0x877ff400 0x00000000 0x0009ec00 "u-boot-dtb.imx"
diff --git a/doc/imx/habv4/csf_examples/mx6_mx7/csf_uboot_fast_authentication.txt b/doc/imx/habv4/csf_examples/mx6_mx7/csf_uboot_fast_authentication.txt
new file mode 100644
index 0000000000..cdb34bcf74
--- /dev/null
+++ b/doc/imx/habv4/csf_examples/mx6_mx7/csf_uboot_fast_authentication.txt
@@ -0,0 +1,23 @@
+[Header]
+ Version = 4.2
+ Hash Algorithm = sha256
+ Engine Configuration = 0
+ Certificate Format = X509
+ Signature Format = CMS
+ Engine = CAAM
+
+[Install SRK]
+ # Index of the key location in the SRK table to be installed
+ File = "../crts/SRK_1_2_3_4_table.bin"
+ Source index = 0
+
+[Install NOCAK]
+ File = "../crts/SRK1_sha256_2048_65537_v3_usr_crt.pem"
+
+[Authenticate CSF]
+
+[Authenticate Data]
+ # Key slot index 0 used to authenticate the image data
+ Verification index = 0
+ # Authenticate Start Address, Offset, Length and file
+ Blocks = 0x877ff400 0x00000000 0x0009ec00 "u-boot-dtb.imx"
diff --git a/doc/imx/habv4/guides/mx6_mx7_secure_boot.txt b/doc/imx/habv4/guides/mx6_mx7_secure_boot.txt
new file mode 100644
index 0000000000..98e18beecd
--- /dev/null
+++ b/doc/imx/habv4/guides/mx6_mx7_secure_boot.txt
@@ -0,0 +1,402 @@
+ +=======================================================+
+ + i.MX6, i.MX7 U-Boot Secure Boot guide using HABv4 +
+ +=======================================================+
+
+1. HABv4 secure boot process
+-----------------------------
+
+This document describes a step-by-step procedure on how to sign and securely
+boot an U-Boot image for non-SPL targets. It is assumed that the reader is
+familiar with basic HAB concepts and with the PKI tree generation.
+
+Details about HAB can be found in the application note AN4581[1] and in the
+introduction_habv4.txt document.
+
+1.1 Building a u-boot-dtb.imx image supporting secure boot
+-----------------------------------------------------------
+
+The U-Boot provides support to secure boot configuration and also provide
+access to the HAB APIs exposed by the ROM vector table, the support is
+enabled by selecting the CONFIG_SECURE_BOOT option.
+
+When built with this configuration, the U-Boot provides extra functions for
+HAB, such as the HAB status logs retrievement through the hab_status command
+and support for extending the root of trust.
+
+The U-Boot also correctly pads the final image by aligning to the next 0xC00
+address, so the CSF signature data generated by CST can be concatenated to
+image.
+
+The diagram below illustrate a signed u-boot-dtb.imx image layout:
+
+ ------- +-----------------------------+ <-- *start
+ ^ | Image Vector Table |
+ | +-----------------------------+ <-- *boot_data
+ | | Boot Data |
+ | +-----------------------------+ <-- *dcd
+ | | DCD Table |
+ | +-----------------------------+
+ Signed | | Padding |
+ Data | +-----------------------------+ <-- *entry
+ | | |
+ | | |
+ | | u-boot-dtb.bin |
+ | | |
+ | | |
+ | +-----------------------------+
+ v | Padding |
+ ------- +-----------------------------+ <-- *csf
+ | |
+ | Command Sequence File (CSF) |
+ | |
+ +-----------------------------+
+ | Padding (optional) |
+ +-----------------------------+
+
+1.2 Enabling the secure boot support
+-------------------------------------
+
+The first step is to generate an U-Boot image supporting the HAB features
+mentioned above, this can be achieved by adding CONFIG_SECURE_BOOT to the
+build configuration:
+
+- Defconfig:
+
+ CONFIG_SECURE_BOOT=y
+
+- Kconfig:
+
+ ARM architecture -> Support i.MX HAB features
+
+1.3 Creating the CSF description file
+--------------------------------------
+
+The CSF contains all the commands that the HAB executes during the secure
+boot. These commands instruct the HAB on which memory areas of the image
+to authenticate, which keys to install, use and etc.
+
+CSF examples are available under doc/imx/habv4/csf_examples/ directory.
+
+A build log containing the "Authenticate Data" parameters is available after
+the U-Boot build, the example below is a log for mx7dsabresd_defconfig target:
+
+- mkimage build log:
+
+ $ cat u-boot-dtb.imx.log
+
+ Image Type: Freescale IMX Boot Image
+ Image Ver: 2 (i.MX53/6/7 compatible)
+ Mode: DCD
+ Data Size: 667648 Bytes = 652.00 KiB = 0.64 MiB
+ Load Address: 877ff420
+ Entry Point: 87800000
+ HAB Blocks: 0x877ff400 0x00000000 0x0009ec00
+ ^^^^^^^^^^ ^^^^^^^^^^ ^^^^^^^^^^
+ | | |
+ | | ------- (1)
+ | |
+ | ------------------ (2)
+ |
+ ----------------------------- (3)
+
+ (1) Size of area in file u-boot-dtb.imx to sign.
+ This area should include the IVT, the Boot Data the DCD
+ and the U-Boot itself.
+ (2) Start of area in u-boot-dtb.imx to sign.
+ (3) Start of area in RAM to authenticate.
+
+- In "Authenticate Data" CSF command users can copy and past the output
+ addresses:
+
+ Block = 0x877ff400 0x00000000 0x0009ec00 "u-boot-dtb.imx"
+
+1.4 Signing the U-Boot binary
+------------------------------
+
+The CST tool is used for singing the U-Boot binary and generating a CSF binary,
+users should input the CSF description file created in the step above and
+should receive a CSF binary, which contains the CSF commands, SRK table,
+signatures and certificates.
+
+- Create CSF binary file:
+
+ $ ./cst -i csf_uboot.txt -o csf_uboot.bin
+
+- Append CSF signature to the end of U-Boot image:
+
+ $ cat u-boot-dtb.imx csf_uboot.bin > u-boot-signed.imx
+
+The u-boot-signed.imx is the signed binary and should be flashed into the boot
+media.
+
+- Flash signed U-Boot binary:
+
+ $ sudo dd if=u-boot-signed.imx of=/dev/sd<x> bs=1K seek=1 && sync
+
+1.5 Programming SRK Hash
+-------------------------
+
+As explained in AN4581[1] and in introduction_habv4.txt document the SRK Hash
+fuse values are generated by the srktool and should be programmed in the
+SoC SRK_HASH[255:0] fuses.
+
+Be careful when programming these values, as this data is the basis for the
+root of trust. An error in SRK Hash results in a part that does not boot.
+
+The U-Boot fuse tool can be used for programming eFuses on i.MX SoCs.
+
+- Dump SRK Hash fuses values in host machine:
+
+ $ hexdump -e '/4 "0x"' -e '/4 "%X""\n"' SRK_1_2_3_4_fuse.bin
+ 0x20593752
+ 0x6ACE6962
+ 0x26E0D06C
+ 0xFC600661
+ 0x1240E88F
+ 0x1209F144
+ 0x831C8117
+ 0x1190FD4D
+
+- Program SRK_HASH[255:0] fuses, using i.MX6 series as example:
+
+ => fuse prog 3 0 0x20593752
+ => fuse prog 3 1 0x6ACE6962
+ => fuse prog 3 2 0x26E0D06C
+ => fuse prog 3 3 0xFC600661
+ => fuse prog 3 4 0x1240E88F
+ => fuse prog 3 5 0x1209F144
+ => fuse prog 3 6 0x831C8117
+ => fuse prog 3 7 0x1190FD4D
+
+The table below lists the SRK_HASH bank and word according to the i.MX device:
+
+ +-------------------+---------------+---------------+---------------+
+ | | i.MX6 Series | i.MX7D/S | i.MX7ULP |
+ +-------------------+---------------+---------------+---------------+
+ | SRK_HASH[31:00] | bank 3 word 0 | bank 6 word 0 | bank 5 word 0 |
+ +-------------------+---------------+---------------+---------------+
+ | SRK_HASH[63:32] | bank 3 word 1 | bank 6 word 1 | bank 5 word 1 |
+ +-------------------+---------------+---------------+---------------+
+ | SRK_HASH[95:64] | bank 3 word 2 | bank 6 word 2 | bank 5 word 2 |
+ +-------------------+---------------+---------------+---------------+
+ | SRK_HASH[127:96] | bank 3 word 3 | bank 6 word 3 | bank 5 word 3 |
+ +-------------------+---------------+---------------+---------------+
+ | SRK_HASH[159:128] | bank 3 word 4 | bank 7 word 0 | bank 5 word 4 |
+ +-------------------+---------------+---------------+---------------+
+ | SRK_HASH[191:160] | bank 3 word 5 | bank 7 word 1 | bank 5 word 5 |
+ +-------------------+---------------+---------------+---------------+
+ | SRK_HASH[223:192] | bank 3 word 6 | bank 7 word 2 | bank 5 word 6 |
+ +-------------------+---------------+---------------+---------------+
+ | SRK_HASH[255:224] | bank 3 word 7 | bank 7 word 3 | bank 5 word 7 |
+ +-------------------+---------------+---------------+---------------+
+
+1.6 Verifying HAB events
+-------------------------
+
+The next step is to verify that the signature attached to U-Boot is
+successfully processed without errors. HAB generates events when processing
+the commands if it encounters issues.
+
+The hab_status U-Boot command call the hab_report_event() and hab_status()
+HAB API functions to verify the processor security configuration and status.
+This command displays any events that were generated during the process.
+
+Prior to closing the device users should ensure no HAB events were found, as
+the example below:
+
+- Verify HAB events:
+
+ => hab_status
+
+ Secure boot disabled
+
+ HAB Configuration: 0xf0, HAB State: 0x66
+ No HAB Events Found!
+
+1.7 Closing the device
+-----------------------
+
+After the device successfully boots a signed image without generating any HAB
+events, it is safe to close the device. This is the last step in the HAB
+process, and is achieved by programming the SEC_CONFIG[1] fuse bit.
+
+Once the fuse is programmed, the chip does not load an image that has not been
+signed using the correct PKI tree.
+
+- Program SEC_CONFIG[1] fuse, using i.MX6 series as example:
+
+ => fuse prog 0 6 0x00000002
+
+The table below list the SEC_CONFIG[1] bank and word according to the i.MX
+device:
+
+ +--------------+-----------------+------------+
+ | Device | Bank and Word | Value |
+ +--------------+-----------------+------------+
+ | i.MX6 Series | bank 0 word 6 | 0x00000002 |
+ +--------------+-----------------+------------+
+ | i.MX7D/S | bank 1 word 3 | 0x02000000 |
+ +--------------+-----------------+------------+
+ | i.MX7ULP | bank 29 word 6 | 0x80000000 |
+ +--------------+-----------------+------------+
+
+1.8 Completely secure the device
+---------------------------------
+
+Additional fuses can be programmed for completely secure the device, more
+details about these fuses and their possible impact can be found at AN4581[1].
+
+- Program SRK_LOCK, using i.MX6 series as example:
+
+ => fuse prog 0 0 0x4000
+
+- Program DIR_BT_DIS, using i.MX6 series as example:
+
+ => fuse prog 0 6 0x8
+
+- Program SJC_DISABLE, using i.MX6 series as example:
+
+ => fuse prog 0 6 0x100000
+
+- JTAG_SMODE, using i.MX6 series as example:
+
+ => fuse prog 0 6 0xC00000
+
+The table below list the SRK_LOCK, DIR_BT_DIS, SJC_DISABLE, and JTAG_SMODE bank
+and word according to the i.MX device:
+
+ +--------------+---------------+------------+
+ | Device | Bank and Word | Value |
+ +--------------+---------------+------------+
+ | SRK_LOCK |
+ +-------------------------------------------+
+ | i.MX6 Series | bank 0 word 0 | 0x00004000 |
+ +--------------+---------------+------------+
+ | i.MX7D/S | bank 0 word 0 | 0x00000200 |
+ +--------------+---------------+------------+
+ | i.MX7ULP | bank 1 word 1 | 0x00000080 |
+ +--------------+---------------+------------+
+ | DIR_BT_DIS |
+ +-------------------------------------------+
+ | i.MX6 Series | bank 0 word 6 | 0x00000008 |
+ +--------------+---------------+------------+
+ | i.MX7D/S | bank 1 word 3 | 0x08000000 |
+ +--------------+---------------+------------+
+ | i.MX7ULP | bank 1 word 1 | 0x00002000 |
+ +--------------+---------------+------------+
+ | SJC_DISABLE |
+ +-------------------------------------------+
+ | i.MX6 Series | bank 0 word 6 | 0x00100000 |
+ +--------------+---------------+------------+
+ | i.MX7D/S | bank 1 word 3 | 0x00200000 |
+ +--------------+---------------+------------+
+ | i.MX7ULP | bank 1 word 1 | 0x00000020 |
+ +--------------+---------------+------------+
+ | JTAG_SMODE |
+ +-------------------------------------------+
+ | i.MX6 Series | bank 0 word 6 | 0x00C00000 |
+ +--------------+---------------+------------+
+ | i.MX7D/S | bank 1 word 3 | 0x00C00000 |
+ +--------------+---------------+------------+
+ | i.MX7ULP | bank 1 word 1 | 0x000000C0 |
+ +--------------+---------------+------------+
+
+2. Extending the root of trust
+-------------------------------
+
+The High Assurance Boot (HAB) code located in the on-chip ROM provides an
+Application Programming Interface (API) making it possible to call back
+into the HAB code for authenticating additional boot images.
+
+The U-Boot supports this feature and can be used to authenticate the Linux
+Kernel Image.
+
+The process of signing an additional image is similar to the U-Boot.
+The diagram below illustrate the zImage layout:
+
+ ------- +-----------------------------+ <-- *load_address
+ ^ | |
+ | | |
+ | | |
+ | | |
+ | | zImage |
+ Signed | | |
+ Data | | |
+ | | |
+ | +-----------------------------+
+ | | Padding Next Boundary |
+ | +-----------------------------+ <-- *ivt
+ v | Image Vector Table |
+ ------- +-----------------------------+ <-- *csf
+ | |
+ | Command Sequence File (CSF) |
+ | |
+ +-----------------------------+
+ | Padding (optional) |
+ +-----------------------------+
+
+2.1 Padding the image
+----------------------
+
+The zImage must be padded to the next boundary address (0x1000), for instance
+if the image size is 0x649920 it must be padded to 0x64A000.
+
+The tool objcopy can be used for padding the image.
+
+- Pad the zImage:
+
+ $ objcopy -I binary -O binary --pad-to 0x64A000 --gap-fill=0x00 \
+ zImage zImage_pad.bin
+
+2.2 Generating Image Vector Table
+----------------------------------
+
+The HAB code requires an Image Vector Table (IVT) for determining the image
+length and the CSF location. Since zImage does not include an IVT this has
+to be manually created and appended to the end of the padded zImage, the
+script genIVT.pl in script_examples directory can be used as reference.
+
+- Generate IVT:
+
+ $ genIVT.pl
+
+Note: The load Address may change depending on the device.
+
+- Append the ivt.bin at the end of the padded zImage:
+
+ $ cat zImage_pad.bin ivt.bin > zImage_pad_ivt.bin
+
+2.3 Signing the image
+----------------------
+
+A CSF file has to be created to sign the image. HAB does not allow to change
+the SRK once the first image is authenticated, so the same SRK key used in
+U-Boot must be used when extending the root of trust.
+
+CSF examples are available in ../csf_examples/additional_images/
+directory.
+
+- Create CSF binary file:
+
+ $ ./cst --i csf_additional_images.txt --o csf_zImage.bin
+
+- Attach the CSF binary to the end of the image:
+
+ $ cat zImage_pad_ivt.bin csf_zImage.bin > zImage_signed.bin
+
+2.4 Verifying HAB events
+-------------------------
+
+The U-Boot includes the hab_auth_img command which can be used for
+authenticating and troubleshooting the signed image, zImage must be
+loaded at the load address specified in the IVT.
+
+- Authenticate additional image:
+
+ => hab_auth_img <Load Address> <Image Size> <IVT Offset>
+
+If no HAB events were found the zImage is successfully signed.
+
+References:
+[1] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using
+ HABv4" - Rev 2.
diff --git a/doc/imx/habv4/script_examples/genIVT.pl b/doc/imx/habv4/script_examples/genIVT.pl
new file mode 100644
index 0000000000..84a4fcb16f
--- /dev/null
+++ b/doc/imx/habv4/script_examples/genIVT.pl
@@ -0,0 +1,12 @@
+#! /usr/bin/perl -w
+use strict;
+open(my $out, '>:raw', 'ivt.bin') or die "Unable to open: $!";
+print $out pack("V", 0x412000D1); # Signature
+print $out pack("V", 0x80800000); # Load Address (*load_address)
+print $out pack("V", 0x0); # Reserved
+print $out pack("V", 0x0); # DCD pointer
+print $out pack("V", 0x0); # Boot Data
+print $out pack("V", 0x80EEA000); # Self Pointer (*ivt)
+print $out pack("V", 0x80EEA020); # CSF Pointer (*csf)
+print $out pack("V", 0x0); # Reserved
+close($out);
--
2.17.1
More information about the U-Boot
mailing list