Implement support for on-device persistent digests.android-p-preview-1android-o-mr1-iot-preview-7o-mr1-iot-preview-7

This feature allows digests from on-device persistent storage to be used
in place of digests embedded in descriptors. This allows verification of
partitions which hold per-device configuration data set during a factory
or provisioning stage and expected to remain unchanged from that point
forward.

Support is added for both 'hash' and 'hashtree' descriptors. In the case
of hashtree descriptors, the verity root digest needs to be added to the
kernel command line so this can be configured later without access to
AVB persistent storage. This is accomplished by supporting substitutions
of the form $(AVB_<part_name>_ROOT_DIGEST) where <part_name> is the
uppercase partition name. For example, if the partition name was
'factory' the kernel command line descriptor would hold:

 "androidboot.vbmeta.root_digest.factory=$(AVB_FACTORY_ROOT_DIGEST)"

The persistent value ops are designed to be reusable. Persistent values
are expected to be tamper-proof, similar to rollback indexes, and are
not expected to be available outside of the boot code running AVB.

Using persistent digests also requires that the partition not use A/B.
A new flag has been added to avbtool to support this as well as a
'flags' field in hash and hashtree descriptors.

This CL bumps the AVB version to 1.1 and any use of persistent digests
(or the --do_not_use_ab flag) will set the minimum libavb version in
vbmeta to 1.1. If these features are not used, the minimum remains 1.0.

Bug: 73020477
Test: Unit

Change-Id: Iffef31b232492bc8700ab8496c5da2ccfb49be44

1 files changed, 65 insertions, 7 deletions

diff --git a/README.md b/README.md
index 0ad0a0b..bbcf96c 100644
--- a/README.md
+++ b/README.md
@@ -22,11 +22,14 @@ Verified Boot 2.0. Usually AVB is used to refer to this codebase.
     + [System Dependencies](#System-Dependencies)
     + [Locked and Unlocked mode](#Locked-and-Unlocked-mode)
     + [Tamper-evident Storage](#Tamper_evident-Storage)
+    + [Named Persistent Values](#Named-Persistent-Values)
+    + [Persistent Digests](#Persistent-Digests)
     + [Updating Stored Rollback Indexes](#Updating-Stored-Rollback-Indexes)
     + [Recommended Bootflow](#Recommended-Bootflow)
     + [Handling dm-verity Errors](#Handling-dm_verity-Errors)
     + [Android Specific Integration](#Android-Specific-Integration)
-    + [Device Specific Notes](Device-Specific-Notes)
+    + [Device Specific Notes](#Device-Specific-Notes)
+* [Version History](#Version-History)
 
 # What is it?
 
@@ -121,6 +124,12 @@ 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]`.
 
+In version 1.1 or later, avbtool supports `--do_not_use_ab` for
+`add_hash_footer` and `add_hashtree_footer` operations. This makes it
+possible to work with a partition that does not use A/B and should
+never have the prefix. This corresponds to the
+`AVB_HASH[TREE]_DESCRIPTOR_FLAGS_DO_NOT_USE_AB` flags.
+
 # Tools and Libraries
 
 This section contains information about the tools and libraries
@@ -335,7 +344,9 @@ added to an existing image as follows:
         [--signing_helper_with_files /path/to/external/signer_with_files]          \
         [--print_required_libavb_version]                                          \
         [--append_to_release_string STR]                                           \
-        [--calc_max_image_size]
+        [--calc_max_image_size]                                                    \
+        [--do_not_use_ab]                                                          \
+        [--use_persistent_digest]
 
 An integrity footer containing the root digest and salt for a hashtree
 for a partition can be added to an existing image as follows. The
@@ -356,7 +367,9 @@ hashtree is also appended to the image.
         [--signing_helper_with_files /path/to/external/signer_with_files]          \
         [--print_required_libavb_version]                                          \
         [--append_to_release_string STR]                                           \
-        [--calc_max_image_size]
+        [--calc_max_image_size]                                                    \
+        [--do_not_use_ab]                                                          \
+        [--use_persistent_digest]
 
 The size of an image with integrity footers can be changed using the
 `resize_image` command:
@@ -522,7 +535,7 @@ e.g. derive `AVB_pk`. Both `AVB_pk` and `AVB_pkmd` are passed to the
 `validate_vbmeta_public_key()` operation when verifying a slot.
 
 Some devices may support the end-user configuring the root of trust to use, see
-the [Device Specific Notes](Device-Specific-Notes) section for details.
+the [Device Specific Notes](#Device-Specific-Notes) section for details.
 
 To prevent rollback attacks, the rollback index should be increased on
 a regular basis. The rollback index can be set with the
@@ -639,9 +652,9 @@ 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
+used for verification, device state (whether the device is LOCKED or
+UNLOCKED), and named persistent values. 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.
 
@@ -651,6 +664,36 @@ 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.
 
+## Named Persistent Values
+
+AVB 1.1 introduces support for named persistent values which must be
+tamper evident and allows AVB to store arbitrary key-value pairs.
+Integrators may limit support for these values to a set of fixed
+well-known names, a maximum value size, and / or a maximum number of
+values.
+
+## Persistent Digests
+
+Using a persistent digest for a partition means the digest (or root
+digest in the case of a hashtree) is not stored in the descriptor but
+is stored in a named persistent value. This allows configuration data
+which may differ from device to device to be verified by AVB. It must
+not be possible to modify the persistent digest when the device is in
+the LOCKED state.
+
+To specify that a descriptor should use a persistent digest, use the
+`--use_persistent_digest` option for the `add_hash_footer` or
+`add_hashtree_footer` avbtool operations. Then, during verification of
+the descriptor, AVB will look for the digest in the named persistent
+value `avb.persistent_digest.$(partition_name)` instead of in the
+descriptor itself.
+
+For hashtree descriptors using a persistent digest, the digest value
+will be available for substitution into kernel command line descriptors
+using a token of the form `$(AVB_FOO_ROOT_DIGEST)` where 'FOO' is the
+uppercase partition name, in this case for the partition named 'foo'.
+The token will be replaced by the digest in hexadecimal form.
+
 ## Updating Stored Rollback Indexes
 
 In order for Rollback Protection to work the bootloader will need to
@@ -860,3 +903,18 @@ security features (including rollback-protection) are in effect, e.g. the
 
 When booting an image signed with a custom key, a yellow screen will be shown as
 part of the boot process to remind the user that the custom key is in use.
+
+# Version History
+
+### Version 1.1
+
+Version 1.1 adds support for the following:
+
+* A 32-bit `flags` element is added to hash and hashtree descriptors.
+* Support for partitions which don't use [A/B](#A_B-Support).
+* Tamper-evident [named persistent values](#Named-Persistent-Values).
+* [Persistent digests](#Persistent-Digests) for hash or hashtree descriptors.
+
+### Version 1.0
+
+All features not explicitly listed under a later version are supported by 1.0.