Update AVB docs to include overview, recommendations and best practices.
This information is currently in a separate document which is
confusing when things get out of sync, leading to bitrot and
worse. Instead, just include this information in README.md - this way
it's easy to point to and things don't bitrot!
Emphasize that recommendations and best practices are just that and
the word 'must' should be taken with a grain of salt. It is done this
way such that requirement docs for specific devices can point to a
specific version of README.md and say "the device MUST implementation
all recommendations (except X, Y, and Z) in this particular version of
external/avb/README.md".
Test: Renders fine in Markdown editor.
Test: All unit tests pass.
Bug: None
Change-Id: Iaae80e021180c1a18db8cdbd479e04c98f4c7d33
diff --git a/README.md b/README.md
index 775dbe4..54805a0 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,130 @@
# Android Verified Boot 2.0
+---
This repository contains tools and libraries for working with Android
Verified Boot 2.0. Usually AVB is used to refer to this codebase.
-## Introduction
+# Table of Contents
+
+* [What is it?](#What-is-it)
+ + [The VBMeta struct](#The-VBMeta-struct)
+ + [Rollback Protection](#Rollback-Protection)
+ + [A/B Support](#A_B-Support)
+* [Tools and Libraries](#Tools-and-Libraries)
+ + [avbtool and libavb](#avbtool-and-libavb)
+ + [Files and Directories](#Files-and-Directories)
+ + [Portability](#Portability)
+ + [Versioning and Compatibility](#Versioning-and-Compatibility)
+ + [Adding New Features](#Adding-New-Features)
+ + [Using avbtool](#Using-avbtool)
+ + [Build System Integration](#Build-System-Integration)
+* [Device Integration](#Device-Integration)
+ + [System Dependencies](#System-Dependencies)
+ + [Locked and Unlocked mode](#Locked-and-Unlocked-mode)
+ + [Tamper-evident Storage](#Tamper_evident-Storage)
+ + [Updating Stored Rollback Indexes](#Updating-Stored-Rollback-Indexes)
+ + [Recommended Bootflow](#Recommended-Bootflow)
+ + [Android Specific Integration](#Android-Specific-Integration)
+
+# What is it?
+
+Verified boot is the process of assuring the end user of the integrity
+of the software running on a device. It typically starts with a
+read-only portion of the device firmware which loads code and executes
+it only after cryptographically verifying that the code is authentic
+and doesn't have any known security flaws. AVB is one implementation
+of verified boot.
+
+## The VBMeta struct
+
+The central data structure used in AVB is the VBMeta struct. This data
+structure contains a number of descriptors (and other metadata) and
+all of this data is cryptographically signed. Descriptors are used for
+image hashes, image hashtree metadata, and so-called *chained
+partitions*. A simple example is the following:
+
+
+
+where the `vbmeta` partition holds the hash for the `boot` partition
+in a hash descriptor. For the `system` and `vendor` partitions a
+hashtree follows the filesystem data and the `vbmeta` partition holds
+the root hash, salt, and offset of the hashtree in hashtree
+descriptors. Because the VBMeta struct in the `vbmeta` partition is
+cryptographically signed, the boot loader can check the signature and
+verify it was made by the owner of `key0` (by e.g. embedding the
+public part of `key0`) and thereby trust the hashes used for `boot`,
+`system`, and `vendor`.
+
+A chained partition descriptor is used to delegate authority - it
+contains the name of the partition where authority is delegated as
+well as the public key that is trusted for signatures on this
+particular partition. As an example, consider the following setup:
+
+
+
+In this setup the `xyz` partition has a hashtree for
+integrity-checking. Following the hashtree is a VBMeta struct which
+contains the hashtree descriptor with hashtree metadata (root hash,
+salt, offset, etc.) and this struct is signed with `key1`. Finally, at
+the end of the partition is a footer which has the offset of the
+VBMeta struct.
+
+This setup allows the bootloader to use the chain partition descriptor
+to find the footer at the end of the partition (using the name in the
+chain partition descriptor) which in turns helps locate the VBMeta
+struct and verify that it was signed by `key1` (using `key1_pub` stored in the
+chain partition descriptor). Crucially, because there's a footer with
+the offset, the `xyz` partition can be updated without the `vbmeta`
+partition needing any changes.
+
+The VBMeta struct is flexible enough to allow hash descriptors and
+hashtree descriptors for any partition to live in either the `vbmeta`
+partition or - via a chain partition descriptor - in the partition
+that they are used to integrity check. This allows for a wide range of
+organizational and trust relationships.
+
+## Rollback Protection
+
+AVB includes Rollback Protection which is used to protect against
+known security flaws. Each VBMeta struct has a *rollback index* baked
+into it like the following:
+
+
+
+These numbers are referred to as `rollback_index[n]` and are increased
+for each image as security flaws are discovered and
+fixed. Additionally the device stores the last seen rollback index in
+tamper-evident storage:
+
+
+
+and these are referred to as `stored_rollback_index[n]`.
+
+Rollback protection is having the device reject an image unless
+`rollback_index[n]` >= `stored_rollback_index[n]` for all `n`, and
+having the device increase `stored_rollback_index[n]` over
+time. Exactly how this is done is discussed in
+the
+[Updating Stored Rollback Indexes](#Updating-Stored-Rollback-Indexes)
+section.
+
+## A/B Support
+
+AVB has been designed to work with A/B by requiring that the A/B
+suffix is never used in any partition names stored in
+descriptors. Here's an example with two slots:
+
+
+
+Note how the rollback indexes differ between slots - for slot A the
+rollback indexes are `[42, 101]` and for slot B they are `[43, 103]`.
+
+# Tools and Libraries
+
+This section contains information about the tools and libraries
+included in AVB.
+
+## avbtool and libavb
The main job of `avbtool` is to create `vbmeta.img` which is the
top-level object for verified boot. This image is designed to go into
@@ -26,53 +147,17 @@
In addition to `avbtool`, a library - `libavb` - is provided. This
library performs all verification on the device side e.g. it starts by
-loading the vbmeta partition, checks the signature, and then goes on
-to load the boot partition for verification. This library is intended
-to be used in both boot loaders and inside Android. It has a simple
-abstraction for system dependencies (see `avb_sysdeps.h`) as well as
-operations that the boot loader or OS is expected to implement (see
-`avb_ops.h`). The main entry point for verification is
+loading the `vbmeta` partition, checks the signature, and then goes on
+to load the `boot` partition for verification. This library is
+intended to be used in both boot loaders and inside Android. It has a
+simple abstraction for system dependencies (see `avb_sysdeps.h`) as
+well as operations that the boot loader or OS is expected to implement
+(see `avb_ops.h`). The main entry point for verification is
`avb_slot_verify()`.
-It is expected that most devices will use A/B (e.g. multiple copies of
-the OS in separate so-called 'slots') in addition to AVB. While
-managing A/B metadata and associated metadata (e.g. managing
-`stored_rollback_index[n]` locations) is outside the scope of
-`libavb`, enough interfaces are exposed so the boot loader can
-integrate its A/B stack with `libavb`. In particular
-`avb_slot_verify()` takes a `slot_suffix` parameter and its result
-struct `AvbSlotVerifyData` convey the rollback indexes in the image
-that was verified.
-
-AVB also includes an A/B implementation that boot loaders may
-optionally use. This implementation is in the `libavb_ab` library and
-integrates with image verification including updating the
-`stored_rollback_index[n]` locations on the device as needed. The
-bootloader can use this through the `avb_ab_flow()` function which in
-turn calls `avb_slot_verify()` as needed.
-
-In `libavb_ab`, A/B metadata is stored in the `misc` partition using a
-format private to `libavb_ab` in the location on `misc` reserved for
-this. For more information about the `misc.img` file format see
-the
-[bootloader_message.h](https://android.googlesource.com/platform/bootable/recovery/+/master/bootloader_message/include/bootloader_message/bootloader_message.h) file
-in AOSP. A/B metadata can be written to `misc.img` using the
-`set_ab_metadata` sub-command of `avbtool`. A/B metadata is comprised
-of data for each slo and per-slot metadata has a priority field (0 to
-15), number of tries remaining for attempting to boot the slot (0 to
-7), and a flag to indicate whether the slot has successfully booted.
-
-A/B metadata integrity is provided by a simple magic marker and a
-CRC-32 checksum. If invalid A/B metadata is detected, the behavior is
-to reset the A/B metadata to a known state where both slots are given
-seven boot tries.
-
-An implementation of a boot_control HAL using AVB-specific A/B
-metadata is also provided.
-
Android Things has specific requirements and validation logic for the
vbmeta public key. An extension is provided in `libavb_atx` which
-performs this validation as an implementatio of `libavb`'s public key
+performs this validation as an implementation of `libavb`'s public key
validation operation (see `avb_validate_vbmeta_public_key()` in
`avb_ops.h`).
@@ -89,17 +174,18 @@
`avb_sysdeps.h`. If the platform provides the standard C runtime
`avb_sysdeps_posix.c` can be used.
* `libavb_ab/`
- + An A/B implementation for use in boot loaders.
+ + An experimental A/B implementation for use in boot loaders
+ and AVB examples.
* `libavb_atx/`
+ An Android Things Extension for validating public key metadata.
* `libavb_user/`
- + Contains an AvbOps implementation suitable for use in userspace
- on the device (used in boot_control.avb and avbctl).
+ + Contains an `AvbOps` implementation suitable for use in Android
+ userspace. This is used in `boot_control.avb` and `avbctl`.
* `boot_control/`
- + An implemementation of the Android boot_control HAL for use with
- boot loaders using `libavb_ab`.
+ + An implementation of the Android `boot_control` HAL for use with
+ boot loaders using the experimental `libavb_ab` A/B stack.
* `Android.mk`
- + Build instructions for building libavb (a static library for use
+ + Build instructions for building `libavb` (a static library for use
on the device), host-side libraries (for unit tests), and unit
tests.
* `avbtool`
@@ -110,31 +196,36 @@
`libavb_atx`.
* `tools/avbctl/`
+ Contains the source-code for a tool that can be used to control
- AVB at runtime.
+ AVB at runtime in Android.
* `examples/uefi/`
+ Contains the source-code for a UEFI-based boot-loader utilizing
`libavb/` and `libavb_ab/`.
+* `README.md`
+ + This file.
+* `docs/`
+ + Contains documentation files.
-## Audience and portability notes
+## Portability
-This code is intended to be used in bootloaders in devices running
-Android. The suggested approach is to copy the appropriate header and
-C files mentioned in the previous section into the boot loader and
-integrate as appropriate.
+The `libavb` code is intended to be used in bootloaders in devices
+that will load Android or other operating systems. The suggested
+approach is to copy the appropriate header and C files mentioned in
+the previous section into the boot loader and integrate as
+appropriate.
-The `libavb/` and `libavb_ab/` codebase will evolve over time so
-integration should be as non-invasive as possible. The intention is to
-keep the API of the library stable however it will be broken if
-necessary. As for portability, the library is intended to be highly
-portable, work on both little- and big-endian architectures and 32-
-and 64-bit. It's also intended to work in non-standard environments
-without the standard C library and runtime.
+As the `libavb/` codebase will evolve over time integration should be
+as non-invasive as possible. The intention is to keep the API of the
+library stable however it will be broken if necessary. As for
+portability, the library is intended to be highly portable, work on
+both little- and big-endian architectures and 32- and 64-bit. It's
+also intended to work in non-standard environments without the
+standard C library and runtime.
If the `AVB_ENABLE_DEBUG` preprocessor symbol is set, the code will
include useful debug information and run-time checks. Production
builds should not use this. The preprocessor symbol `AVB_COMPILATION`
should be set only when compiling the libraries. The code must be
-compiled into a separate libraries.
+compiled into a separate library.
Applications using the compiled `libavb` library must only include the
`libavb/libavb.h` file (which will include all public interfaces) and
@@ -143,7 +234,7 @@
example `avb_sha.[ch]` and `avb_rsa.[ch]`) will not be visible to
application code.
-## Versioning and compatibility
+## Versioning and Compatibility
AVB uses a version number with three fields - the major, minor, and
sub version. Here's an example version number
@@ -181,7 +272,7 @@
if, for example, creating an image that does not use any features
added after AVB version 1.0.
-## Adding new features
+## Adding New Features
If adding a new feature for example a new algorithm or a new
descriptor then `AVB_VERSION_MINOR` in `avb_version.h` and `avbtool`
@@ -197,7 +288,7 @@
If `AVB_VERSION_MINOR` has already been bumped since the last release
there is obviously no need to bump it again.
-## Usage
+## Using avbtool
The content for the vbmeta partition can be generated as follows:
@@ -297,9 +388,9 @@
--vbmeta_image vbmeta.img
$ fastboot flash boot boot-with-vbmeta-appended.img
-## Build system integration notes
+## Build System Integration
-Android Verified Boot is enabled by the `BOARD_AVB_ENABLE` variable
+In Android, AVB is enabled by the `BOARD_AVB_ENABLE` variable
BOARD_AVB_ENABLE := true
@@ -322,11 +413,11 @@
Remember that the public part of this key needs to be available to the
bootloader of the device expected to verify resulting images. Use
`avbtool extract_public_key` to extract the key in the expected format
-(**AVB_pk** in the following). If the device is using a different root
-of trust than **AVB_pk** the `--public_key_metadata` option can be
-used to embed a blob (**AVB_pkmd** in the following) that can be used
-to e.g. derive **AVB_pk**. Both **AVB_pk** and **AVB_pkmd** are passed
-to the `validate_vbmeta_public_key()` operation when verifying a slot.
+(`AVB_pk` in the following). If the device is using a different root
+of trust than `AVB_pk` the `--public_key_metadata` option can be used
+to embed a blob (`AVB_pkmd` in the following) that can be used to
+e.g. derive `AVB_pk`. Both `AVB_pk` and `AVB_pkmd` are passed to the
+`validate_vbmeta_public_key()` operation when verifying a slot.
To prevent rollback attacks, the rollback index should be increased on
a regular basis. The rollback index can be set with the
@@ -356,5 +447,213 @@
for `vendor.img`. Typical options to be used here include
`--hash_algorithm`, `--salt`, `--block_size`, and `--generate_fec`.
+The variable `BOARD_AVB_DTBO_ADD_HASH_FOOTER_ARGS` can be used to
+specify additional options passed to `avbtool add_hash_footer` for
+`dtbo.img`. Typical options to be used here include `--hash_algorithm`
+and `--salt`.
+
Build system variables (such as `PRODUCT_SUPPORTS_VERITY_FEC`) used
-for previous version of Verified Boot in Android are not used in AVB
+for previous version of Verified Boot in Android are not used in AVB.
+
+# Device Integration
+
+This section discusses recommendations and best practices for
+integrating `libavb` with a device boot loader. It's important to
+emphasize that these are just recommendations so the use of the word
+`must` should be taken lightly.
+
+Additionally term *HLOS* is used in this chapter to refer to the *High
+Level Operating System*. This obviously includes Android (including
+other form-factors than phones) but could also be other operating
+systems.
+
+## System Dependencies
+
+The `libavb` library is written in a way so it's portable to any
+system with a C99 compiler. It does not require the standard C library
+however the boot loader must implement a simple set of system
+primitives required by `libavb` such as `avb_malloc()`, `avb_free()`,
+and `avb_print()`.
+
+In addition to the system primitives, `libavb` interfaces with the boot
+loader through the supplied `AvbOps` struct. This includes operations
+to read and write data from partitions, read and write rollback
+indexes, check if the public key used to make a signature should be
+accepted, and so on.
+
+## Locked and Unlocked mode
+
+AVB has been designed to support the notion of the device being either
+LOCKED state or UNLOCKED state as used in Android.
+
+In the context of AVB, the LOCKED state means that verification errors
+are fatal whereas in UNLOCKED state they are not. If the device is
+UNLOCKED pass `true` in the `allow_verification_error` parameter of
+`avb_slot_verify()` and treat verification errors including
+
+* `AVB_SLOT_VERIFY_RESULT_ERROR_PUBLIC_KEY_REJECTED`
+* `AVB_SLOT_VERIFY_RESULT_ERROR_VERIFICATION`
+* `AVB_SLOT_VERIFY_RESULT_ERROR_ROLLBACK_INDEX`
+
+as non-fatal. If the device is in the LOCKED state, pass `false` in
+the `allow_verification_error` parameter of `avb_slot_verify()` and
+only treat `AVB_SLOT_VERIFY_RESULT_OK` as non-fatal.
+
+On Android, device state may be altered through the fastboot interface
+using, e.g. `fastboot flashing lock` (to transition to the LOCKED
+state) and `fastboot flashing unlock` (to transition to the UNLOCKED
+state).
+
+The device must only allow state transitions (e.g. from LOCKED to
+UNLOCKED or UNLOCKED to LOCKED) after asserting physical presence of
+the user. If the device has a display and buttons this is typically
+done by showing a dialog and requiring the user to confirm or cancel
+using physical buttons.
+
+All user data must be cleared when transitioning from the LOCKED to
+the UNLOCKED state (including the `userdata` partition and any NVRAM
+spaces). Additionally all `stored_rollback_index[n]` locations must be
+cleared (all elements must be set to zero). Similar action (erasing
+`userdata`, NVRAM spaces, and `stored_rollback_index[n]` locations)
+shall also happening when transitioning from UNLOCKED to LOCKED. If
+the device is required to use full disk encryption, then a less
+intensive wipe is required for UNLOCKED to LOCKED. Depending on the
+device form-factor and intended use, the user should be prompted to
+confirm before any data is erased.
+
+## Tamper-evident Storage
+
+In this document, *tamper-evident* means that it's possible to detect
+if the HLOS has tampered with the data, e.g. if it has been
+overwritten.
+
+Tamper-evident storage must be used for stored rollback indexes, keys
+used for verification, and device state (whether the device is LOCKED
+or UNLOCKED). If tampering has been detected the corresponding
+`AvbOps` operation should fail by e.g. returning
+`AVB_IO_RESULT_ERROR_IO`. It is especially important that verification
+keys cannot be tampered with since they represent the root-of-trust.
+
+If verification keys are mutable they must only be set by the end
+user, e.g. it must never be set at the factory or store or any
+intermediate point before the end user. Additionally, it must only be
+possible to set or clear a key while the device is in the UNLOCKED
+state.
+
+## Updating Stored Rollback Indexes
+
+In order for Rollback Protection to work the bootloader will need to
+update the `stored_rollback_indexes[n]` array on the device prior to
+transferring control to the HLOS. If not using A/B this is
+straightforward - just update it to what's in the AVB metadata for the
+slot before booting. In pseudo-code it would look like this:
+
+```c++
+// The |slot_data| parameter should be the AvbSlotVerifyData returned
+// by avb_slot_verify() for the slot we're about to boot.
+//
+bool update_stored_rollback_indexes_for_slot(AvbOps* ops,
+ AvbSlotVerifyData* slot_data) {
+ for (int n = 0; n < AVB_MAX_NUMBER_OF_ROLLBACK_INDEX_LOCATIONS; n++) {
+ uint64_t rollback_index = slot_data->rollback_indexes[n];
+ if (rollback_index > 0) {
+ AvbIOResult io_ret;
+ uint64_t current_stored_rollback_index;
+
+ io_ret = ops->read_rollback_index(ops, n, ¤t_stored_rollback_index);
+ if (io_ret != AVB_IO_RESULT_OK) {
+ return false;
+ }
+
+ if (rollback_index > current_stored_rollback_index) {
+ io_ret = ops->write_rollback_index(ops, n, rollback_index);
+ if (io_ret != AVB_IO_RESULT_OK) {
+ return false;
+ }
+ }
+ }
+ }
+ return true;
+}
+```
+
+However if using A/B more care must be taken to still allow the device
+to fall back to the old slot if the update didn't work.
+
+For an HLOS like Android where rollback is only supported if the
+updated OS version is found to not work, `stored_rollback_index[n]`
+should only be updated from slots that are marked as SUCCESSFUL in the
+A/B metadata. The pseudo-code for that is as follows where
+`is_slot_is_marked_as_successful()` comes from the A/B stack in use:
+
+```c++
+if (is_slot_is_marked_as_successful(slot->ab_suffix)) {
+ if (!update_stored_rollback_indexes_for_slot(ops, slot)) {
+ // TODO: handle error.
+ }
+}
+```
+
+For an HLOS where it's possible to roll back to a previous version,
+`stored_rollback_index[n]` should be set to the largest possible value
+allowing all bootable slots to boot. This approach is implemented in
+AVB's experimental A/B stack `libavb_ab`, see the `avb_ab_flow()`
+implementation. Note that this requires verifying *all* bootable slots
+at every boot and this may impact boot time.
+
+## Recommended Bootflow
+
+The recommended boot flow for a device using AVB is as follows:
+
+
+
+Notes:
+
+* The device is expected to search through all A/B slots until it
+ finds a valid OS to boot. Slots that are rejected in the LOCKED
+ state might not be rejected in the UNLOCKED state, (e.g. when
+ UNLOCKED any key can be used and rollback index failures are
+ allowed), so the algorithm used for selecting a slot varies
+ depending on what state the device is in.
+
+* If no valid OS (that is, no bootable A/B slot) can be found, the
+ device cannot boot and has to enter repair mode. It is
+ device-dependent what this looks like. If the device has a screen
+ it must convey this state to the user.
+
+* If the device is LOCKED, only an OS signed by an embedded
+ verification key (see the previous section) shall be
+ accepted. Additionally, the rollback indexes in the verified image
+ must not exceed those stored on the device and
+ `stored_rollback_index[n]` on the device are expected to be updated
+ as specified in the previous section.
+ + If the key used for verification was set by the end user, and
+ the device has a screen, it must show a warning with the key
+ fingerprint to convey that the device is booting a custom
+ OS. The warning must be shown for at least 10 seconds before the
+ boot process continues. If the device does not have a screen,
+ other ways must be used to convey that the device is booting a
+ custom OS (lightbars, LEDs, etc.).
+
+* If the device is UNLOCKED, there is no requirement to check the key
+ used to sign the OS nor is there any requirement to check or update
+ rollback `stored_rollback_index[n]` on the device. Because of this
+ the user must always be shown a warning about verification not
+ occurring.
+ + It is device-dependent how this is implemented since it depends
+ on the device form-factor and intended usage. If the device has
+ a screen and buttons (for example if it's a phone) the warning
+ is to be shown for at least 10 seconds before the boot process
+ continues. If the device does not have a screen, other ways must
+ be used to convey that the device is UNLOCKED (lightbars, LEDs,
+ etc.).
+
+## Android Specific Integration
+
+On Android, the boot loader must set the
+`androidboot.verifiedbootstate` parameter on the kernel command-line
+to indicate the boot state. It shall use the following values:
+
+* **green**: If in LOCKED state and the key used for verification was not set by the end user.
+* **yellow**: If in LOCKED state and the key used for verification was set by the end user.
+* **orange**: If in the UNLOCKED state.
diff --git a/docs/avb-ab-partitions.png b/docs/avb-ab-partitions.png
new file mode 100644
index 0000000..0422ad8
--- /dev/null
+++ b/docs/avb-ab-partitions.png
Binary files differ
diff --git a/docs/avb-chained-partition.png b/docs/avb-chained-partition.png
new file mode 100644
index 0000000..9500e82
--- /dev/null
+++ b/docs/avb-chained-partition.png
Binary files differ
diff --git a/docs/avb-integrity-data-in-vbmeta.png b/docs/avb-integrity-data-in-vbmeta.png
new file mode 100644
index 0000000..3f8827e
--- /dev/null
+++ b/docs/avb-integrity-data-in-vbmeta.png
Binary files differ
diff --git a/docs/avb-recommended-boot-flow.png b/docs/avb-recommended-boot-flow.png
new file mode 100644
index 0000000..ed5dc04
--- /dev/null
+++ b/docs/avb-recommended-boot-flow.png
Binary files differ
diff --git a/docs/avb-rollback-indexes.png b/docs/avb-rollback-indexes.png
new file mode 100644
index 0000000..2e5f48d
--- /dev/null
+++ b/docs/avb-rollback-indexes.png
Binary files differ
diff --git a/docs/avb-stored-rollback-indexes.png b/docs/avb-stored-rollback-indexes.png
new file mode 100644
index 0000000..bd3279a
--- /dev/null
+++ b/docs/avb-stored-rollback-indexes.png
Binary files differ
