Generate an Encrypted Artifact¶
This guide covers generating AES-encrypted .swu packages for ToloMEO QEMU targets.
Prerequisites¶
- Signing keys already generated and configured — see Generate a Signed Update Package
opensslavailable in the build environment (present in the devcontainer by default)- A distribution that enables
tlm-update-encrypted; see Enabletlm-update-encrypted
Generate the AES Key¶
Encrypted artifacts use AES-256-CBC. The key and IV are stored together in a single text file.
Key File Format¶
Generate the Key File¶
mkdir -p keys
printf 'key=%s\niv=%s\n' \
"$(openssl rand -hex 32)" \
"$(openssl rand -hex 16)" \
> keys/swupdate-enc
chmod 600 keys/swupdate-enc
Protect the Key¶
Note
The repository contains a development-only key at devel-keys/swupdate-enc for build validation. Anyone with the
file can decrypt all packages built with it, so never use it in production.
Warning
Never commit a production AES key. Every target device must receive a new key before a package encrypted with it reaches the device, and that delivery needs a separate secure channel. See Encrypted Updates.
Enable tlm-update-encrypted¶
Add tlm-update-encrypted to DISTRO_FEATURES in the distro configuration. No reference distribution enables it.
Set it in the distro configuration only: tolomeo.inc assigns DISTRO_FEATURES with =, so a machine configuration
cannot add to it.
tlm-update-encrypted is independent of tlm-update-ota, tlm-update-ota-streaming, and tlm-update-offline. Any
combination is valid.
Configure the Key Variables¶
Three variables control where the AES key is read from at build time. Set them in your kas configuration file or
local.conf, or pass them as environment variables before calling kas.
| Variable | Default | Description |
|---|---|---|
SWUPDATE_KEYDIR |
${BSPDIR}/keys |
Directory containing all key material (signing and encryption) |
SWUPDATE_ENC_KEYNAME |
swupdate-enc |
Base name of the AES key file, without path or extension |
SWUPDATE_AES_FILE |
${SWUPDATE_KEYDIR}/${SWUPDATE_ENC_KEYNAME} |
Full path to the AES key file — empty unless tlm-update-encrypted is active; derived by default |
With the defaults, the build reads the AES key from keys/swupdate-enc relative to the BSP root (${BSPDIR}).
To use a different key name, pass it via environment before building:
Or set it in local.conf:
Build the Package¶
The imgen-update-full-enc recipe skips itself unless the distribution enables tlm-update-encrypted. Build it from a kas
target file whose distro does. The recipe inherits the encryption configuration from swupdate_config, so the target
file needs no encryption variables.
# kas/tolomeo-qemux86-64_imgen-update-full-enc-<your-distro>.yml
---
header:
version: 14
includes:
- kas/common.yml
machine: tolomeo-qemux86-64
distro: <your-distro>
target: imgen-update-full-enc
BUILD_VERSION sets the version string embedded in the sw-description. The buildinfo block of
meta-tolomeo-qemu/kas/common.yml assigns it, so an environment variable has no effect. Replace the block in the target
file:
local_conf_header:
buildinfo: |-
FIRMWARE_NAME = "TVD-embedded-firmware"
BUILD_VERSION = "1.0.0"
SECURITY_PATCH_LEVEL = "26.09"
Then run the build:
SWUPDATE_SIGN_KEYNAME defaults to swupdate-sign and must match the signing key used when building the image.
After the build completes, the encrypted .swu archive is collected under:
artifacts/tolomeo-qemux86-64/image-prod/<version>/updates/imgen-update-full-enc/
└── imgen-update-full-enc-tolomeo-qemux86-64.rootfs.swu
Note
A device installs the package only when its swupdate.sh or swupdate-usb.sh passes -K <path-to-key> and the key
is on the device. See Encrypted Updates.
Verify the Package¶
Inspect the archive contents:
cpio -tv < artifacts/tolomeo-qemux86-64/image-prod/<version>/updates/imgen-update-full-enc/imgen-update-full-enc-tolomeo-qemux86-64.rootfs.swu
Both sw-description and the rootfs image appear as encrypted entries in the archive. The sw-description.sig RSA
signature file is present alongside them — signing and encryption are both applied.
See also
- Encrypted Updates — design background and key delivery
- Generate a Signed Update Package — signing key setup