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
This document explain how to secure each boot transition.
Sections
Secure Boot: BL1 to BL2
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.
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.
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.
& 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.
& 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
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:
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
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.