Skip to content

Generate a Signed Update Package

This guide covers creating the SWUpdate signing key pair and building a signed full update package.

Prerequisites

Generate the Signing Key Pair

Generate an RSA private key protected by a passphrase, and extract its public key. The private key signs the package at build time; the device verifies it with the public key it ships.

mkdir -p keys
cd keys

# Generate password file and RSA private key with AES-256 encryption
echo "<your-passphrase>" > swupdate-sign.pass
openssl genrsa -aes256 -passout file:swupdate-sign.pass -out swupdate-sign 2048

# Extract public key
openssl rsa -in swupdate-sign -out swupdate-sign.pub -outform PEM -pubout

# Protect private key and password file; the public key can be world-readable
chmod 600 swupdate-sign swupdate-sign.pass
chmod 644 swupdate-sign.pub
cd ..

Warning

Never commit keys/swupdate-sign or keys/swupdate-sign.pass; add both to .gitignore. Rotating the key pair needs an update that installs the new public key on the device first, because the device verifies packages with the public key it already holds.

Use Your Own Key Location (Optional)

By default the build reads the key material from ${BSPDIR}/keys, using the key base name swupdate-sign. The meta-tolomeo-distro kas fragment sets both:

Variable Default Description
SWUPDATE_KEYDIR ${BSPDIR}/keys Directory containing all key material (signing and encryption)
SWUPDATE_SIGN_KEYNAME swupdate-sign Base name for the key files, without extension

Set either variable in the kas configuration or local.conf, or export it before calling kas:

export SWUPDATE_KEYDIR="$(pwd)/keys"
export SWUPDATE_SIGN_KEYNAME="swupdate-sign"

The key file paths derive from the two variables:

Variable Derived Path Purpose
SWUPDATE_PRIVATE_KEY ${SWUPDATE_KEYDIR}/${SWUPDATE_SIGN_KEYNAME} RSA private key for signing
SWUPDATE_PUBLIC_KEY ${SWUPDATE_KEYDIR}/${SWUPDATE_SIGN_KEYNAME}.pub RSA public key for verification
SWUPDATE_PASSWORD_FILE ${SWUPDATE_KEYDIR}/${SWUPDATE_SIGN_KEYNAME}.pass Passphrase for the private key

With the defaults, the private key is ${BSPDIR}/keys/swupdate-sign, the public key ${BSPDIR}/keys/swupdate-sign.pub and the password file ${BSPDIR}/keys/swupdate-sign.pass.

Build the Full Update Package

The buildinfo block of the kas configuration assigns BUILD_VERSION, so a shell variable does not override it. Set the version there: in this repository, in meta-tolomeo-qemu/kas/common.yml; in an integration project, in kas/base.yml.

local_conf_header:
  buildinfo: |-
    FIRMWARE_NAME = "TVD-embedded-firmware"
    BUILD_VERSION = "0.2.0"
    SECURITY_PATCH_LEVEL = "26.09"

Then build the target:

kas build kas/tolomeo-qemux86-64_imgen-update-full.yml

The package is collected under:

artifacts/tolomeo-qemux86-64/image-prod/0.2.0/updates/imgen-update-full/
├── build-info.txt
└── imgen-update-full-tolomeo-qemux86-64.rootfs.swu

Verify the Package

List the archive contents:

cpio -tv < artifacts/tolomeo-qemux86-64/image-prod/0.2.0/updates/imgen-update-full/imgen-update-full-tolomeo-qemux86-64.rootfs.swu

Extract it for inspection:

mkdir swu-contents
cd swu-contents
cpio -idv < ../artifacts/tolomeo-qemux86-64/image-prod/0.2.0/updates/imgen-update-full/imgen-update-full-tolomeo-qemux86-64.rootfs.swu

Verify the signature of sw-description with the public key, from inside swu-contents:

openssl dgst -sha256 \
    -verify ../keys/swupdate-sign.pub \
    -signature sw-description.sig \
    sw-description

The command prints:

Verified OK

Troubleshooting

The build stops with SWUPDATE_PUBLIC_KEY must be set

The full message is SWUPDATE_PUBLIC_KEY must be set to the public key file, because SWUPDATE_PUBLIC_KEY is empty. Leave SWUPDATE_KEYDIR and SWUPDATE_SIGN_KEYNAME at their defaults, or set SWUPDATE_PUBLIC_KEY to the public key file.

The build stops with SWUpdate public key not found

The file named in the error does not exist. Generate the key pair, or point SWUPDATE_KEYDIR and SWUPDATE_SIGN_KEYNAME at the existing one.

See also