AM62P 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-AM62P 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=am62px-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 AM62P 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 AM62P 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 AM62P uses multiple processor cores and separate binaries for each. A more detailed explanation is available on the Secure Boot Wiki for the AM62px.

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.

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 22.04 installation with OpenSSL >= 3.0.0. (Ubuntu 20.04 or earlier ship with OpenSSL 1.1.1 which is incompatible)
OTP 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

CAUTION Even if you build applications using the MCU Plus SDK with a newer release version, you must use version 09.01.00.39 for building the OTP Keywriter Application

You can use the Docker container provided for building the Yocto build with Ubuntu 22.04.

CAUTION If you have previously used Secure Boot on the AM62x, you will need a different version of OpenSSL. For the AM62x, OpenSSL 1.1.1 is needed, while you need OpenSSL > 3.0.0 for the AM62P.

Installation Steps¶

This guide assumes some familiarity with the article on Docker Build Environment.

Start the Ubuntu 22.04 container

$ cd ~/var-host-docker-containers
$ ./run.sh -u 22.04
$ grep DESCRIPTION /etc/lsb-release
DISTRIB_DESCRIPTION="Ubuntu 22.04.5 LTS"
$ openssl version
OpenSSL 3.0.2 15 Mar 2022 (Library: OpenSSL 3.0.2 15 Mar 2022)

Ensure that OpenSSL version 3.0.0 or later is used. Older versions of OpenSSL must be avoided.

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-68ibsyT7Ks/09.01.00.39/mcu_plus_sdk_am62px_09_01_00_39-linux-x64-installer.run
$ md5sum mcu_plus_sdk_am62x_09_01_00_39-linux-x64-installer.run
8b5127cb04399913f5b739f6d1a34171  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_am62px_SR_10_09_01_00_05-linux-x64-installer.run .
$ md5sum otp_keywriter_am62px_SR_10_09_01_00_05-linux-x64-installer.run
52daba4022f2c972bd94fbc208d905b7  otp_keywriter_am62px_SR_10_09_01_00_05-linux-x64-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/. Don't install to the default suggestion /home//ti

$ ./mcu_plus_sdk_am62px_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_am62px_09_01_00_39 Setup Wizard.

----------------------------------------------------------------------------
Please specify the directory where mcu_plus_sdk_am62px_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_am62px_09_01_00_39 on your
computer.

Do you want to continue? [Y/n]:

----------------------------------------------------------------------------
Please wait while Setup installs mcu_plus_sdk_am62px_09_01_00_39 on your
computer.

 Installing
 0% ______________ 50% ______________ 100%
 #########################################

----------------------------------------------------------------------------
Setup has finished installing mcu_plus_sdk_am62px_09_01_00_39 on your computer.

OTP Keywriter Application needs to be installed into a specific directory

$ ls tools/
mcu_plus_sdk_am62px_09_01_00_39
$ mkdir tools/mcu_plus_sdk_am62px_09_01_00_39/source/security
$ ./otp_keywriter_am62px-SR_10_09_00_5-linux-x64-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_am62px_SR_10 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_am62px__SR10_09_01_00_05]: /workdir/ti/tools/mcu_plus_sdk_am62px_09_01_00_39/source/security

----------------------------------------------------------------------------
Setup is now ready to begin installing otp_keywriter_am62px_SR_10 on your computer.

Do you want to continue? [Y/n]:

----------------------------------------------------------------------------
Please wait while Setup installs otp_keywriter_am62px_SR_10 on your computer.

 Installing
 0% ______________ 50% ______________ 100%
 #########################################

----------------------------------------------------------------------------
Setup has finished installing otp_keywriter_am62px_SR_10 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_am62px_09_01_00_39/source/security/sbl_keywriter/am62px/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 > 3.0.0 (Older versions are not supported)

