1.. _module-pw_software_update: 2 3------------------- 4pw_software_update 5------------------- 6 7This module provides the following building blocks of a high assurance software 8update system: 9 101. A `TUF <https://theupdateframework.io>`_-based security framework. 112. A `protocol buffer <https://developers.google.com/protocol-buffers>`_ based 12 software update "bundle" format. 133. An update bundle decoder and verification stack. 144. An extensible software update RPC service. 15 16High assurance software update 17============================== 18 19On a high-level, a high-assurance software update system should make users feel 20safe to use and be technologically worthy of user's trust over time. In 21particular it should demonstrate the following security and privacy properties. 22 231. The update packages are generic, sufficiently qualified, and officially 24 signed with strong insider attack guardrails. 252. The update packages are delivered over secure channels. 263. Update checking, changelist, and installation are done with strong user 27 authorization and awareness. 284. Incoming update packages are strongly authenticated by the client. 295. Software update requires and builds on top of verified boot. 30 31Life of a software update 32========================= 33 34The following describes a typical software update sequence of events. The focus 35is not to prescribe implementation details but to raise awareness in subtle 36security and privacy considerations. 37 38Stage 0: Product makers create and publish updates 39^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 40A (system) software update is essentially a new version of the on-device 41software stack. Product makers create, qualify and publish new software updates 42to deliver new experiences or bug fixes to users. 43 44While not visible to end users, the product maker team is expected to follow 45widely agreed security and release engineering best practices before signing and 46publishing a new software update. A new software update should be generic for 47all devices, rather than targeting specific devices. 48 49Stage 1: Users check for updates 50^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 51For most consumer products, software updates are "opt-in", which means users 52either manually check for new updates or opt-in for the device itself to check 53(and/or install) updates automatically on the user's behalf. The opt-in may be 54blanket or conditioned on the nature of the updates. 55 56If users have authorized automatic updates, update checking also happens on a 57regular schedule and at every reboot. 58 59.. important:: 60 As a critical security recovery mechanism, checking and installing software 61 updates ideally should happen early in boot, where the software stack has 62 been freshly verified by verified boot and minimum mutable input is taken 63 into account in update checking and installation. 64 65 In other words, the longer the system has been running (up), the greater 66 the chance that system has been taken control by an attacker. So it is 67 a good idea to remind users to reboot when the system has been running for 68 "too long". 69 70Stage 2: Users install updates 71^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 72 73Once a new update has been determined to be available for the device, users will 74be prompted to authorize downloading and installing the update. Users can also 75opt-in to automatic downloading and installing. 76 77.. important:: 78 If feasible, rechecking, downloading and installing an update should be 79 carried out early in a reboot -- to recover from potential temporary attacker 80 control. 81 82To improve reliability and reduce disruption, modern system updates typically 83employ an A/B update mechanism, where the incoming update is installed into 84a backup boot slot, and only enacted and locked down (anti-rollback) after 85the new slot has passed boot verification and fully booted into a good state. 86 87.. important:: 88 While a system update is usually carried out by a user space update client, 89 an incoming update may contain more than just the user space. It could 90 contain firmware for the bootloader, trusted execution environment, DSP, 91 sensor cores etc. which could be important components of a device's TCB ( 92 trusted compute base, where critical device security policies are enforced). 93 When updating these components across different domains, it is best to let 94 each component carry out the actual updating, some of which may require 95 stronger user authorization (e.g. a test of physical presence, explicit 96 authorization with an admin passcode etc.) 97 98Lastly, updates should be checked again in case there are newer updates 99available. 100 101 102Command-line Interface 103====================== 104 105You can access the software update CLI by running ``pw update`` in the pigweed environment. 106 107 108.. code-block:: bash 109 110 ~$ cd pigweed 111 ~/pigweed$ source ./activate.sh 112 ~/pigweed$ pw update 113 114 usage: pw update [-h] <command> 115 116 Software update related operations. 117 118 positional arguments: 119 generate-key 120 create-root-metadata 121 sign-root-metadata 122 inspect-root-metadata 123 create-empty-bundle 124 add-root-metadata-to-bundle 125 add-file-to-bundle 126 sign-bundle 127 inspect-bundle 128 verify-bundle 129 130 optional arguments: 131 -h, --help show this help message and exit 132 133 Learn more at: pigweed.dev/pw_software_update 134 135 136generate-key 137^^^^^^^^^^^^ 138 139The ``generate-key`` subcommmand generates an ECDSA SHA-256 public + private keypair. 140 141.. code-block:: bash 142 143 $ pw update generate-key -h 144 145 usage: pw update generate-key [-h] pathname 146 147 Generates an ecdsa-sha2-nistp256 signing key pair (private + public) 148 149 positional arguments: 150 pathname Path to generated key pair 151 152 optional arguments: 153 -h, --help show this help message and exit 154 155 156+------------+------------+----------------+ 157| positional argument | 158+============+============+================+ 159|``pathname``|path to the generated keypair| 160+------------+------------+----------------+ 161 162create-root-metadata 163^^^^^^^^^^^^^^^^^^^^ 164 165The ``create-root-metadata`` subcommand creates a root metadata. 166 167.. code-block:: bash 168 169 $ pw update create-root-metadata -h 170 171 usage: pw update create-root-metadata [-h] [--version VERSION] --append-root-key ROOT_KEY 172 --append-targets-key TARGETS_KEY -o/--out OUT 173 174 Creation of root metadata 175 176 optional arguments: 177 -h, --help show this help message and exit 178 --version VERSION Canonical version number for rollback checks; 179 Defaults to 1 180 181 required arguments: 182 --append-root-key ROOT_KEY Path to root key 183 --append-targets-key TARGETS_KEY Path to targets key 184 -o OUT, --out OUT Path to output file 185 186 187 188+--------------------------+-------------------------------------------+ 189| required arguments | 190+==========================+===========================================+ 191|``--append-root-key`` | path to desired root key | 192+--------------------------+-------------------------------------------+ 193|``--append-targets-key`` | path to desired target key | 194+--------------------------+-------------------------------------------+ 195|``--out`` | output path of newly created root metadata| 196+--------------------------+-------------------------------------------+ 197 198 199+-------------+------------+------------------------------+ 200| optional argument | 201+=============+============+==============================+ 202|``--version``| Rollback version number(default set to 1) | 203+-------------+------------+------------------------------+ 204 205sign-root-metadata 206^^^^^^^^^^^^^^^^^^ 207 208The ``sign-root-metadata`` subcommand signs a given root metadata. 209 210.. code-block:: bash 211 212 usage: pw update sign-root-metadata [-h] --root-metadata ROOT_METADATA --root-key ROOT_KEY 213 214 Signing of root metadata 215 216 optional arguments: 217 -h, --help show this help message and exit 218 219 required arguments: 220 --root-metadata ROOT_METADATA Root metadata to be signed 221 --root-key ROOT_KEY Root signing key 222 223 224 225+--------------------------+-------------------------------------------+ 226| required arguments | 227+==========================+===========================================+ 228|``--root-metadata`` | Path of root metadata to be signed | 229+--------------------------+-------------------------------------------+ 230|``--root-key`` | Path to root signing key | 231+--------------------------+-------------------------------------------+ 232 233inspect-root-metadata 234^^^^^^^^^^^^^^^^^^^^^ 235 236The ``inspect-root-metadata`` subcommand prints the contents of a given root metadata. 237 238.. code-block:: bash 239 240 $ pw update inspect-root-metadata -h 241 242 usage: pw update inspect-root-metadata [-h] pathname 243 244 Outputs contents of root metadata 245 246 positional arguments: 247 pathname Path to root metadata 248 249 optional arguments: 250 -h, --help show this help message and exit 251 252 253+--------------------------+-------------------------------------------+ 254| positional argument | 255+==========================+===========================================+ 256|``pathname`` | Path to root metadata | 257+--------------------------+-------------------------------------------+ 258 259 260create-empty-bundle 261^^^^^^^^^^^^^^^^^^^ 262 263The ``create-empty-bundle`` subcommand creates an empty update bundle. 264 265.. code-block:: bash 266 267 $ pw update create-empty-bundle -h 268 269 usage: pw update create-empty-bundle [-h] [--target-metadata-version VERSION] pathname 270 271 Creation of an empty bundle 272 273 positional arguments: 274 pathname Path to newly created empty bundle 275 276 optional arguments: 277 -h, --help show this help message and exit 278 --target-metadata-version VERSION Version number for targets metadata; 279 Defaults to 1 280 281+--------------------------+-------------------------------------------+ 282| positional argument | 283+==========================+===========================================+ 284|``pathname`` | Path to newly created empty bundle | 285+--------------------------+-------------------------------------------+ 286 287+------------------------------+--------------------------------------+ 288| optional arguments | 289+==============================+======================================+ 290|``--target-metadata-version`` | Version number for targets metadata; | 291| | Defaults to 1 | 292+------------------------------+--------------------------------------+ 293 294add-root-metadata-to-bundle 295^^^^^^^^^^^^^^^^^^^^^^^^^^^ 296 297The ``add-root-metadata-to-bundle`` subcommand adds a root metadata to a bundle. 298 299.. code-block:: bash 300 301 $ pw update add-root-metadata-to-bundle -h 302 303 usage: pw update add-root-metadata-to-bundle [-h] --append-root-metadata ROOT_METADATA 304 --bundle BUNDLE 305 306 Add root metadata to a bundle 307 308 optional arguments: 309 -h, --help show this help message and exit 310 311 required arguments: 312 --append-root-metadata ROOT_METADATA Path to root metadata 313 --bundle BUNDLE Path to bundle 314 315+--------------------------+-------------------------------------------+ 316| required arguments | 317+==========================+===========================================+ 318|``--append-root-metadata``| Path to root metadata | 319+--------------------------+-------------------------------------------+ 320|``--bundle`` | Path to bundle | 321+--------------------------+-------------------------------------------+ 322 323 324add-file-to-bundle 325^^^^^^^^^^^^^^^^^^ 326 327The ``add-file-to-bundle`` subcommand adds a target file to an existing bundle. 328 329.. code-block:: bash 330 331 $ pw update add-file-to-bundle -h 332 333 usage: pw update add-file-to-bundle [-h] [--new-name NEW_NAME] --bundle BUNDLE 334 --file FILE_PATH 335 336 Add a file to an existing bundle 337 338 optional arguments: 339 -h, --help show this help message and exit 340 --new-name NEW_NAME Optional new name for target 341 342 required arguments: 343 --bundle BUNDLE Path to an existing bundle 344 --file FILE_PATH Path to a target file 345 346+--------------------------+-------------------------------------------+ 347| required arguments | 348+==========================+===========================================+ 349|``--file`` | Path to a target file | 350+--------------------------+-------------------------------------------+ 351|``--bundle`` | Path to bundle | 352+--------------------------+-------------------------------------------+ 353 354+--------------------------+-------------------------------------------+ 355| optional argument | 356+==========================+===========================================+ 357|``--new-name`` | Optional new name for target | 358+--------------------------+-------------------------------------------+ 359 360sign-bundle 361^^^^^^^^^^^ 362 363The ``sign-bundle`` subcommand signs an existing bundle with a dev key. 364 365.. code-block:: bash 366 367 $ pw update sign-bundle -h 368 369 usage: pw update sign-bundle [-h] --bundle BUNDLE --key KEY 370 371 Sign an existing bundle using a development key 372 373 optional arguments: 374 -h, --help show this help message and exit 375 376 required arguments: 377 --bundle BUNDLE Bundle to be signed 378 --key KEY Bundle signing key 379 380+--------------------------+-------------------------------------------+ 381| required arguments | 382+==========================+===========================================+ 383|``--key`` | Key to sign bundle | 384+--------------------------+-------------------------------------------+ 385|``--bundle`` | Path to bundle | 386+--------------------------+-------------------------------------------+ 387 388inspect-bundle 389^^^^^^^^^^^^^^ 390 391The ``inspect-bundle`` subcommand prints the contents of a given bundle. 392 393.. code-block:: bash 394 395 $ pw update inspect-bundle -h 396 397 usage: pw update inspect-bundle [-h] pathname 398 399 Outputs contents of bundle 400 401 positional arguments: 402 pathname Path to bundle 403 404 optional arguments: 405 -h, --help show this help message and exit 406 407 408+------------+------------+----------------+ 409| positional argument | 410+============+============+================+ 411|``pathname``|Path to bundle | 412+------------+------------+----------------+ 413 414verify-bundle 415^^^^^^^^^^^^^ 416 417The ``verify-bundle`` subcommand performs verification of an existing bundle. 418 419.. code-block:: bash 420 421 $ pw update verify-bundle -h 422 423 usage: pw update verify-bundle [-h] --bundle BUNDLE 424 --trusted-root-metadata ROOT_METADATA 425 426 Verify a bundle 427 428 optional arguments: 429 -h, --help show this help message and exit 430 431 required arguments: 432 --bundle BUNDLE Bundle to be verified 433 --trusted-root-metadata ROOT_METADATA Trusted root metadata 434 435+---------------------------+-------------------------------------------+ 436| required arguments | 437+===========================+===========================================+ 438|``--trusted-root-metadata``| Trusted root metadata(anchor) | 439+---------------------------+-------------------------------------------+ 440|``--bundle`` | Path of bundle to be verified | 441+---------------------------+-------------------------------------------+ 442 443Getting started with bundles (coming soon) 444========================================== 445