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@nxp.com Reviewed-by: Utkarsh Gupta utkarsh.gupta@nxp.com Signed-off-by: Breno Lima breno.lima@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);