Skip to content

Understanding Encrypted Artifacts

Design rationale and feature boundary for AES-encrypted .swu packages in meta-tolomeo.

For step-by-step instructions, see Build Encrypted SWUpdate Artifacts. For a complete variable reference, see Update Mechanism Reference.

Table of Contents

What update-encrypted Provides

The update-encrypted DISTRO_FEATURE compiles AES decryption support into the swupdate binary. Specifically it enables:

Kconfig option Effect
CONFIG_ENCRYPTED_IMAGES=y AES decryption of payload images at install time
CONFIG_ENCRYPTED_SW_DESCRIPTION=y AES decryption of the sw-description manifest
CONFIG_ENCRYPTED_IMAGES_HARDEN_LOGGING=y Suppresses key material from error log output

The feature does not:

  • provision the AES key on the device
  • change how updates are triggered or how the update service is managed
  • require update-ota, update-local, or update-ota-streaming — it is independent of all other update features

update-encrypted is already included in DISTRO_FEATURES for both tolomeo-prod and tolomeo-devel. Custom distributions inheriting from meta-tolomeo must add it explicitly.

Signing and Encryption: Complementary Concerns

Signing and encryption solve different threat models. Both are active in meta-tolomeo when update-encrypted is combined with the existing RSA signing infrastructure.

Signing provides authenticity. A signed artifact proves it was produced by a trusted source and was not modified in transit. An attacker who intercepts the package cannot forge a new one without the private signing key. The payload content is visible to anyone who obtains the artifact.

Encryption provides confidentiality. An encrypted artifact cannot be read by a party that obtains it without the AES key. It does not prove origin on its own — an attacker could encrypt a valid-looking artifact if they have the AES key.

An encrypted-but-unsigned artifact is confidential but not authenticated. A signed-but-unencrypted artifact is authenticated but not confidential. Using both together closes both gaps.

In practice, the imgen-update-full-enc recipe sets both SWUPDATE_IMAGES_ENCRYPTED and SWUPDATE_ENCRYPT_SWDESC = "1", so both the payload images and the sw-description manifest are encrypted before signing.

The Feature Boundary

meta-tolomeo provides:

  • The compiled swupdate binary with AES decryption support
  • Build-time variables for driving encryption in imgen recipes (SWUPDATE_AES_FILE, SWUPDATE_ENC_KEYNAME)
  • A reference imgen recipe (imgen-update-full-enc) for QEMU targets that encrypts the rootfs image and the manifest

The BSP layer is responsible for:

  1. Deciding how the AES key reaches the device. meta-tolomeo does not prescribe a key delivery mechanism. The design space is described in the next section.

  2. Provisioning the key at the expected path before swupdate runs. Whether the key arrives as a static file baked into the image, a tmpfs mount populated at boot, or a symlink to a TEE-exported key is a BSP decision.

  3. Passing -K <path-to-key> to the swupdate binary. The binary has decryption support compiled in, but it does not attempt decryption unless the -K flag is present at invocation. The BSP must override swupdate.sh (OTA) or swupdate-usb.sh (USB) in a bbappend to add this flag. Without it, applying an encrypted package will fail even if the binary has CONFIG_ENCRYPTED_IMAGES=y.

On-Device Key Delivery Design Space

Four approaches in increasing order of operational complexity and security strength. The right choice depends on threat model, hardware, and operational infrastructure.

Development path

The AES key is written to a fixed path in the root filesystem by a recipe bbappend at image build time. No runtime key retrieval is needed.

When it fits: QEMU-based development, CI validation, environments where artifact confidentiality is not a production requirement.

Why it is unsuitable for production: Anyone with a copy of the image has the AES key. The key cannot be rotated independently of the image.

Secure storage / trusted execution environment

The key is stored in a TEE-protected area — for example OP-TEE secure storage or eMMC RPMB — and retrieved at runtime by a trusted application that exports it to a volatile tmpfs path before swupdate runs.

When it fits: Platforms with a functional TEE that want hardware-isolated key storage without a dedicated security chip.

Requirements: TEE support in the BSP, a trusted application managing the key lifecycle, and a systemd unit that exports the key before the swupdate service starts.

TPM-sealed key

The key is sealed to the TPM at provisioning time using a policy tied to the measured platform state (PCR values). At boot, a systemd service unseals the key into a volatile in-memory path. The key is only accessible when the platform is in a known-good measured state.

When it fits: Platforms with a TPM2 chip and a measured boot chain. Provides attestation binding — the key is inaccessible if firmware or OS is modified.

Requirements: TPM2 chip, tpm2-tools on the device, a measured boot chain with stable PCR values, and a key-unseal service that runs before swupdate.

Provisioning service

The key is delivered to the device during factory provisioning or first-boot onboarding over a mutually authenticated channel (e.g. TLS with a device certificate issued during manufacturing). The key never appears in any build artifact — each device receives a unique key at enrollment.

When it fits: Production fleets where devices are provisioned by a manufacturing or onboarding service and per-device key uniqueness is required.

Requirements: A provisioning backend, device identity certificates, and a first-boot agent that contacts the service and writes the key to protected storage. The highest operational complexity, but the strongest separation between build-time and runtime material.