Skip to content

Generate an Encrypted Artifact

This guide covers generating AES-encrypted .swu packages for ToloMEO QEMU targets.

Prerequisites

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

key=<64 hexadecimal digits, the AES-256 key>
iv=<32 hexadecimal digits, the 128-bit IV>

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

echo "keys/swupdate-enc" >> .gitignore

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.

# meta-<your-bsp>/conf/distro/<your-distro>.conf
DISTRO_FEATURES += "tlm-update-encrypted"

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:

export SWUPDATE_ENC_KEYNAME="my-project-aes"

Or set it in local.conf:

SWUPDATE_ENC_KEYNAME = "my-project-aes"

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:

kas build kas/tolomeo-qemux86-64_imgen-update-full-enc-<your-distro>.yml

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