Secure Boot

Secure boot is a mechanism that establishes a Chain of Trust (CoT) on all system boot images. Secure boot relies on cryptography to verify image signatures before their execution.

  • Root of Trusted Boot
    • The RoT(Root of Trusted) is Mediatek BootROM on Mediatek platform.

    • The BootROM verifies TF-A (BL2 image) with BROM secure boot mechanism

  • Chain of Trusted Boot
    • TF-A (BL2) verifies the BL3x image (fip.bin) which includes TF-A (BL31), OP-TEE (BL32) and U-Boot (BL33) with TF-A Trusted Board Boot mechanism

    • U-Boot (BL33) verifies Linux Kernel image with U-Boot FIT Verified Boot mechanism

../../_images/sw_yocto_secure-boot_workflow.png

This document explain how to secure each boot transition.

Secure Boot: BL1 to BL2

../../_images/sw_yocto_secure-boot_rot.png

When we power-up the device, the BL1 (ROM code) is the first code run. The BL2 (TF-A) is verified through the following sequence of steps.

    1. BL1 loads a hash based on root of trust public key (ROTPK) from the eFuse and calculates the SHA-256 hash of that ROTPK in BL2 image.

    1. The hash of ROTPK is compared with the one from the eFuse. If the comparison passed, BL1 would do signature verification in the next steps. If any failure, the system will halt.

    1. & 4. BL1 loads the BL2 loader and calculates the SHA-256 hash from the BL2 loader. In the meantime, BL1 decrypts the signature of BL2 loader based on RSA-2048.

    1. & 6. If the comparison succeeds, the system jumps to BL2 loader. Otherwise, the system halt.

This ROM code cannot be modified, however we can enable secure boot feature through efuse settings. Users can refer to the steps below to enable the secure boot (BL1 to BL2).

1. Generate eFuse and DA key

please add the following commands to generate keys for secure boot:

openssl genrsa -out ${KEYDIR}/efuse.pem 2048
openssl genrsa -out ${KEYDIR}/da.pem 2048

Warning

Enable SBC(Secure Boot Check)/DAA(Download Agent Authentication) and write the public key in efuse are performed one time only.

The efuse will be blown forever, we cannot override these fields after that.

The private keys efuse.pem and da.pem MUST NOT BE LOST.

Otherwise we won’t be able to sign/boot bl2.img and Download Agent (download mode).

Note

Download Agent (DA) is used on image flashing process only, and DA binary(lk.bin) is downloaded into SRAM (the same place that BootROM loads BL2 image) by BootROM via USB interface.

On the secure boot mechanism, DAA (Download Agent Authentication) can be enabled to support download agent verification by BootROM.

The concept is similar to BL2 verified by BootROM, but using a different key (DA_key) for DA signing and an eFuse control index (DAA_EN) for DAA enablement.

2. Set NDA_BUILD = “1” in Yocto build configuration

Secure boot support is NDA license required and the relevant tools are only provided with NDA license. Please add the following line to your local.conf:

NDA_BUILD = "1"

Important

Secure boot support is NDA license required and the relevant tools are only provided with NDA license. Please contact your Mediatek customer window to have access permission of NDA resources.

3. Set the keys in Yocto build configuration

To set the keys in yocto to sign BL2 and Download Agent, please add the following lines to your local.conf:

EFUSE_KEY = "${KEYDIR}/efuse.pem"
DA_KEY = "${KEYDIR}/da.pem"
BL2_SIGN_ENABLE = "1"
DA_SIGN_ENABLE = "1"
# Generate the secure package
SECURE_ZIP_ENABLE = "1"

Note

DAA (Download Agent Authentication) is not yet supported by all platforms. Currently, this is only supported by i350-evk and i350-pumpkin. For the other platforms, you must remove DA_SIGN_ENABLE and DA_KEY from your local.conf.

Then build BL2 and DA(LK) using yocto:

bitbake trusted-firmware-a
bitbake lk

This should generate a signed bl2.img and lk.bin in tmp/deploy/images/i350-evk.

4. Use eFuse Writer tool to enable secure boot (BL1 to BL2)

eFuse Writer is a user-space tool used to read and write eFuse fields. Users can write specific efuse index to enable Secure Boot feature with using eFuse Writer.

