| .. _module-pw_software_update: |
| |
| ------------------- |
| pw_software_update |
| ------------------- |
| |
| This module provides the following building blocks of a high assurance software |
| update system: |
| |
| 1. A `TUF <https://theupdateframework.io>`_-based security framework. |
| 2. A `protocol buffer <https://developers.google.com/protocol-buffers>`_ based |
| software update "bundle" format. |
| 3. An update bundle decoder and verification stack. |
| 4. An extensible software update RPC service. |
| |
| High assurance software update |
| ============================== |
| |
| On a high-level, a high-assurance software update system should make users feel |
| safe to use and be technologically worthy of user's trust over time. In |
| particular it should demonstrate the following security and privacy properties. |
| |
| 1. The update packages are generic, sufficiently qualified, and officially |
| signed with strong insider attack guardrails. |
| 2. The update packages are delivered over secure channels. |
| 3. Update checking, changelist, and installation are done with strong user |
| authorization and awareness. |
| 4. Incoming update packages are strongly authenticated by the client. |
| 5. Software update requires and builds on top of verified boot. |
| |
| Life of a software update |
| ========================= |
| |
| The following describes a typical software update sequence of events. The focus |
| is not to prescribe implementation details but to raise awareness in subtle |
| security and privacy considerations. |
| |
| Stage 0: Product makers create and publish updates |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| A (system) software update is essentially a new version of the on-device |
| software stack. Product makers create, qualify and publish new software updates |
| to deliver new experiences or bug fixes to users. |
| |
| While not visible to end users, the product maker team is expected to follow |
| widely agreed security and release engineering best practices before signing and |
| publishing a new software update. A new software update should be generic for |
| all devices, rather than targeting specific devices. |
| |
| Stage 1: Users check for updates |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| For most consumer products, software updates are "opt-in", which means users |
| either manually check for new updates or opt-in for the device itself to check |
| (and/or install) updates automatically on the user's behalf. The opt-in may be |
| blanket or conditioned on the nature of the updates. |
| |
| If users have authorized automatic updates, update checking also happens on a |
| regular schedule and at every reboot. |
| |
| .. important:: |
| As a critical security recovery mechanism, checking and installing software |
| updates ideally should happen early in boot, where the software stack has |
| been freshly verified by verified boot and minimum mutable input is taken |
| into account in update checking and installation. |
| |
| In other words, the longer the system has been running (up), the greater |
| the chance that system has been taken control by an attacker. So it is |
| a good idea to remind users to reboot when the system has been running for |
| "too long". |
| |
| Stage 2: Users install updates |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| Once a new update has been determined to be available for the device, users will |
| be prompted to authorize downloading and installing the update. Users can also |
| opt-in to automatic downloading and installing. |
| |
| .. important:: |
| If feasible, rechecking, downloading and installing an update should be |
| carried out early in a reboot -- to recover from potential temporary attacker |
| control. |
| |
| To improve reliability and reduce disruption, modern system updates typically |
| employ an A/B update mechanism, where the incoming update is installed into |
| a backup boot slot, and only enacted and locked down (anti-rollback) after |
| the new slot has passed boot verification and fully booted into a good state. |
| |
| .. important:: |
| While a system update is usually carried out by a user space update client, |
| an incoming update may contain more than just the user space. It could |
| contain firmware for the bootloader, trusted execution environment, DSP, |
| sensor cores etc. which could be important components of a device's TCB ( |
| trusted compute base, where critical device security policies are enforced). |
| When updating these components across different domains, it is best to let |
| each component carry out the actual updating, some of which may require |
| stronger user authorization (e.g. a test of physical presence, explicit |
| authorization with an admin passcode etc.) |
| |
| Lastly, updates should be checked again in case there are newer updates |
| available. |
| |
| |
| Command-line Interface |
| ====================== |
| |
| You can access the software update CLI by running ``pw update`` in the pigweed environment. |
| |
| |
| .. code-block:: bash |
| |
| ~$ cd pigweed |
| ~/pigweed$ source ./activate.sh |
| ~/pigweed$ pw update |
| |
| usage: pw update [-h] <command> |
| |
| Software update related operations. |
| |
| positional arguments: |
| 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 |
| verify-bundle |
| |
| optional arguments: |
| -h, --help show this help message and exit |
| |
| Learn more at: pigweed.dev/pw_software_update |
| |
| |
| generate-key |
| ^^^^^^^^^^^^ |
| |
| The ``generate-key`` subcommmand generates an ECDSA SHA-256 public + private keypair. |
| |
| .. code-block:: bash |
| |
| $ pw update generate-key -h |
| |
| usage: pw update generate-key [-h] pathname |
| |
| Generates an ecdsa-sha2-nistp256 signing key pair (private + public) |
| |
| positional arguments: |
| pathname Path to generated key pair |
| |
| optional arguments: |
| -h, --help show this help message and exit |
| |
| |
| +------------+------------+----------------+ |
| | positional argument | |
| +============+============+================+ |
| |``pathname``|path to the generated keypair| |
| +------------+------------+----------------+ |
| |
| create-root-metadata |
| ^^^^^^^^^^^^^^^^^^^^ |
| |
| The ``create-root-metadata`` subcommand creates a root metadata. |
| |
| .. code-block:: bash |
| |
| $ pw update create-root-metadata -h |
| |
| usage: pw update create-root-metadata [-h] [--version VERSION] --append-root-key ROOT_KEY |
| --append-targets-key TARGETS_KEY -o/--out OUT |
| |
| Creation of root metadata |
| |
| optional arguments: |
| -h, --help show this help message and exit |
| --version VERSION Canonical version number for rollback checks; |
| Defaults to 1 |
| |
| required arguments: |
| --append-root-key ROOT_KEY Path to root key |
| --append-targets-key TARGETS_KEY Path to targets key |
| -o OUT, --out OUT Path to output file |
| |
| |
| |
| +--------------------------+-------------------------------------------+ |
| | required arguments | |
| +==========================+===========================================+ |
| |``--append-root-key`` | path to desired root key | |
| +--------------------------+-------------------------------------------+ |
| |``--append-targets-key`` | path to desired target key | |
| +--------------------------+-------------------------------------------+ |
| |``--out`` | output path of newly created root metadata| |
| +--------------------------+-------------------------------------------+ |
| |
| |
| +-------------+------------+------------------------------+ |
| | optional argument | |
| +=============+============+==============================+ |
| |``--version``| Rollback version number(default set to 1) | |
| +-------------+------------+------------------------------+ |
| |
| sign-root-metadata |
| ^^^^^^^^^^^^^^^^^^ |
| |
| The ``sign-root-metadata`` subcommand signs a given root metadata. |
| |
| .. code-block:: bash |
| |
| usage: pw update sign-root-metadata [-h] --root-metadata ROOT_METADATA --root-key ROOT_KEY |
| |
| Signing of root metadata |
| |
| optional arguments: |
| -h, --help show this help message and exit |
| |
| required arguments: |
| --root-metadata ROOT_METADATA Root metadata to be signed |
| --root-key ROOT_KEY Root signing key |
| |
| |
| |
| +--------------------------+-------------------------------------------+ |
| | required arguments | |
| +==========================+===========================================+ |
| |``--root-metadata`` | Path of root metadata to be signed | |
| +--------------------------+-------------------------------------------+ |
| |``--root-key`` | Path to root signing key | |
| +--------------------------+-------------------------------------------+ |
| |
| inspect-root-metadata |
| ^^^^^^^^^^^^^^^^^^^^^ |
| |
| The ``inspect-root-metadata`` subcommand prints the contents of a given root metadata. |
| |
| .. code-block:: bash |
| |
| $ pw update inspect-root-metadata -h |
| |
| usage: pw update inspect-root-metadata [-h] pathname |
| |
| Outputs contents of root metadata |
| |
| positional arguments: |
| pathname Path to root metadata |
| |
| optional arguments: |
| -h, --help show this help message and exit |
| |
| |
| +--------------------------+-------------------------------------------+ |
| | positional argument | |
| +==========================+===========================================+ |
| |``pathname`` | Path to root metadata | |
| +--------------------------+-------------------------------------------+ |
| |
| |
| create-empty-bundle |
| ^^^^^^^^^^^^^^^^^^^ |
| |
| The ``create-empty-bundle`` subcommand creates an empty update bundle. |
| |
| .. code-block:: bash |
| |
| $ pw update create-empty-bundle -h |
| |
| usage: pw update create-empty-bundle [-h] [--target-metadata-version VERSION] pathname |
| |
| Creation of an empty bundle |
| |
| positional arguments: |
| pathname Path to newly created empty bundle |
| |
| optional arguments: |
| -h, --help show this help message and exit |
| --target-metadata-version VERSION Version number for targets metadata; |
| Defaults to 1 |
| |
| +--------------------------+-------------------------------------------+ |
| | positional argument | |
| +==========================+===========================================+ |
| |``pathname`` | Path to newly created empty bundle | |
| +--------------------------+-------------------------------------------+ |
| |
| +------------------------------+--------------------------------------+ |
| | optional arguments | |
| +==============================+======================================+ |
| |``--target-metadata-version`` | Version number for targets metadata; | |
| | | Defaults to 1 | |
| +------------------------------+--------------------------------------+ |
| |
| add-root-metadata-to-bundle |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| The ``add-root-metadata-to-bundle`` subcommand adds a root metadata to a bundle. |
| |
| .. code-block:: bash |
| |
| $ pw update add-root-metadata-to-bundle -h |
| |
| usage: pw update add-root-metadata-to-bundle [-h] --append-root-metadata ROOT_METADATA |
| --bundle BUNDLE |
| |
| Add root metadata to a bundle |
| |
| optional arguments: |
| -h, --help show this help message and exit |
| |
| required arguments: |
| --append-root-metadata ROOT_METADATA Path to root metadata |
| --bundle BUNDLE Path to bundle |
| |
| +--------------------------+-------------------------------------------+ |
| | required arguments | |
| +==========================+===========================================+ |
| |``--append-root-metadata``| Path to root metadata | |
| +--------------------------+-------------------------------------------+ |
| |``--bundle`` | Path to bundle | |
| +--------------------------+-------------------------------------------+ |
| |
| |
| add-file-to-bundle |
| ^^^^^^^^^^^^^^^^^^ |
| |
| The ``add-file-to-bundle`` subcommand adds a target file to an existing bundle. |
| |
| .. code-block:: bash |
| |
| $ pw update add-file-to-bundle -h |
| |
| usage: pw update add-file-to-bundle [-h] [--new-name NEW_NAME] --bundle BUNDLE |
| --file FILE_PATH |
| |
| Add a file to an existing bundle |
| |
| optional arguments: |
| -h, --help show this help message and exit |
| --new-name NEW_NAME Optional new name for target |
| |
| required arguments: |
| --bundle BUNDLE Path to an existing bundle |
| --file FILE_PATH Path to a target file |
| |
| +--------------------------+-------------------------------------------+ |
| | required arguments | |
| +==========================+===========================================+ |
| |``--file`` | Path to a target file | |
| +--------------------------+-------------------------------------------+ |
| |``--bundle`` | Path to bundle | |
| +--------------------------+-------------------------------------------+ |
| |
| +--------------------------+-------------------------------------------+ |
| | optional argument | |
| +==========================+===========================================+ |
| |``--new-name`` | Optional new name for target | |
| +--------------------------+-------------------------------------------+ |
| |
| sign-bundle |
| ^^^^^^^^^^^ |
| |
| The ``sign-bundle`` subcommand signs an existing bundle with a dev key. |
| |
| .. code-block:: bash |
| |
| $ pw update sign-bundle -h |
| |
| usage: pw update sign-bundle [-h] --bundle BUNDLE --key KEY |
| |
| Sign an existing bundle using a development key |
| |
| optional arguments: |
| -h, --help show this help message and exit |
| |
| required arguments: |
| --bundle BUNDLE Bundle to be signed |
| --key KEY Bundle signing key |
| |
| +--------------------------+-------------------------------------------+ |
| | required arguments | |
| +==========================+===========================================+ |
| |``--key`` | Key to sign bundle | |
| +--------------------------+-------------------------------------------+ |
| |``--bundle`` | Path to bundle | |
| +--------------------------+-------------------------------------------+ |
| |
| inspect-bundle |
| ^^^^^^^^^^^^^^ |
| |
| The ``inspect-bundle`` subcommand prints the contents of a given bundle. |
| |
| .. code-block:: bash |
| |
| $ pw update inspect-bundle -h |
| |
| usage: pw update inspect-bundle [-h] pathname |
| |
| Outputs contents of bundle |
| |
| positional arguments: |
| pathname Path to bundle |
| |
| optional arguments: |
| -h, --help show this help message and exit |
| |
| |
| +------------+------------+----------------+ |
| | positional argument | |
| +============+============+================+ |
| |``pathname``|Path to bundle | |
| +------------+------------+----------------+ |
| |
| verify-bundle |
| ^^^^^^^^^^^^^ |
| |
| The ``verify-bundle`` subcommand performs verification of an existing bundle. |
| |
| .. code-block:: bash |
| |
| $ pw update verify-bundle -h |
| |
| usage: pw update verify-bundle [-h] --bundle BUNDLE |
| --trusted-root-metadata ROOT_METADATA |
| |
| Verify a bundle |
| |
| optional arguments: |
| -h, --help show this help message and exit |
| |
| required arguments: |
| --bundle BUNDLE Bundle to be verified |
| --trusted-root-metadata ROOT_METADATA Trusted root metadata |
| |
| +---------------------------+-------------------------------------------+ |
| | required arguments | |
| +===========================+===========================================+ |
| |``--trusted-root-metadata``| Trusted root metadata(anchor) | |
| +---------------------------+-------------------------------------------+ |
| |``--bundle`` | Path of bundle to be verified | |
| +---------------------------+-------------------------------------------+ |
| |
| Getting started with bundles (coming soon) |
| ========================================== |
