Design#

pw_software_update: Secure software delivery

This page explains the security framing, bundle format and update workflows of pw_software_update.

Embedded TUF#

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.

The pw_software_update module implements the following building blocks around TUF.

Update bundles#

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”.

Key structure#

As an optimization and trade-off for embedded projects, pw_software_update only supports the “root” and “targets” roles, as represented by root_metadata and targets_metadata.

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.

Signing service#

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.

Bundle verification#

The 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.

Update workflow#

On the device side, BundledUpdateService orchestrates an update session end-to-end. It drives the backend via a BundledUpdateBackend interface.

BundledUpdateService is invoked via pw_rpc after an incoming bundle is staged via pw_transfer.

Tooling#

pw_software_update provides the following tooling support for development and integration.

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#

The pw update ... CLI (Command Line Interface) is a user-friendly interface to the pw_software_update python package.

You can use the CLI to quickly learn and prototype a software update system based on 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 target.

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 CLI reference.