123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402 |
- +=======================================================+
- + 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_IMX_HAB 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_IMX_HAB to the
- build configuration:
- - Defconfig:
- CONFIG_IMX_HAB=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.
|