Skip to content

SWUpdate Package Generation

Setting up cryptographic keys and building signed SWUpdate (.swu) packages for secure over-the-air updates.

Table of Contents

Overview

SWUpdate packages are signed compound archives containing:

  • sw-description: Update manifest with file hashes and installation instructions
  • sw-description.sig: Cryptographic signature of the manifest
  • Update images: Root filesystem, kernel, or other system components

The signing process ensures only authorized updates from verified sources can be installed.

Note: The build examples shown use QEMU targets for internal validation of OTA workflows. For production hardware, adapt the kas configuration files accordingly.

Key Management

Generating Cryptographic Keys

Generate a public/private key pair for signing and verification.

Create Keys Directory

mkdir -p keys
cd keys

Generate RSA Keys

# Generate password file and RSA private key with AES-256 encryption
echo "your-secure-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

Set Proper Permissions

# Protect private key and password file
chmod 600 swupdate-sign swupdate-sign.pass

# Public key can be world-readable
chmod 644 swupdate-sign.pub

Security Best Practices

  • Understand the key update procedure
  • Be aware that updating the public/private keys requires a specific update procedure
  • Public keys must be present on the target system to validate the origin of update artifacts
  • Update artifacts are signed with the private key, which is stored securely and used only during the build process

  • Plan key rotation carefully to avoid breaking existing update validation

  • Never commit production keys to version control

  • Add keys/swupdate-sign and keys/swupdate-sign.pass to .gitignore

  • Keep private keys and passphrases out of any shared repositories

  • Use strong passphrases

  • Minimum 12 characters
  • Mix uppercase, lowercase, numbers, and symbols

  • Avoid dictionary words

  • Regularly rotate keys

  • Follow your organization's security policy
  • Typically every 1-2 years for production systems

  • Coordinate key rotation with the required update procedure to ensure continuity

  • Backup keys securely

  • Store encrypted backups offline
  • Use multiple secure locations
  • Document key recovery procedures
  • Include both public and private keys in your backup strategy

SWUpdate Configuration

Configuration Variables

common-swupdate: |-
    # --- SWUpdate Configuration ---
    # Security: Cryptographic key configuration

    # Directory containing all key material (signing and encryption)
    SWUPDATE_KEYDIR ?= "${BSPDIR}/keys"

    # Base name shared by all key files, without file extension
    SWUPDATE_SIGN_KEYNAME ?= "swupdate-sign"

Variable Descriptions

Variable Description Example
SWUPDATE_KEYDIR Directory containing all key material (signing and encryption) keys
SWUPDATE_SIGN_KEYNAME Base name for key files (without extension) swupdate-sign

Derived Key Paths

The following key files are automatically derived from the base configuration:

Key File Derived Path Purpose
Private key ${SWUPDATE_KEYDIR}/${SWUPDATE_SIGN_KEYNAME} RSA private key for signing
Public key ${SWUPDATE_KEYDIR}/${SWUPDATE_SIGN_KEYNAME}.pub RSA public key for verification
Password file ${SWUPDATE_KEYDIR}/${SWUPDATE_SIGN_KEYNAME}.pass Passphrase for encrypted key

For example, with defaults (SWUPDATE_KEYDIR=keys and SWUPDATE_SIGN_KEYNAME=swupdate-sign):

  • Private key: keys/swupdate-sign
  • Public key: keys/swupdate-sign.pub
  • Password file: keys/swupdate-sign.pass

Building Update Packages

Update Package Types

Full Update Package

Complete system update with full images for major updates or recovery.

Validation target: kas/tolomeo-qemux86-64_imgen-update-full.yml

Delta Update Package

Optimized update using rdiff binary diffs for regular OTA updates.

Validation target: kas/tolomeo-qemux86-64_imgen-update-delta.yml

Encrypted Full Update Package

Full system update with AES-encrypted payload and manifest for artifact confidentiality.

Validation target: kas/tolomeo-qemux86-64_imgen-update-full-enc.yml

See Build Encrypted SWUpdate Artifacts for key generation, configuration, and build instructions.

Build Process

Set Up Environment Variables

# Optional: Override default key directory and name
export SWUPDATE_KEYDIR="$(pwd)/keys"
export SWUPDATE_SIGN_KEYNAME="swupdate-sign"

Note: These variables are defined in common.yml with default values. Only export them manually to override defaults. The actual key file paths are automatically derived from these base variables.

Build the Package

Full update package:

FIRMWARE_NAME=TVD BUILD_VERSION=0.2.0 kas build kas/tolomeo-qemux86-64_imgen-update-full.yml

Delta update package:

VERSION_FROM=0.1.0 VERSION_TO=0.2.0 kas build kas/tolomeo-qemux86-64_imgen-update-delta.yml

Build Variables

Variable Description Default Example
FIRMWARE_NAME Firmware identifier - TVD
BUILD_VERSION Target version for full update - 0.2.0
VERSION_FROM Source version for delta update - 0.1.0
VERSION_TO Target version for delta update - 0.2.0

Note: FIRMWARE_NAME and BUILD_VERSION can be overridden to match your project needs.

Artifact Structure

After building, artifacts are organized by machine, image, and version:

artifacts/tolomeo-qemux86-64/image-prod/
└── 0.2.0/
    ├── build-info.txt
    ├── image-prod-tolomeo-qemux86-64.rootfs.ext4
    ├── image-prod-tolomeo-qemux86-64.rootfs.ext4.gz
    ├── u-boot.bin
    └── updates/
        ├── from_0.1.0/
        │   ├── delta-info.json
        │   ├── delta-update-0.1.0-to-0.2.0.swu
        │   ├── rootfs.delta
        │   ├── rootfs.delta.gz
        │   └── rootfs.signature
        └── imgen-update-valid/
            ├── build-info.txt
            └── imgen-update-valid-tolomeo-qemux86-64.rootfs.swu

Key Artifacts

  • delta-update-X.X.X-to-Y.Y.Y.swu: Delta update package (incremental)
  • imgen-update-valid-*.rootfs.swu: Full update package (complete)
  • delta-info.json: Metadata about the delta update
  • rootfs.delta: rdiff binary patch file

Testing and Verification

Verify Package Contents

cpio -tv < artifacts/tolomeo-qemux86-64/image-prod/0.2.0/updates/imgen-update-valid/imgen-update-valid-tolomeo-qemux86-64.rootfs.swu

Extract for inspection:

mkdir swu-contents
cd swu-contents
cpio -idv < ../artifacts/tolomeo-qemux86-64/image-prod/0.2.0/updates/imgen-update-valid/imgen-update-valid-tolomeo-qemux86-64.rootfs.swu

Verify Signature

openssl dgst -sha256 \
    -verify keys/swupdate-sign.pub \
    -signature sw-description.sig \
    sw-description

Expected output: Verified OK

Apply on Device

Dry run:

swupdate -k /etc/swupdate/certs/public.pem -i package.swu -e <software>,<mode> -H <board:rev> -n

Actual update:

swupdate -k /etc/swupdate/certs/public.pem -i package.swu -e <software>,<mode> -H <board:rev>