pw_software_update: Guide#

pw_software_update: Secure software delivery

How you update software on an embedded system is specific to the project. However, there are common patterns. This section provides suggestions for each scenario, which you can then adjust to fit your specific needs.

High-level steps#

Setting up an end-to-end software delivery system can seem overwhelming, but generally involves the following high-level steps.

Get familiar with pw_software_update.
Enable local updates for development.
Enable remote updates for internal testing.
Prepare for launching.
Ensure smooth landing.

1. Get familiar with `pw_software_update`.#

pw_software_update is not yet a fully managed service like Google Play Store. To use it effectively, you need to have at least a basic understanding of how it works. The Getting started and Design sections can help you with this.

2. Enable local updates for development.#

This step allows developers to update a device that is connected to their development computer. This achieves a low-latency feedback loop for developers, so they can see the results of their changes quickly.

Component	Task	Description
Build System	Produce update bundles	Use `pw_software_update`’s CLI and Python APIs to generate and check in dev keys, assemble build artifacts into a bundle, and locally sign the bundle.

Dev Tools	Send update bundles	Use `pw_rpc` to connect to the `BundledUpdate` service to start and progress through an update session. Use `pw_transfer` to transfer the bundle’s bytes.

Device software	Implement `BundledUpdateBackend`	Respond to framework callings. Supply root metadata.

3. Enable remote updates for internal testing.#

This step builds upon the previous step and allows developers as well as internal testers to receive software updates over an internal network from an internal release repository. This makes it easy for them to stay up-to-date with the latest software and fixes.

Component	Task	Description
Build System	Upload unsigned bundles	Assemble and generate dev-key signed bundles for local consumption as before. Upload the unsigned bundle to an internal build artifacts repository.

Dev Tools	Support remote update	In addition to local update as before, optionally support updating a device with a build pulled from the build server.

Signing service	Prepare for test-key signing	Set up root and targets test keys and their corresponding ACLs. Monitor incoming signing requests and and automatically sign incoming builds with the test key.

Release system	Produce internal releases	Trigger builds. Run tests. Request test-key remote signing. Publish internal releases.

4. Prepare for launching.#

The goal of this step is not to add new features for users, but to improve security at key points in the development process in preparation for launch.

Component	Task	Description
Build System	Validate and endorse builds	In addition to previous responsibilities, validate builds to make sure the builds are configured and built properly per their build type (e.g. no debug features in user builds), and then endorse the validated builds by signing the builds with the build server’s private key and uploading both the builds and signatures.

Signing service	Prepare for prod-key signing	Set up root and targets production keys and their corresponding ACLs. Monitor incoming signing requests and only sign qualified, user builds with the production key. Verify builder identity and validate build content just before signing.

Release system	Produce well-secured releases	Run builds through daily, internal tests, and production release candidates. Only production-sign a build after all other qualifications have passed.

5. Ensure smooth rollout.#

This step ensures updates are delivered to users reliably and with speed in cases of recoverable security bugs, over the supported lifetime of a product.

Component	Task	Description
Release system	Produce well-secured updates	Carefully control new features. Keep all dependencies up to date. Always ready for emergency updates.