pw_software_update: Get started#

Pigweed AI summary: This text is a tutorial on how to create, sign, inspect, and verify a software bundle using the "pw update" command in Pigweed. A bundle is a single software release instance that includes all target files of the software build and metadata needed to match, verify, and install the build on a target device. The tutorial covers creating signing keys, creating root metadata, creating an empty bundle, adding root metadata and files to the bundle, signing the bundle, and verifying its integrity. The tutorial

Hello Bundles!#

Pigweed AI summary: This section explains how to create, sign, inspect, and verify a software release instance called a bundle using the "pw update" command. It includes steps to create signing keys, assign them to roles, create root metadata, add files to the bundle, sign the bundle, and verify its integrity. The section also emphasizes the importance of using a proper key management service in production. Finally, it congratulates the reader on creating their first pw_software_update bundle and provides a reference for further learning.

A bundle represents a single software release instance – including all target files of the software build and metadata needed to match, verify and install the build on a target device.

The following illustrates how a bundle is created, signed, inspected, and verified using pw update ... commands.

First let’s make a working directory under your Pigweed dir. The pw update command is not yet visible outside the Pigweed directory.

$ cd ~/pigweed
$ source activate.sh

$ mkdir hello_bundles
$ cd hello_bundles

Create signing keys for “root” and “targets” roles.

Note

Here keys are generated locally for demonstration purposes only. In production, you must use a proper key management service (such as Google Cloud KMS) to generate, control access to, and log usage of software signing keys.

$ mkdir keys
$ pw update generate-key keys/root_key
$ pw update generate-key keys/targets_key
$ tree
.
└── keys
    ├── root_key
    ├── root_key.pub
    ├── targets_key
    └── targets_key.pub

Now that we have the keys, let’s find them an owner by creating the root metadata.

# Assign a single key to each "root" and "targets" roles.
$ pw update create-root-metadata --append-root-key keys/root_key.pub \
   --append-targets-key keys/targets_key.pub -o root_metadata.pb

# Sign the root metadata with the root key to make it official.
$ pw update sign-root-metadata --root-metadata root_metadata.pb \
   --root-key keys/root_key

# Review the generated root metadata (output omitted for brevity).
$ pw update inspect-root-metadata root_metadata.pb

Now we are ready to create a bundle.

# Start with an empty bundle.
$ pw update create-empty-bundle my_bundle.pb

# Add root metadata.
$ pw update add-root-metadata-to-bundle \
   --append-root-metadata root_metadata.pb --bundle my_bundle.pb

# Add some files.
$ mkdir target_files
$ echo "application bytes" > target_files/application.bin
$ echo "rtos bytes" > target_files/rtos.bin
$ pw update add-file-to-bundle --bundle my_bundle.pb --file target_files/application.bin
$ pw update add-file-to-bundle --bundle my_bundle.pb --file target_files/rtos.bin
$ tree
   .
   ├── keys
   │   ├── root_key
   │   ├── root_key.pub
   │   ├── targets_key
   │   └── targets_key.pub
   ├── my_bundle.pb
   ├── root_metadata.pb
   └── target_files
       ├── application.bin
       └── rtos.bin

# Sign our bundle with the "targets" key.
$ pw update sign-bundle --bundle my_bundle.pb --key keys/targets_key

# Review and admire our work (output omitted).
$> pw update inspect-bundle my_bundle.pb

Finally we can verify the integrity of our bundle.

Note

Here we are using python3 -m pw_software_update.verify because the pw verify-bundle command is WIP.

$ python3 -m pw_software_update.verify --incoming my_bundle.pb
   Verifying: my_bundle.pb
   (self-verification)
   Checking content of the trusted root metadata
          Checking role type
          Checking keys database
          Checking root signature requirement
          Checking targets signature requirement
          Checking for key sharing
   Verifying incoming root metadata
          Checking signatures against current root
          Total=1, threshold=1
          Verified: 1
          Checking content
          Checking role type
          Checking keys database
          Checking root signature requirement
          Checking targets signature requirement
          Checking for key sharing
          Checking signatures against current root
          Total=1, threshold=1
          Verified: 1
          Checking for version rollback
          Targets key rotation: False
   Upgrading trust to the incoming root metadata
   Verifying targets metadata
          Checking signatures: total=1, threshold=1
          Verified signatures: 1
          Checking content
          Checking role type
   Checking targets metadata for version rollback
   Verifying target file: "application"
   Verifying target file: "rtos"
   Verification passed.

🎉🎉 Congratulations on creating your first pw_software_update bundle! 🎉🎉

To learn more, see pw_software_update: Design.

pw_software_update#

Secure software delivery

pw_software_update: Get started#

Hello Bundles!#