AM62 Secure Boot
Quick Overview
This is a quick summary of the steps that need to be done to get Secure Boot to work on the VAR-SOM-AM62x using Yocto. For full instructions, please refer to the detailed sections below.
- Create keys and certificates
Use the provided helper scripts to create the signing keys and certificates for U-Boot and the Linux kernel. - Build the OTP Keywriter Application
Use the generated certificate and the modified version of board.c (provided by Variscite) to build the application - Secure the SOM
Create an SD card with the OTP Keywriter Application. Boot the SOM from this SD card to burn the security keys into the eFuses and secure the device. - Configure Yocto to build signed images
Set the environment variable SIGN_KEYDIR for your Yocto build. The variable must point to a directory that contains the the key data. Also, use `MACHINE=am62x-var-som-secureboot` in your Yocto build configuration. The Yocto build system will then automatically build images for use with the secured SOM.
Introduction - Secure Boot
Secure Boot is an optional feature which allows you to make sure only software signed with a trusted key can be executed on the board.
It incorporates Boot ROM level security which cannot be altered after programming the appropriate one-time electrically programmable fuses (OTP eFuses).
The Boot ROM is responsible for loading the initial software image from the boot medium (SPL/U-Boot, OPTEE, ARM Trusted Firmware). This enables the boot ROM to authenticate the initial software image by using digital signatures. It also provides a mechanism to establish a chain of trust for the remaining software components (such as the kernel image) and thus to establish a secure state of the system.
Content of this Guide
This guide explains how to enable Secure Boot on the AM62x platform. It includes:
- How to secure your SOM so that only signed bootloaders and kernels will be loaded
- How to sign your bootloaders and kernels
The following topics are not covered:
- hardening the system against attackers that have physical access to the SOM
- hardening they system by preventing manipulation of the U-Boot environment
- encrypting the root file system
This is provided as a reference example. Customers must evaluate and modify the implementation as needed to align with their own security policies and deployment needs.
Additional resources and links for further reading are available at the end of this guide.
Secure Boot - Booting the System
The purpose of Secure Boot is to ensure that only the software that is signed with a trusted key can be executed on the SOM. This is done using RSA public key cryptography.
The following provides a simplified version of the Secure Boot process on the AM62x platform:
- The SOM is powered. The Public Boot ROM code is executed. This Boot ROM code is built into the silicon by Texas Instruments and cannot be modified.
- The Boot ROM reads configuration data from OTP eFuses. This includes Secure Boot settings and a hash of the public keys.
- The Public Boot ROM Code will load the next level bootloader (e.g. U-Boot SPL) from the boot media (e.g. eMMC or SD card). If Secure Boot is activated, then the integrity of the binary is verified using the public key hash.
- The SPL initializes the RAM and loads the full U-Boot image. If Secure Boot is enabled, another signature check is performed at this stage.
- The Variscite U-Boot with Secure Boot activated will then verify a FIT image. It will use a public key hash, integrated in the U-Boot binary at build-time. This allows to use different keys for the Linux kernel FIT image and the U-Boot itself.
The actual boot process is more complex because the AM62x uses multiple processor cores and separate binaries for each. A more detailed explanation is available on the Secure Boot Wiki for the AM62x
When using the Yocto build environment provided by Variscite, note the following difference:
- The default U-Boot (non-secure version) allows booting a Linux kernel directly (using the file named Image along with a .dtb file), which is helpful for development and debugging.
- In contrast, the Secure Boot version disables the option to boot unsigned kernel images. Only FIT images with a valid signature can be booted.
Secure Boot - Building the OTP Keywriter Application to Burn the eFuses
To enable Secure Boot on a SOM, specific eFuses must be programmed. This process converts an "open" SOM into a "secured" SOM.
Texas Instruments uses the following terms:
- HS-FS (High Security – Field Securable): Devices that can be secured by programming eFuses.
- HS-SE (High Security – Security Enforced): Devices that have already been secured.
- GP (General Purpose): Devices without security features. Variscite does not ship those devices.
Unfortunately Variscite cannot provide an SD card for direct usage. Instead a stand-alone application that has the key data embedded into the binary needs to be built. Texas Instrument calls this the OTP Keywriter Application.
Prerequisites
To build the OTP Keywriter Application, the following are needed:
- a Linux Ubuntu Ubuntu 20.04 installation with OpenSSL 1.1.1. (Ubuntu 22.04 and later ship with OpenSSL 3.x which is incompatible)
- OPT Keywriter Add-on for MCU Plus SDK 09.01.00.39. Variscite is not allowed to provide this file for legal reasons. A sales represantative from Texas Instruments needs to be contacted to receive it
- Internet connection for downloading tools from Texas Instruments
The recommended container to build Yocto for the AM62x is Ubuntu 22.04. For the OTP Keywriter Application, Ubuntu 20.04 should be used. It is unproblematic to use different container for the Yocto build and the OTP Keywriter Application build.
Installation Steps
This guide assumes some familiarity with the article on Docker Build Environment.
Start the Ubuntu 20.04 container
$ cd ~/var-host-docker-containers $ ./run.sh -u 20.04 $ grep DESCRIPTION /etc/lsb-release DISTRIB_DESCRIPTION="Ubuntu 20.04.6 LTS" $ openssl version OpenSSL 1.1.1f 31 Mar 2020
Ensure that OpenSSL version 1.1.1 is used. Newer versions of OpenSSL (such as version 3.x) must be avoided. Although the OTP Keywriter Application can be built with newer versions, using them will cause an "internal error" when attempting to burn the eFuses.
The provided Docker image already includes all required packages from the Ubuntu package repository. However, some tools must still be installed manually.
The following instructions will install these tools into the /workdir directory inside the Docker container. This allows the tools to be reused in later sessions.
Download the required tools from the official Texas Instruments servers.
$ cd /workdir $ mkdir ti $ cd ti/ $ wget -q https://dr-download.ti.com/software-development/software-development-kit-sdk/MD-IIN1zFBAlS/09.01.00.39/mcu_plus_sdk_am62x_09_01_00_39-linux-x64-installer.run $ md5sum mcu_plus_sdk_am62x_09_01_00_39-linux-x64-installer.run 6165e1b68531926ea96f251a69823f10 mcu_plus_sdk_am62x_09_01_00_39-linux-x64-installer.run $ wget -q https://dr-download.ti.com/software-development/ide-configuration-compiler-or-debugger/MD-nsUM6f7Vvb/1.18.0.3266/sysconfig-1.18.0_3266-setup.run $ md5sum sysconfig-1.18.0_3266-setup.run 7d9a7fb41320f91c98457432e65dae1d sysconfig-1.18.0_3266-setup.run $ wget -q https://dr-download.ti.com/software-development/ide-configuration-compiler-or-debugger/MD-ayxs93eZNN/3.2.0.LTS/ti_cgt_armllvm_3.2.0.LTS_linux-x64_installer.bin $ md5sum ti_cgt_armllvm_3.2.0.LTS_linux-x64_installer.bin 83543ce418bf4788326006a93d65a4c8 ti_cgt_armllvm_3.2.0.LTS_linux-x64_installer.bin
Also put the OTP Keywriter Add-on from Texas Instruments in that folder
$ md5sum am62x-security-secure-tools.zip 76e72c8abf78e9ef8e65db0f0de3f8a3 am62x-security-secure-tools.zip $ unzip am62x-security-secure-tools.zip Archive: am62x-security-secure-tools.zip creating: am62x-security-secure-tools/ inflating: am62x-security-secure-tools/otp_keywriter_am62ax-linux-installer.run inflating: am62x-security-secure-tools/otp_keywriter_am62px_SR_10_09_01_00_05-windows-x64-installer.exe inflating: am62x-security-secure-tools/SPRUIM0C-C-windows-installer.exe inflating: am62x-security-secure-tools/otp_keywriter_am62x-windows-installer.exe inflating: am62x-security-secure-tools/otp_keywriter_am62x-linux-installer.run inflating: am62x-security-secure-tools/otp_keywriter_am62ax-windows-installer.exe inflating: am62x-security-secure-tools/otp_keywriter_am62px_SR_10_09_01_00_05-linux-x64-installer.run inflating: am62x-security-secure-tools/SPRUIM0C-C-linux-x64-installer.run $ mv am62x-security-secure-tools/otp_keywriter_am62x-linux-installer.run . $ md5sum otp_keywriter_am62x-linux-installer.run f7a3ea8a701b490c5cb9a9f7093300af otp_keywriter_am62x-linux-installer.run
Other versions of these files might work but have not been tested by Variscite.
Make sure that all installer binaries are executable.
$ chmod a+x *.run *.bin
Start with the installation of the tools. Installation is rather straight-forward for all tools:
- Execute binary in text mode
- select English as language
- accept EULA
- install to /workdir/ti/tools/<packagename>. Don't install to the default suggestion /home/<username>/ti
$ ./mcu_plus_sdk_am62x_09_01_00_39-linux-x64-installer.run --mode text Language Selection Please select the installation language [..] Please choose an option [13] : ---------------------------------------------------------------------------- Welcome to the mcu_plus_sdk_am62x_09_01_00_39 Setup Wizard. ---------------------------------------------------------------------------- Please specify the directory where mcu_plus_sdk_am62x_09_01_00_39 will be installed. Installation Directory [/home/vari/ti]: /workdir/ti/tools/ ---------------------------------------------------------------------------- Setup is now ready to begin installing mcu_plus_sdk_am62x_09_01_00_39 on your computer. Do you want to continue? [Y/n]: ---------------------------------------------------------------------------- Please wait while Setup installs mcu_plus_sdk_am62x_09_01_00_39 on your computer. Installing 0% ______________ 50% ______________ 100% ######################################### ---------------------------------------------------------------------------- Setup has finished installing mcu_plus_sdk_am62x_09_01_00_39 on your computer.
OPT Keywriter Application needs to be installed into a specific directory
$ ls tools/ mcu_plus_sdk_am62x_09_01_00_39 $ mkdir tools/mcu_plus_sdk_am62x_09_01_00_39/source/security $ ./otp_keywriter_am62x-linux-installer.run --mode text Language Selection Please select the installation language [..] Please choose an option [13] : ---------------------------------------------------------------------------- Created with an evaluation version of InstallBuilder Welcome to the otp_keywriter_am62x Setup Wizard. ---------------------------------------------------------------------------- Please read the following License Agreement. You must accept the terms of this agreement before continuing with the installation. Press [Enter] to continue: [.. Here follows the EULA text] TILAW-#352383-v9-EP_Security_Software_SLA_and_Non-Disclosure_Agreement.txt Press [Enter] to continue: Do you accept this license? [y/n]: y ---------------------------------------------------------------------------- Please specify the directory where otp_keywriter_am62x will be installed. Installation Directory [/home/vari/ti/otp_keywriter_am62x_09_00_00]: /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security ---------------------------------------------------------------------------- Setup is now ready to begin installing otp_keywriter_am62x on your computer. Do you want to continue? [Y/n]: ---------------------------------------------------------------------------- Please wait while Setup installs otp_keywriter_am62x on your computer. Installing 0% ______________ 50% ______________ 100% ######################################### ---------------------------------------------------------------------------- Setup has finished installing otp_keywriter_am62x on your computer. View Readme file? [Y/n]: N $ ls tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/ sbl_keywriter uninstall uninstall.dat
Installation of sysconfig is rather straight-forward
$ ./sysconfig-1.18.0_3266-setup.run --mode text ---------------------------------------------------------------------------- Welcome to the TI System Configuration Tool Setup Wizard. ---------------------------------------------------------------------------- Please read the following License Agreement. You must accept the terms of this agreement before continuing with the installation. Press [Enter] to continue: [.. EULA omitted] Do you accept this license? [y/n]: y ---------------------------------------------------------------------------- Please specify the directory where TI System Configuration Tool will be installed. Installation Directory [/home/vari/ti/sysconfig_1.18.0]: /workdir/ti/tools/sysconfig_1.18.0 ---------------------------------------------------------------------------- Setup is now ready to begin installing TI System Configuration Tool on your computer. Do you want to continue? [Y/n]: ---------------------------------------------------------------------------- Please wait while Setup installs TI System Configuration Tool on your computer. Installing 0% ______________ 50% ______________ 100% ######################################### ---------------------------------------------------------------------------- Setup has finished installing TI System Configuration Tool on your computer. Create Desktop Shortcut [y/N]: Launch TI System Configuration Tool [Y/n]: n
The last piece of software that needs to be installed is the ARM CGT CLANG
$ ./ti_cgt_armllvm_3.2.0.LTS_linux-x64_installer.bin --mode text ---------------------------------------------------------------------------- Welcome to the ARM_LLVM Code Generation Tools Setup Wizard. ---------------------------------------------------------------------------- Select Installation Directory Please specify the directory where ARM_LLVM Code Generation Tools will be installed. The installation requires 1020086 KB. Destination Directory [/workdir/ti/ti-cgt-armllvm_3.2.0.LTS]: /workdir/ti/tools/ti-cgt-armllvm_3.2.0.LTS ---------------------------------------------------------------------------- Setup is now ready to begin installing ARM_LLVM Code Generation Tools on your computer. Do you want to continue? [Y/n]: ---------------------------------------------------------------------------- Please wait while Setup installs ARM_LLVM Code Generation Tools on your computer. Installing 0% ______________ 50% ______________ 100% ######################################### ---------------------------------------------------------------------------- Setup has finished installing ARM_LLVM Code Generation Tools on your computer.
Variscite Modifications for OTP Keywriter Application
Texas Instruments provides the application that is needed to create the OTP Keywriter Application, but it needs to be adapted for Variscite Boards. The necessary modifications can be found in the repository var-sbl-keywriter-support
Please copy the files board.c and example.syscfg to the folder /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/, replacing the files already present in that directory.
These modifications make the necessary changes so that the OTP Keywriter Application runs properly on the VAR-SOM hardware.
Generate Keys for OTP Keywriter Application (and Linux kernel)
Texas Instruments provides a script to generate the cryptographic keys needed to sign the U-Boot bootloader. These keys can also be used later to sign the Linux kernel.
First the the keys need to be generated. This is a good time to double-check the OpenSSL version 1.1.1. (Newer versions are not supported)
$ cd /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/sbl_keywriter/scripts/cert_gen/am62x/ $ openssl version OpenSSL 1.1.1f 31 Mar 2020 $ ls construct_ext_otp_data.sh generate_test_binaries.sh gen_keywr_cert_helpers.sh gen_keywr_cert.sh keys_devel templates tifek $ ./gen_keywr_cert.sh -g # Generating random keys in keys/folder Generating RSA private key, 4096 bit long modulus (2 primes) .......................................................++++ ......................................................................++++ e is 65537 (0x010001) Generating RSA private key, 4096 bit long modulus (2 primes) ...........................................................++++ .........................................................................................................................................................................................................++++ e is 65537 (0x010001) $ ls construct_ext_otp_data.sh generate_test_binaries.sh gen_keywr_cert_helpers.sh gen_keywr_cert.sh keys keys_devel templates tifek $ mv keys keys_variscite $ ls -l keys_variscite/ total 20 -rw-rw-r-- 1 vari vari 32 May 18 20:02 aes256.key -rw-rw-r-- 1 vari vari 32 May 18 20:02 bmek.key -rw------- 1 vari vari 3243 May 18 20:02 bmpk.pem -rw-rw-r-- 1 vari vari 32 May 18 20:02 smek.key -rw------- 1 vari vari 3247 May 18 20:02 smpk.pem
The relevant files here are
- smpk.pem: the Secondary Manufacturer Private Key (TI being the Primary Manufacturer)
- bmpk.pem: the Backup Manufacturer Private Key
It is possible that the file size of these files differ.
Having two keys makes it possible to later revoke the first key and only use the backup key. However, in our example only the secondary key will be used.
These are private keys. Make sure to not share them publicly. However, these files will be needed later.
The next step is to generate a certificate.
$ cd /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/sbl_keywriter/scripts/cert_gen/am62x #same folder as before $ ./gen_keywr_cert.sh -t tifek/ti_fek_public.pem --msv 0xC0FFE -s keys_variscite/smpk.pem --smek keys_variscite/smek.key --keycnt 1 --keyrev 1 # Using MSV[19:0]: 0x000C0FFE # Using Key Count: 0x00000001 # Using Key Rev: 0x00000001 Generating Single signed certificate!! GEN: AES256 key generated, since not provided # encrypt aes256 key with tifek public part # encrypt SMPK-priv signed aes256 key(hash) with tifek public part # encrypt smpk-pub hash using aes256 key writing RSA key # encrypt smek (sym key) using aes256 key 4000 primary_cert.bin 4000 ../../x509cert/final_certificate.bin # SHA512 Hashes of keys are stored in verify_hash.csv for reference.. $ ls -l ../../ cert_gen/ x509cert/ $ ls -l ../../x509cert/final_certificate.bin -rw-rw-r-- 1 vari vari 4000 Jun 11 09:36 ../../x509cert/final_certificate.bin
The final certificate file size is below the 5400 byte limit.
The resulting certificate is in a different folder and needs to be converted:
$ cd /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/sbl_keywriter/scripts/x509cert/ $ ls final_certificate.bin $ python3 ../../../../../tools/bin2c/bin2c.py final_certificate.bin keycert.h KEYCERT $ ls final_certificate.bin keycert.h
keycert.h is the header file that will later be used during the build process. It does not need to be moved to a different location.
Building the OTP Keywriter Application
Make sure that you have executed all steps in Variscite Modifications for OTP Keywriter Application and have also created and converted the keys as described in the section above. After you have done that you can build the OTP Keywriter Application.
$ cd /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/ti-arm-clang/ $ TOOLS_PATH=/workdir/ti/tools/ make -sj PROFILE=debug clean Cleaning: am62x:r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out ... $ TOOLS_PATH=/workdir/ti/tools/ make -sj PROFILE=debug Generating SysConfig files ... Running script... Validating... Generating Code (example.syscfg)... Writing /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/ti-arm-clang/generated/ti_dpl_config.c... Writing /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/ti-arm-clang/generated/ti_dpl_config.h... Writing /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/ti-arm-clang/generated/ti_drivers_config.c... Writing /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/ti-arm-clang/generated/ti_drivers_config.h... Writing /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/ti-arm-clang/generated/ti_drivers_open_close.c... Writing /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/ti-arm-clang/generated/ti_drivers_open_close.h... Writing /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/ti-arm-clang/generated/ti_pinmux_config.c... Writing /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/ti-arm-clang/generated/ti_power_clock_config.c... Writing /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/ti-arm-clang/generated/ti_board_config.c... Writing /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/ti-arm-clang/generated/ti_board_config.h... Writing /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/ti-arm-clang/generated/ti_board_open_close.c... Writing /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/ti-arm-clang/generated/ti_board_open_close.h... Compiling: am62x:r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out: ../main.c Compiling: am62x:r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out: ../keywriter_utils.c Compiling: am62x:r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out: ../board.c Compiling: am62x:r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out: generated/ti_drivers_config.c Compiling: am62x:r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out: generated/ti_drivers_open_close.c Compiling: am62x:r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out: generated/ti_board_config.c Compiling: am62x:r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out: generated/ti_board_open_close.c Compiling: am62x:r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out: generated/ti_dpl_config.c Compiling: am62x:r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out: generated/ti_pinmux_config.c Compiling: am62x:r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out: generated/ti_power_clock_config.c . Linking: am62x:r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out ... Linking: am62x:r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out Done !!! . Boot image: am62x:r5fss0-0:nortos:ti-arm-clang /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/ti-arm-clang/sbl_keywriter.debug.tiimage ... Boot image: am62x:r5fss0-0:nortos:ti-arm-clang /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/ti-arm-clang/sbl_keywriter.debug.tiimage Done !!!
The result of that build is the file tiboot3.bin.
Create an SD Card with the OTP Keywriter Application
Securing a board is done by booting from an SD card with the OTP Keywriter binary on it.
The easiest way to create such an SD card is to start with an SD Recovery Card. Please follow the instructions from Yocto Recovery SD card to create one.
After you have created the SD card, please re-insert the SD card into your development PC card-reader and mount the SD card (depending on the system, this might happen automatically). Then copy the file tiboot3.bin to the SD card, overwriting the existing file. Unmount the filesystem properly. Depending on your setup this may look something like this:
$ mount /dev/sda1 /mnt/boot # ensure that there is a tiboot3.bin to replace in that folder $ ls /mnt/boot/tiboot3.bin tiboot3.bin $ cp /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/sbl_keywriter/am62x-sk/r5fss0-0_nortos/ti-arm-clang/tiboot3.bin /mnt/boot/ umount /mnt/boot
Executing the OTP Keywriter Application (fusing the board)
Executing the OTP Keywriter Application is simply booting from the SD card you have just created. Make sure that your carrier board is configured to boot from SD card, insert the SD card and then power the board. You will see the following output:
Starting Keywriting Enabled VPP keys Certificate found: 0x43c15480 Keywriter Debug Response:0x0 Success Programming Keys
That's it. This SOM is now secured and will no longer boot unsigned bootloaders.
Additional Reading on OTP Keywriter Application
Texas Instruments also provides some additional documentation on the OTP Keywriter Application.
Integrating Secure Boot in Yocto to Build Signed U-Boot and Kernel Binaries
Variscite provides an easy way to integrate Secure Boot into its Yocto layer. To build images with signed bootloaders and kernels, use the following setting.
``` MACHINE=am62x-var-som-secureboot ```
This setting can either be specified on the command line when building packages or images with Yocto, or you can set this in your local.conf or your customer-specific layer.
am62x-var-som-secureboot is derived from the am62x-var-som machine and inherits all its features, but will add Secure Boot to it. It also requires a second variable to be set: SIGN_KEYDIR
- This variable is not set by default.
- This variable SIGN_KEYDIR must point to a directory containing key data. This directory must be accessible at build time. When a Docker container is used to build the Yocto image, it must be a path that is accessible from within the Docker container.
Provisioning of the Key Data
To build a signed version of U-Boot and the Linux kernel, the build process needs access to private keys. Since these are the private keys, it is important to keep them secure and avoid sharing them publicly. For this reason it is recommended to
- not integrate the private keys as part of the U-Boot repository
- not store them as part of your custom layer if this means that a lot of developers will be able to access it
Instead the environment variable SIGN_KEYDIR can be used. It may point to any directory accessible during the Yocto build. For the following example, this entry was used
$ cd /workdir/oe-layersetup/build # or wherever your build folder is positioned
$ tail conf/local.conf
[.. more entries]
SIGN_KEYDIR="${TOPDIR}/variscite_keys"
$ ls -l /workdir/oe-layersetup/build/variscite_keys/
total 16
-rw-r--r-- 1 vari vari 1939 Apr 30 10:35 custMpk.crt
-rw-r--r-- 1 vari vari 3247 Apr 30 10:35 custMpk.key
-rw-r--r-- 1 vari vari 3247 Apr 30 10:35 custMpk.pem
Files in the key directory
- custMpk.pem: This is the file smpk.pem, which was put in the folder /workdir/ti/tools/mcu_plus_sdk_am62x_09_01_00_39/source/security/sbl_keywriter/scripts/cert_gen/am62x/keys_variscite/ when the keys for the OTP Keywriter Application were generated. The file simply needs to be copied and renamed.
- custMpk.key: This is the private key used for signing the Linux Kernel FIT Image later. This can be a copy of custMpk.pem in which case the identical key is shared for signing the U-Boot and the Linux Kernel FIT Image. If you don't want the key to be identical, you can also create a new one with the following call
vari@20-04-dd7218bb:/workdir/oe-layersetup/build$ openssl genpkey -algorithm RSA -out variscite_keys/custMpk.key -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:65537
- custMpk.crt: Certificate, containing the public key. You can create this using the following command:
vari@20-04-dd7218bb:/workdir/oe-layersetup/build$ openssl req -batch -new -x509 -key varscite_keys/custMpk.key -out varscite_keys/custMpk.crt
The next step need to done on the machine that does the Yocto build. This could be a different virtual machine (e.g. Ubuntu 22.04 instead of Ubuntu 20.04).
If you change the keys in the key directory and this directory is not part of a Yocto recipe, then the Yocto build system cannot detect that these keys have been modified. You can force a patching of the key data by running the following commands:
$ MACHINE=am62x-var-som-secureboot bitbake u-boot-variscite -f -c patch $ MACHINE=am62x-var-som-secureboot bitbake mc:k3r5:u-boot-variscite -f -c patch
After that you can build your normal image and the U-Boot and the Linux kernel will be signed properly, e.g.
$ MACHINE=am62x-var-som-secureboot bitbake var-default-image
The signed files will be both part of the image file but will also be part of the deploy directory.
Additional Reading on U-Boot Secure Boot
The following resources can also be interesting:
- U-Boot FIT Signature Verification
- U-Boot Verified Boot
- U-Boot AM62 Platforms
- U-Boot K3 Generation (base for several TI platforms)
Further Hardening the System and Additional Reading
The method described in this article is only the first step to create a security-enabled device. This is provided as a reference example. Customers must evaluate and modify the implementation as needed to align with their own security policies and deployment needs. The following list provides some things you might want to consider:
- The U-Boot environment is currently still modifiable. This means that a malicious attacker might attempt to modify the boot command. While boot commands that would allow to directly boot into a non-signed image have been deactivated in the Secure Boot configuration, this would still permit to modify the content of RAM. Keep in mind that some software update mechanisms rely on a writable U-Boot environment.
- The interactive U-Boot shell has not been deactivated. This allows attackers with physical attack of the device to modify the boot command. While boot commands that would allow to directly boot into a non-signed image have been deactivated in the Secure Boot configuration, this would still permit to modify the content of the RAM.
- While U-Boot and the Linux Kernel are now verified at boot time, the root file system is not verified. A malicious attacker could modify the content of the root file system and thereby execute own code. If this is relevant to your product consider adding signed read-only images or to encrypt your images.
Here is some interesting additional reading on Securing U-Boot: A Guide to Mitigating Common Attack Vectors