Skip to content

Build Encrypted SWUpdate Artifacts

Generating AES-encrypted .swu packages for ToloMEO QEMU targets.

For design background and on-device key delivery strategies, see Understanding Encrypted Artifacts. For signing key setup, see SWUpdate Package Generation.

Table of Contents

Prerequisites

  • Signing keys already generated and configured — see SWUpdate Package Generation
  • openssl available in the build environment (present in the devcontainer by default)

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-character hexadecimal AES-256 key>
iv=<32-character hexadecimal 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

The resulting file looks like:

key=4FADBC80F38D614208782D5F5FF7E73585D233E254669163F2AEA66ED5406D6E
iv=836A91DC99FDC6751252716E2D47A306

Protect the key

# Add to .gitignore — never commit a production AES key to version control
echo "keys/swupdate-enc" >> .gitignore

Note: The repository contains a development-only key at devel-keys/swupdate-enc for build validation. It must never be used in production environments — anyone with the file can decrypt all packages built with it.

Security best practices

  • Never commit production AES keys to version control. Anyone with the key can decrypt update packages.
  • Use a hardware security module or secrets manager for production. See Understanding Encrypted Artifacts for the full design space.
  • Plan key rotation. All target devices must receive the new key before it is used to build new packages. Key delivery requires a separate secure channel — it cannot be done via a .swu package that is itself encrypted with the old key.

Enable update-encrypted

update-encrypted is already included in DISTRO_FEATURES for tolomeo-prod and tolomeo-devel. If you are building a custom distribution that inherits from meta-tolomeo, add it to your distro or machine configuration:

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

update-encrypted is independent of update-ota, update-ota-streaming, and update-local. Any combination is valid.

Configure 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 — derived, cannot be set directly

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"

Create the kas Configuration

Create a kas file for the encrypted recipe. The recipe (imgen-update-full-enc_git.bb) inherits encryption configuration from swupdate_config — no additional variables are needed in the kas file beyond the target name.

# kas/tolomeo-qemux86-64_imgen-update-full-enc.yml
---
header:
  version: 14

  includes:
    - kas/common.yml

machine: tolomeo-qemux86-64
distro: tolomeo-prod
target: imgen-update-full-enc

Build the Package

Set the required environment variables and run the build:

export SWUPDATE_SIGN_KEYNAME="swupdate-sign"
export BUILD_VERSION="1.0.0"
kas build kas/tolomeo-qemux86-64_imgen-update-full-enc.yml

Note: SWUPDATE_SIGN_KEYNAME must match the signing key base name used when building the image. BUILD_VERSION sets the version string embedded in the sw-description. Both can be overridden in local.conf or via environment.

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

Verify the package

Inspect the archive contents:

cpio -tv < artifacts/tolomeo-qemux86-64/image-prod/${BUILD_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.