Skip to content

Enable FIT Image Signing

This guide covers enabling RSA signing of the Linux kernel FIT image in a custom BSP layer built on top of meta-tolomeo-bsp. This mechanism is generic — it is not specific to any silicon vendor.

Prerequisites

  • meta-tolomeo-bsp included in your layer stack
  • RSA key pair for FIT signing available (see Generate the Key Pair), or the DAVE development keys in devel-keys/ for build validation (see Development Keys)

Generate the Key Pair

mkdir -p keys
openssl genpkey -algorithm RSA -out keys/fitImage-sign.key \
    -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:65537
chmod 600 keys/fitImage-sign.key
openssl req -batch -new -x509 -key keys/fitImage-sign.key \
    -out keys/fitImage-sign.crt -days 3650 \
    -subj "/CN=ToloMEO FIT signing key"

The basename must match UBOOT_SIGN_KEYNAME. The build reads <name>.key to sign the FIT image and embeds <name>.crt into the U-Boot device tree for verification.

Warning

Do not passphrase-protect this key — mkimage cannot prompt during a BitBake task.

Note

This key is unrelated to the HAB4 or AHAB SRK set. It signs the kernel FIT image, which U-Boot verifies after the boot ROM has already authenticated U-Boot itself. It still requires the same protection as any signing key.

Enable the Distro Feature

Add to your distro configuration file or machine configuration file:

DISTRO_FEATURES += "secure-boot"

Include the Machine Configuration

Add to your machine .conf file:

require conf/machine/include/u-boot-secure-boot.inc

This include is provided by meta-tolomeo-bsp. It sets the following variables:

Variable Default Description
UBOOT_SIGN_ENABLE derived "1" when secure-boot is active, else "0"
UBOOT_SIGN_KEYDIR "keys" Directory containing the key pair, relative to ${BSPDIR}
UBOOT_SIGN_KEYNAME "dev" Base name for the key files (.key and .crt)
UBOOT_FIT_GENERATE_KEYS "0" Key auto-generation disabled — keys must be provisioned

Include the U-Boot Fragment

For a generic (non-NXP) BSP, add to your U-Boot bbappend:

require recipes-bsp/u-boot/u-boot-fit-signature.inc

This include is provided by meta-tolomeo-bsp. When secure-boot is active it adds the fit-signature.cfg config fragment, enabling CONFIG_FIT_SIGNATURE=y and CONFIG_RSA=y in the U-Boot build.

Note

BSPs using meta-tolomeo-nxp already receive this via recipes-bsp/u-boot/u-boot-secure-boot.inc. Do not add it a second time.

Set Key Variables

Override the default key path and name in your kas configuration file or local.conf:

UBOOT_SIGN_KEYDIR      = "${BSPDIR}/keys"
UBOOT_SIGN_KEYNAME     = "fitImage-sign"
UBOOT_SIGN_IMG_KEYNAME = "fitImage-sign"

The build reads ${UBOOT_SIGN_KEYDIR}/${UBOOT_SIGN_KEYNAME}.key for signing and embeds ${UBOOT_SIGN_KEYDIR}/${UBOOT_SIGN_KEYNAME}.crt into the U-Boot device tree for verification.

Build

kas build kas/<your-machine>_<your-distro>_<your-image>.yml

The signed FIT image is written to the deploy directory:

build/tmp-glibc/deploy/images/<machine>/fitImage-<machine>.bin

Development Keys

DAVE provides a pre-generated RSA key pair in devel-keys/ for build validation:

File Purpose
devel-keys/fitImage-sign.key RSA private key for signing
devel-keys/fitImage-sign.crt X.509 certificate embedded into U-Boot DTB

To use them, create the keys/ symlink and set the key name:

ln -s devel-keys keys

UBOOT_SIGN_KEYDIR      = "${BSPDIR}/keys"
UBOOT_SIGN_KEYNAME     = "fitImage-sign"
UBOOT_SIGN_IMG_KEYNAME = "fitImage-sign"

Warning

The keys in devel-keys/ are publicly known and exist only for build validation. Never use them on a production device.

See also