Generate a Signed Update Package¶

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¶

Derived Key Paths¶

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

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"

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¶

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>