$ cd /workdir/ti/tools/mcu_plus_sdk_am62px_09_01_00_39/source/security/sbl_keywriter/scripts/cert_gen/am62px/
$ openssl version
OpenSSL 3.0.2 15 Mar 2022 (Library: OpenSSL 3.0.2 15 Mar 2022)
$ ./gen_keywr_cert.sh -g
$ mv keys keys_variscite
$ ls -l keys_variscite/*
-rw-rw-r-- 1 vari vari   32 Sep 10 14:24 keys_variscite/aes256.key
-rw-rw-r-- 1 vari vari   32 Sep 10 14:24 keys_variscite/bmek.key
-rw-rw-r-- 1 vari vari   32 Sep 10 14:24 keys_variscite/smek.key

keys_variscite/v15:
total 8
-rw------- 1 vari vari 3243 Sep 10 14:24 bmpk.pem
-rw------- 1 vari vari 3243 Sep 10 14:24 smpk.pem

keys_variscite/v22:
total 8
-rw------- 1 vari vari 3341 Sep 10 14:24 bmpk.pem
-rw------- 1 vari vari 3341 Sep 10 14:24 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

We only need the v15 version of these files.

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.

WARNING It is only possible to use a certificate with a maximum size of 6144 byte. In our example, we will not make use of the Backup Manufacturer Key. This way we can ensure that we stay below the limit of 6144 bytes. There is additional information on this, provided by the documentation that comes with the OTP Keywriter Application. Please check $MCU_PLUS_SDK_INSTALL_DIR/source/security/sbl_keywriter/docs/_build_am62px/html/index.html

$ 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/SR_10/ti_fek_public.pem --msv 0xC0FFE -s keys_variscite/v15/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  PKCS#1v1.5  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
# 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..

The final certificate file size is below the 6144 byte limit.

The resulting certificate is in a different folder. For the AM62Px release, the files from that folder will be used by the next build stage - no manual copying needed.

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_am62px_09_01_00_39/source/security/sbl_keywriter/am62px/wkup-r5fss0-0_nortos/ti-arm-clang/
$ TOOLS_PATH=/workdir/ti/tools/ make -sj PROFILE=debug clean
Cleaning: am62px:wkup-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_am62px_09_01_00_39/source/security/sbl_keywriter/am62px/wkup-r5fss0-0_nortos/ti-arm-clang/generated/ti_dpl_config.c...
Writing /workdir/ti/tools/mcu_plus_sdk_am62px_09_01_00_39/source/security/sbl_keywriter/am62px/wkup-r5fss0-0_nortos/ti-arm-clang/generated/ti_dpl_config.h...
Writing /workdir/ti/tools/mcu_plus_sdk_am62px_09_01_00_39/source/security/sbl_keywriter/am62px/wkup-r5fss0-0_nortos/ti-arm-clang/generated/ti_drivers_config.c...
Writing /workdir/ti/tools/mcu_plus_sdk_am62px_09_01_00_39/source/security/sbl_keywriter/am62px/wkup-r5fss0-0_nortos/ti-arm-clang/generated/ti_drivers_config.h...
Writing /workdir/ti/tools/mcu_plus_sdk_am62px_09_01_00_39/source/security/sbl_keywriter/am62px/wkup-r5fss0-0_nortos/ti-arm-clang/generated/ti_drivers_open_close.c...
Writing /workdir/ti/tools/mcu_plus_sdk_am62px_09_01_00_39/source/security/sbl_keywriter/am62px/wkup-r5fss0-0_nortos/ti-arm-clang/generated/ti_drivers_open_close.h...
Writing /workdir/ti/tools/mcu_plus_sdk_am62px_09_01_00_39/source/security/sbl_keywriter/am62px/wkup-r5fss0-0_nortos/ti-arm-clang/generated/ti_pinmux_config.c...
Writing /workdir/ti/tools/mcu_plus_sdk_am62px_09_01_00_39/source/security/sbl_keywriter/am62px/wkup-r5fss0-0_nortos/ti-arm-clang/generated/ti_power_clock_config.c...
Writing /workdir/ti/tools/mcu_plus_sdk_am62px_09_01_00_39/source/security/sbl_keywriter/am62px/wkup-r5fss0-0_nortos/ti-arm-clang/generated/ti_board_config.c...
Writing /workdir/ti/tools/mcu_plus_sdk_am62px_09_01_00_39/source/security/sbl_keywriter/am62px/wkup-r5fss0-0_nortos/ti-arm-clang/generated/ti_board_config.h...
Writing /workdir/ti/tools/mcu_plus_sdk_am62px_09_01_00_39/source/security/sbl_keywriter/am62px/wkup-r5fss0-0_nortos/ti-arm-clang/generated/ti_board_open_close.c...
Writing /workdir/ti/tools/mcu_plus_sdk_am62px_09_01_00_39/source/security/sbl_keywriter/am62px/wkup-r5fss0-0_nortos/ti-arm-clang/generated/ti_board_open_close.h...
Compiling: am62px:wkup-r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out: ../main.c
Compiling: am62px:wkup-r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out: ../keywriter_utils.c
Compiling: am62px:wkup-r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out: ../board.c
Compiling: am62px:wkup-r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out: generated/ti_drivers_config.c
Compiling: am62px:wkup-r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out: generated/ti_drivers_open_close.c
Compiling: am62px:wkup-r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out: generated/ti_board_config.c
Compiling: am62px:wkup-r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out: generated/ti_board_open_close.c
Compiling: am62px:wkup-r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out: generated/ti_dpl_config.c
Compiling: am62px:wkup-r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out: generated/ti_pinmux_config.c
Compiling: am62px:wkup-r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out: generated/ti_power_clock_config.c
.
Linking: am62px:wkup-r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out ...
Linking: am62px:wkup-r5fss0-0:nortos:ti-arm-clang sbl_keywriter.debug.out Done !!!
.
Boot image: am62px:wkup-r5fss0-0:nortos:ti-arm-clang /workdir/ti/tools/mcu_plus_sdk_am62px_09_01_00_39/source/security/sbl_keywriter/am62px/wkup-r5fss0-0_nortos/ti-arm-clang/sbl_keywriter.debug.hs_fs.tiimage ...
Boot image: am62px:wkup-r5fss0-0:nortos:ti-arm-clang /workdir/ti/tools/mcu_plus_sdk_am62px_09_01_00_39/source/security/sbl_keywriter/am62px/wkup-r5fss0-0_nortos/ti-arm-clang/sbl_keywriter.debug.hs_fs.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_am62px_09_01_00_39/source/security/sbl_keywriter/am62px/wkup-r5fss0-0_nortos/ti-arm-clang/tiboot3.bin /mnt/boot/
umount /mnt/boot

CAUTION Don't use the SD card unless you plan to secure a board. Make sure that you don't use that SD card by accident!!!

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 Keywriter
Enabled VPP

DMSC Firmware Version 9.2.6-v09.02.06-1-gdf86f (Kool
DMSC Firmware revision 0x9
DMSC ABI revision 3.1

keys Certificate found: 0x43c16180
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 at $MCU_PLUS_SDK_INSTALL_DIR/source/security/sbl_keywriter/docs/_build_am62px/html/index.html

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=am62px-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.

am62px-var-som-secureboot is derived from the am62px-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 Sep 10 17:50 custMpk.crt
-rw-r--r-- 1 vari vari 3243 Sep 10 17:49 custMpk.key
-rw-r--r-- 1 vari vari 3243 Sep 10 17:49 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_am62px_09_01_00_39/source/security/sbl_keywriter/scripts/cert_gen/am6ap2x/keys_variscite/v15 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 steps need to done on the machine that does the Yocto build.

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=am62px-var-som-secureboot bitbake u-boot-variscite -f -c patch
$ MACHINE=am62px-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=am62px-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:

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