Generate a Signed Update Package¶
This guide covers creating the SWUpdate signing key pair and building a signed full update package.
Prerequisites¶
- A working build; see Build the ToloMEO Reference Image
opensslavailable in the build environment (present in the devcontainer by default)
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:
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:
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:
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
- Generate a Delta Update — incremental rdiff packages
- Generate an Encrypted Artifact — encrypt the package
- Test Updates in QEMU — install a package on a QEMU device
- Artifacts Collection — the artifact tree and its classes
- Update Mechanism — SWUpdate variables, formats, and files