Important

eFuse Writer tool and the user guide is only provided with NDA license. Please contact your Mediatek customer window to have access permission for eFuse Writer tool.

# ewriter --help
ewriter Usage:
ewriter CMD INDEX LENGTH [VALUE in HEX]
Mandatory and optional arguments.
  CMD:    0(read) or 1(write).
  INDEX:  the index number of an eFuse field.
  LENGTH: the length of the eFuse index.
  [VALUE in HEX]: the data in hex be written into the eFuse index,
                  only valid in writing eFuse (CMD=1).
The details about efuse index and length, please refer to platform ewriter user guide.
Examples:
(1) read efuse index 1 with byte length "32" -> # ewriter 0 1 32
(2) read efuse index 5 with byte length "1"  ->  # ewriter 0 5 1
(3) write efuse index 1 with byte length "32"
    -> # ewriter 1 1 32 0000000011111111222222223333333344444444555555556666666677777777
(4) write efuse index 5 -> # ewriter 1 5 1 1
If the device does not have SBC and DAA enabled, these fields should not be set and keep 0.
For example: (The efuse index may be different on different platforms.)
ewriter 0 18 1  # read SBC efuse bit
efuse hex:
00
ewriter 0 19 1  # read DAA efuse bit
efuse hex:
00
ewriter 0 31 32  # read Public Key Hash0 efuse field
efuse hex:
00000000000000000000000000000000
00000000000000000000000000000000

5. Write public key hash and enable SBC/DAA on eFuse

  • 5.1. Generate your own SBC public key hash:

Users can find the SBC public key hash by checking the build log of TF-A. For example, in case of using i350-evk, the build log file can be found under build/tmp/work/i350_evk-poky-linux/bl2/2.6-r0/temp/log.do_gen_bl2_img. Then, users can write the public key hash string into eFuse with using eFuse writer as explained in section 5.2.

=== Public Key Hash ===
b'0e9b206f5936612793001deec2802b66491c0c1e46e44c0c551784626997d5d9'

Users can also generate public key hash manually by following these steps:

git clone https://gitlab.com/mediatek/aiot/nda/mtk-secure-boot-tools
cd mtk-secure-boot-tools
python3 sign-image_v2/pbp.py -j efuse.pem -func keyhash_pss -o keyhash

The output keyhash is the binary blob of public key hash.

  • 5.2. Enable SBC/DAA on eFuse:

For enabling secure boot (BL1 to BL2), users need to write the specific eFuse index.
The eFuse index includes SBC/DAA enablement and public key hash.
For example: (The efuse index may be different on different platforms.)

Caution

The efuse index is different on different platforms. Please check the efuse index before writing eFuse fields. The efuse index information is only provided with NDA license. Please contact your Mediatek customer window to have access permission for eFuse index information.

Please visit the MediaTek On-Line and find the eFuse Writer User Guide of the platform by the keyword IoT_Open_Platform_eFuse_Writer_User_Guide. It will assist you to generate the correct public key hash for Public Key Hash0 efuse field.

ewriter 1 18 1 1 # enable SBC efuse bit
efuse hex:
01
ewriter 1 19 1 1 # enable DAA efuse bit
efuse hex:
01
ewriter 1 31 32 <EFUSE_PUBLIC_KEY_HASH> # write your own Public Key Hash0 efuse field
efuse hex:
<EFUSE_PUBLIC_KEY_HASH>

6. Read back the Secure boot efuse settings

If the device have SBC and DAA enabled, these secure boot related fields should now be updated:
For example: (The efuse index may be different on different platforms.)
ewriter 0 18 1  # read SBC efuse bit
efuse hex:
01
ewriter 0 19 1  # read DAA efuse bit
efuse hex:
01
ewriter 0 31 32 # read Public Key Hash0 efuse field
efuse hex:
<EFUSE_PUBLIC_KEY_HASH>

7. Flash “bl2.img” with aiot-bootrom (optional)

If you would like to update BL2 image only, you could refer to the commands below. If DAA is enabled, the auth_sv5.auth is required and BROM will load/verify/boot Download Agent. Please make sure the auth_sv5.auth file is existed in the deploy/images/<machine> folder.

