Secure software delivery
This page explains the security framing, bundle format and update workflows of
At the heart, the
pw_software_update module leverages
The Update Framework (TUF),
an industry-leading software update security framework that is open, flexible,
and offers a balanced security and privacy treatment.
pw_software_update module implements the following building blocks
Update bundles represent software releases packaged ready for delivery. A bundle is essentially an archived folder matching the following structure:
/ ├── root_metadata ├── targets_metadata └── targets ├── release_notes.txt ├── manifest.txt ├── rtos.bin └── app.bin
Bundles are encoded as serialized “protocol buffers”.
As an optimization and trade-off for embedded projects,
only supports the “root” and “targets” roles, as represented by
The “root” role delegates the “targets” role to directly authorize each release.
The “root” role can regularly rotate the “targets” role, in effect revoking older versions once a new release is available.
The “root” role is the “root of trust” for software update and tied into
verified boot. Due to security risks,
pw_software_update does not use
persistent metadata caches that are not covered by verified boot.
Production signing keys MUST be kept secure and clean. That means we must carefully control access, log usage details, and revoke the key if it was (accidentally) used to sign a “questionable” build.
This is easier with a signing server built around a key management service.
We don’t yet have a public-facing service. External users should source their own solution.
UpdateBundleAccessor decodes, verifies, and exposes the target
files from an incoming bundle. This class hides the details of the bundle
format and verification flow from callers.
On the device side,
BundledUpdateService orchestrates an update
session end-to-end. It drives the backend via a
BundledUpdateService is invoked via pw_rpc after an
incoming bundle is staged via pw_transfer.
pw_software_update provides the following tooling support for development
The python package#
pw_software_update comes with a python package of the same name, providing
the following functionalities.
Local signing key generation for development.
TUF root metadata generation and signing.
Bundle generation, signing, and verification.
Signing server integration.
A typical use of the package is for build system integration.
Help on package pw_software_update: NAME pw_software_update - pw_software_update PACKAGE CONTENTS bundled_update_pb2 cli dev_sign generate_test_bundle keys metadata remote_sign root_metadata tuf_pb2 update_bundle update_bundle_pb2 verify
The command line utility#
pw update ... CLI (Command Line Interface) is a user-friendly interface
pw_software_update python package.
You can use the CLI to quickly learn and prototype a software update system
pw_software_update on your development PC before productionizing
one. In the future you will be able to use the CLI to update a reference
usage: pw update [sub-commands] sub-commands: generate-key create-root-metadata sign-root-metadata inspect-root-metadata create-empty-bundle add-root-metadata-to-bundle add-file-to-bundle sign-bundle inspect-bundle options: -h, --help show this help message and exit
To learn more, see pw_software_update: CLI reference.