From 8ff6e91f0b2034b33c16c7c16328b57d23e4dcc2 Mon Sep 17 00:00:00 2001 From: Ali Zhang Date: Thu, 8 Sep 2022 16:40:11 +0000 Subject: [PATCH] pw_software_update: docs: rewrite Rewrite to explain things better (hopefully :-). Bug: 231160054 Change-Id: I6624e9ee73c321cdea79d3f81d4c3bdfbc78a7c7 Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/109470 Reviewed-by: Yecheng Zhao Commit-Queue: Ali Zhang --- pw_software_update/docs.rst | 216 ++++++++++++++++-------------------- 1 file changed, 96 insertions(+), 120 deletions(-) diff --git a/pw_software_update/docs.rst b/pw_software_update/docs.rst index c5bdd67462..2a0cb34448 100644 --- a/pw_software_update/docs.rst +++ b/pw_software_update/docs.rst @@ -4,123 +4,99 @@ pw_software_update ------------------- -This module provides the building blocks for trusted software update systems. - -Goals -===== - -**Software update** is any system that enables a product *vendor* to deliver -some kind of *improvement* to a product *consumer*, in good faith. - -To that definition, a software update system should design toward the following -goals. - -1. The product receives feature, performance, stability, UX improvements with - minimum intervention from both the vendor and consumer. The product just - automatically gets **increasingly more useful**. - -2. The product receives timely security patches in response to newly discovered - vulnerabilities and/or expiring trust material etc. The product is - **self-healing**. - -3. All software updates **require consumer approval**. The product vendor being - able to remotely modify a product's behavior is both fantastic and risky. - The system must mitigate insider attacks that may happen by mistake, - willingly, or when compelled. The product vendor should strive to help the - consumer make an informed decision over whether or not, when, and how to - check / install what updates, to the extent feasible and as required by local - regulations. - -4. Software updates **liberate engineering workflows**. While security-heavy - systems tend to compete with consumer-facing features for attention and - resources and thus perceived as "necessary evil", it is often a - misconception. With careful design, security features can preserve and - enlarge flexibility in affected workflows. No law, no freedom. - -System overview -=============== - -At its core, software update is a system that allows a consumer to download some -file provided by some vendor **by choice**. That choice might be "I want to be -left alone. I will not check for updates and I wish not to be solicited", or -"I want to sign my life away and never be bothered again. Please automatically -check and install all updates as soon as they are available", or anything in -between those two extremes. - -How a consumer approaches such a choice depends on many factors. - -1. The consumer's ability to authenticate the files, and by derivation, their - vendor. Authentication enables the consumer to identify the update vendor ( - with cryptographic non-deniability) and assign some **baseline trust** to - it based on individual judgment and the public credibility of the vendor. - - .. note:: From the vendor's point of view, authentication also protects the - vendor's product from being tampered by attackers or consumers. - Traditionally that has been the main purpose of security in software update - systems. - -2. The consumer's ability to independently audit the update files. e.g. by - re-producing bitwise-identical binaries from available source code, hiring an - accredited security researcher / investigator, looking up the files from a - publicly available non-forgeable ledger etc. - -3. The consumer's ability to assess the "bomb radius" of allowing an update, - i.e. the worst possible fallout that may result from the vendor betraying the - consumer's baseline trust. On platforms with well designed trust structure, - it is easy for a generally informed consumer to reason that a misbehaving car - infotainment app won't be able to take control of "system" and drive the car - into a ditch, unless the application manages to escape its capabilities - sandbox set up by the governing system software, either by exploiting a bug - in the system or by colluding with the system vendor. - -4. The consumer's situation. All else being equal, a developer evaluating a - smart speaker with a test account, a US senator carrying a smartphone, - and an airliner technician maintaining a fleet of passenger aircraft - will approach software update choices with drastically different discretion. - -It is in the best interests of both consumers and vendors to design and fit -software update systems in various platforms in a way that bolsters mutual -trust. So let's discuss this further in the "security model". - -Security model --------------- - -Authentication -^^^^^^^^^^^^^^ - -`pw_software_update` adopts `TUF `_ as the -authentication framework. This framework is well-formulated in the TUF -`specification `_ (a -leisure read). To help with context continuity, the most relevant points are -captured below. - -.. attention:: 🚧🏗 This documentation is under construction. The trucks were - last seen here. 🏗🚧 - - -Authorization -^^^^^^^^^^^^^ - -Transparency -^^^^^^^^^^^^ - -Deployment model ----------------- - -Getting started -=============== - -Developer guides -================ - -POUF(Protocol, Operations, Usage and Format) --------------------------------------------- - -Update serving --------------- - -Update consumption ------------------- - -Requesting a security review ----------------------------- \ No newline at end of file +This module provides the following building blocks of a high assurance software +update system: + +1. A `TUF `_-based security framework. +2. A `protocol buffer `_ 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. + +Getting started with bundles (coming soon) +========================================== \ No newline at end of file