unzip -j secure-i350-evk.zip auth_sv5.auth
aiot-bootrom -b lk.bin -s lk.sign
fastboot flash mmc0boot0 bl2.img

Note

DAA is not yet supported by all platforms. Currently, this is only supported by i350-evk and i350-pumpkin. For the other platforms, please follow regular instructions to flash bl2.img.

Please make sure the aiot-tools are up-to-date, otherwise -s might not be supported in your aiot-bootrom version.

Secure Boot: BL2 to fip images

The BL2 image contains an RSA public key and will use it to verify fip images (signed with the private key).

By default, yocto will use a development key and print a warning about it.

To generate own private key:

openssl genrsa -out ${KEYDIR}/rot_key.pem 2048

Then, update local.conf to tell yocto to use your key:

SECURE_BOOT_ROT_KEY = "${KEYDIR}/rot_key.pem"

If the fip images is not signed or signed with another key, BL2 will detect it and rise this kind of errors: (baudrate 115200):

[EMI] mcp_dram_num:0,discrete_dram_num:1,enable_combo_dis:0
[EMI] MDL number = 0
[MEM] complex R/W mem test pass
ERROR:   BL2: Failed to load image id 3 (-2)

Secure Boot: fip images to fitImage

The fip images contains an RSA public key and will use it to verify fitImage (signed with the private key).

By default, if there are no keys provided, yocto will not sign the fitImage and u-boot will not complain about it.

To generate the keys and sign the fitImage, add the following variables to your local.conf

DISTRO_FEATURES:append = " secure-boot"
FIT_GENERATE_KEYS = "1"
FIT_SIGN_INDIVIDUAL = "1"
UBOOT_SIGN_KEYNAME="u-boot"
UBOOT_SIGN_IMG_KEYNAME="u-boot-img"
UBOOT_SIGN_KEYDIR = "${KEYDIR}"

If the keys do not exist, yocto will create them and put them in ${KEYDIR}. The fitImage will be signed, in addition of the kernel and the device tree and the u-boot device tree will be update with the public key required to check fitImage signature.

If the fitImage is not signed or signed with another key, u-boot will detect it and rise this kind of errors:

No 'signature' subnode found for '<NULL>' hash node in 'conf-mediatek_mt8365-evk.dtb' config node
Failed to verify required signature 'key-u-boot'
Bad Data Hash
ERROR: can't get kernel image!

Secure Boot: Summary

For building signed images and enable secure boot, there are total 5 steps:

1. First of all, Generate the keys

export KEYDIR=${HOME}/keys
mkdir -p ${KEYDIR}
openssl genrsa -out ${KEYDIR}/efuse.pem 2048
openssl genrsa -out ${KEYDIR}/da.pem 2048
openssl genrsa -out ${KEYDIR}/rot_key.pem 2048

2. Update the local.conf to enable secure boot

NDA_BUILD = "1"

DISTRO_FEATURES:append = " secure-boot"
KEYDIR = "${HOME}/keys"
EFUSE_KEY = "${KEYDIR}/efuse.pem"
DA_KEY = "${KEYDIR}/da.pem"
BL2_SIGN_ENABLE = "1"
DA_SIGN_ENABLE = "1"
SECURE_BOOT_ROT_KEY = "${KEYDIR}/rot_key.pem"
FIT_SIGN_INDIVIDUAL = "1"
FIT_GENERATE_KEYS = "1"
UBOOT_SIGN_KEYNAME="u-boot"
UBOOT_SIGN_IMG_KEYNAME="u-boot-img"
UBOOT_SIGN_KEYDIR = "${KEYDIR}"
# Generate the secure package
SECURE_ZIP_ENABLE = "1"

3. Build a Rity image

DISTRO=rity-demo bitbake rity-demo-image

4. Enable secure boot with using efuse writer tool

Please refer to section Use eFuse Writer tool.

Important

eFuse Writer tool and the user guide is only provided with NDA license. Please contact your Mediatek customer window to have access permission for eFuse Writer tool.

5. Flash the whole image using aiot-tools

> aiot-flash --daa

Note

Please make sure the aiot-tools are up-to-date, otherwise --daa might not be supported in your aiot-flash version.