| .. _module-pw_software_update-get-started: |
| |
| ------------------------------- |
| pw_software_update: Get started |
| ------------------------------- |
| .. pigweed-module-subpage:: |
| :name: pw_software_update |
| :tagline: Secure software delivery |
| |
| Hello Bundles! |
| -------------- |
| |
| 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. |
| |
| 1. First let's make a working directory under your Pigweed dir. The |
| ``pw update`` command is not yet visible outside the Pigweed |
| directory. |
| |
| .. code-block:: bash |
| |
| $ cd ~/pigweed |
| $ source activate.sh |
| |
| $ mkdir hello_bundles |
| $ cd hello_bundles |
| |
| |
| 2. 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 <https://cloud.google.com/security-key-management>`_) |
| to generate, control access to, and log usage of software signing keys. |
| |
| .. code-block:: bash |
| |
| $ 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 |
| |
| 3. Now that we have the keys, let's find them an owner by creating the root |
| metadata. |
| |
| .. code-block:: bash |
| |
| # 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 |
| |
| 4. Now we are ready to create a bundle. |
| |
| .. code-block:: bash |
| |
| # 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 |
| |
| 5. 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. |
| |
| .. code-block:: bash |
| |
| $ 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 :ref:`module-pw_software_update-design`. |