1# Android Verified Boot 2.0 2--- 3 4This repository contains tools and libraries for working with Android 5Verified Boot 2.0. Usually AVB is used to refer to this codebase. 6 7# Table of Contents 8 9* [What is it?](#what-is-it) 10 + [The VBMeta struct](#the-vbmeta-struct) 11 + [Rollback Protection](#rollback-Protection) 12 + [A/B Support](#a_b-Support) 13 + [The VBMeta Digest](#the-vbmeta-digest) 14* [Tools and Libraries](#tools-and-libraries) 15 + [avbtool and libavb](#avbtool-and-libavb) 16 + [Files and Directories](#files-and-directories) 17 + [Portability](#portability) 18 + [Versioning and Compatibility](#versioning-and-compatibility) 19 + [Adding New Features](#adding-new-features) 20 + [Using avbtool](#using-avbtool) 21 + [Build System Integration](#build-system-integration) 22* [Device Integration](#device-integration) 23 + [System Dependencies](#system-dependencies) 24 + [Locked and Unlocked mode](#locked-and-unlocked-mode) 25 + [Tamper-evident Storage](#tamper_evident-storage) 26 + [Named Persistent Values](#named-persistent-values) 27 + [Persistent Digests](#persistent-digests) 28 + [Updating Stored Rollback Indexes](#updating-stored-rollback-indexes) 29 + [Recommended Bootflow](#recommended-bootflow) 30 + [Booting Into Recovery](#booting-into-recovery) 31 + [Handling dm-verity Errors](#handling-dm_verity-errors) 32 + [Android Specific Integration](#android-specific-integration) 33 + [Device Specific Notes](#device-specific-notes) 34* [Version History](#version-history) 35 36# What is it? 37 38Verified boot is the process of assuring the end user of the integrity 39of the software running on a device. It typically starts with a 40read-only portion of the device firmware which loads code and executes 41it only after cryptographically verifying that the code is authentic 42and doesn't have any known security flaws. AVB is one implementation 43of verified boot. 44 45## The VBMeta struct 46 47The central data structure used in AVB is the VBMeta struct. This data 48structure contains a number of descriptors (and other metadata) and 49all of this data is cryptographically signed. Descriptors are used for 50image hashes, image hashtree metadata, and so-called *chained 51partitions*. A simple example is the following: 52 53 54 55where the `vbmeta` partition holds the hash for the `boot` partition 56in a hash descriptor. For the `system` and `vendor` partitions a 57hashtree follows the filesystem data and the `vbmeta` partition holds 58the root hash, salt, and offset of the hashtree in hashtree 59descriptors. Because the VBMeta struct in the `vbmeta` partition is 60cryptographically signed, the boot loader can check the signature and 61verify it was made by the owner of `key0` (by e.g. embedding the 62public part of `key0`) and thereby trust the hashes used for `boot`, 63`system`, and `vendor`. 64 65A chained partition descriptor is used to delegate authority - it 66contains the name of the partition where authority is delegated as 67well as the public key that is trusted for signatures on this 68particular partition. As an example, consider the following setup: 69 70 71 72In this setup the `xyz` partition has a hashtree for 73integrity-checking. Following the hashtree is a VBMeta struct which 74contains the hashtree descriptor with hashtree metadata (root hash, 75salt, offset, etc.) and this struct is signed with `key1`. Finally, at 76the end of the partition is a footer which has the offset of the 77VBMeta struct. 78 79This setup allows the bootloader to use the chain partition descriptor 80to find the footer at the end of the partition (using the name in the 81chain partition descriptor) which in turns helps locate the VBMeta 82struct and verify that it was signed by `key1` (using `key1_pub` stored in the 83chain partition descriptor). Crucially, because there's a footer with 84the offset, the `xyz` partition can be updated without the `vbmeta` 85partition needing any changes. 86 87The VBMeta struct is flexible enough to allow hash descriptors and hashtree 88descriptors for any partition to live in the `vbmeta` partition, the partition 89that they are used to integrity check (via a chain partition descriptor), or any 90other partition (via a chain partition descriptor). This allows for a wide range 91of organizational and trust relationships. 92 93Chained partitions need not use a footer - it is permissible to have a chained 94partition point to a partition where the VBMeta struct is at the beginning 95(e.g. just like the `vbmeta` partition). This is useful for use-cases where all 96hash- and hashtree-descriptors for the partitions owned by an entire 97organization are stored in a dedicated partition, for example `vbmeta_google`. 98In this example the hashtree descriptor for `system` is in the `vbmeta_google` 99partition meaning that the bootloader doesn't need to access the `system` 100partition at all which is helpful if the `system` partition is managed as a 101logical partition (via e.g. [LVM 102techniques](https://en.wikipedia.org/wiki/Logical_volume_management) or 103similar). 104 105## Rollback Protection 106 107AVB includes Rollback Protection which is used to protect against 108known security flaws. Each VBMeta struct has a *rollback index* baked 109into it like the following: 110 111 112 113These numbers are referred to as `rollback_index[n]` and are increased 114for each image as security flaws are discovered and 115fixed. Additionally the device stores the last seen rollback index in 116tamper-evident storage: 117 118 119 120and these are referred to as `stored_rollback_index[n]`. 121 122Rollback protection is having the device reject an image unless 123`rollback_index[n]` >= `stored_rollback_index[n]` for all `n`, and 124having the device increase `stored_rollback_index[n]` over 125time. Exactly how this is done is discussed in 126the 127[Updating Stored Rollback Indexes](#updating-stored-rollback-indexes) 128section. 129 130## A/B Support 131 132AVB has been designed to work with A/B by requiring that the A/B 133suffix is never used in any partition names stored in 134descriptors. Here's an example with two slots: 135 136 137 138Note how the rollback indexes differ between slots - for slot A the 139rollback indexes are `[42, 101]` and for slot B they are `[43, 103]`. 140 141In version 1.1 or later, avbtool supports `--do_not_use_ab` for 142`add_hash_footer` and `add_hashtree_footer` operations. This makes it 143possible to work with a partition that does not use A/B and should 144never have the prefix. This corresponds to the 145`AVB_HASH[TREE]_DESCRIPTOR_FLAGS_DO_NOT_USE_AB` flags. 146 147In version 1.3, avbtool supports `chain_partition_do_not_use_ab` for 148`make_vbmeta_image` operations. This makes it possible to work with 149a chain partition that does not use A/B and should not have the suffix. 150This corresponds to the `AVB_CHAIN_PARTITION_DESCRIPTOR_FLAGS_DO_NOT_USE_AB` flag. 151 152## The VBMeta Digest 153 154The VBMeta digest is a digest over all VBMeta structs including the root struct 155(e.g. in the `vbmeta` partition) and all VBMeta structs in chained 156partitions. This digest can be calculated at build time using `avbtool 157calculate_vbmeta_digest` and also at runtime using the 158`avb_slot_verify_data_calculate_vbmeta_digest()` function. It is also set on the 159kernel command-line as `androidboot.vbmeta.digest`, see the `avb_slot_verify()` 160documentation for exact details. 161 162This digest can be used together with `libavb` in userspace inside the loaded 163operating system to verify authenticity of the loaded vbmeta structs. This is 164useful if the root-of-trust and/or stored rollback indexes are only available 165while running in the boot loader. 166 167Additionally, if the VBMeta digest is included in [hardware-backed attestation 168data](https://developer.android.com/training/articles/security-key-attestation) 169a relying party can extract the digest and compare it with list of digests for 170known good operating systems which, if found, provides additional assurance 171about the device the application is running on. 172 173For [factory images of Pixel 3 and later 174devices](https://developers.google.com/android/images), the 175`pixel_factory_image_verify.py` located in `tools/transparency` is a convenience 176tool for downloading, verifying and calcuating VBMeta Digests. 177 178 $ pixel_factory_image_verify.py https://dl.google.com/dl/android/aosp/image.zip 179 Fetching file from: https://dl.google.com/dl/android/aosp/image.zip 180 Successfully downloaded file. 181 Successfully unpacked factory image. 182 Successfully unpacked factory image partitions. 183 Successfully verified VBmeta. 184 Successfully calculated VBMeta Digest. 185 The VBMeta Digest for factory image is: 1f329b20a2dd69425e7a29566ca870dad51d2c579311992d41c9ba9ba05e170e 186 187If the given argument is not an URL it considered to be a local file: 188 189 $ pixel_factory_image_verify.py image.zip 190 191# Tools and Libraries 192 193This section contains information about the tools and libraries 194included in AVB. 195 196## avbtool and libavb 197 198The main job of `avbtool` is to create `vbmeta.img` which is the 199top-level object for verified boot. This image is designed to go into 200the `vbmeta` partition (or, if using A/B, the slot in question 201e.g. `vbmeta_a` or `vbmeta_b`) and be of minimal size (for out-of-band 202updates). The vbmeta image is cryptographically signed and contains 203verification data (e.g. cryptographic digests) for verifying 204`boot.img`, `system.img`, and other partitions/images. 205 206The vbmeta image can also contain references to other partitions where 207verification data is stored as well as a public key indicating who 208should sign the verification data. This indirection provides 209delegation, that is, it allows a 3rd party to control content on a 210given partition by including their public key in `vbmeta.img`. By 211design, this authority can be easily revoked by simply updating 212`vbmeta.img` with new descriptors for the partition in question. 213 214Storing signed verification data on other images - for example 215`boot.img` and `system.img` - is also done with `avbtool`. 216 217The minimum requirement for running `avbtool` is to either have 218Python 3.5 installed or build the avbtool with the embedded launcher 219using `m avbtool` and then run it out of the build artifact directory: 220`out/soong/host/linux-x86/bin/avbtool` 221 222In addition to `avbtool`, a library - `libavb` - is provided. This 223library performs all verification on the device side e.g. it starts by 224loading the `vbmeta` partition, checks the signature, and then goes on 225to load the `boot` partition for verification. This library is 226intended to be used in both boot loaders and inside Android. It has a 227simple abstraction for system dependencies (see `avb_sysdeps.h`) as 228well as operations that the boot loader or OS is expected to implement 229(see `avb_ops.h`). The main entry point for verification is 230`avb_slot_verify()`. 231 232An optional extension `libavb_cert` additionally provides a scalable 233certificate-based authorization mechanism. The base `libavb` requires 234the device to implement public key validation manually (see 235`avb_validate_vbmeta_public_key()` in `avb_ops.h`), which can be 236complicated when working with anything other than a single hardcoded 237key. `libavb_cert` provides an implementation of this function which 238provides built-in support for features such as key rotation. 239 240`libavb_cert` was previously named `libavb_atx` (Android Things eXtension) but 241it has been renamed to better represent its usefulness as a general-purpose 242extension rather than anything specific to the Android Things project. 243 244## Files and Directories 245 246* `libavb/` 247 + An implementation of image verification. This code is designed 248 to be highly portable so it can be used in as many contexts as 249 possible. This code requires a C99-compliant C compiler. Part of 250 this code is considered internal to the implementation and 251 should not be used outside it. For example, this applies to the 252 `avb_rsa.[ch]` and `avb_sha.[ch]` files. System dependencies 253 expected to be provided by the platform is defined in 254 `avb_sysdeps.h`. If the platform provides the standard C runtime 255 `avb_sysdeps_posix.c` can be used. 256* `libavb_cert/` 257 + A libavb extension for certificate-based authorization. 258* `libavb_user/` 259 + Contains an `AvbOps` implementation suitable for use in Android 260 userspace. This is used in `boot_control.avb` and `avbctl`. 261* `libavb_ab/` 262 + An experimental A/B implementation for use in boot loaders and 263 AVB examples. **NOTE**: This code is *DEPRECATED* and you must 264 define `AVB_AB_I_UNDERSTAND_LIBAVB_AB_IS_DEPRECATED` to use 265 it. The code will be removed Jun 1 2018. 266* `boot_control/` 267 + An implementation of the Android `boot_control` HAL for use with 268 boot loaders using the experimental `libavb_ab` A/B stack. 269 **NOTE**: This code is *DEPRECATED* and will be removed Jun 1 270 2018. 271* `Android.bp` 272 + Build instructions for building `libavb` (a static library for use 273 on the device), host-side libraries (for unit tests), and unit 274 tests. 275* `avbtool` 276 + A tool written in Python for working with images related to 277 verified boot. 278* `test/` 279 + Unit tests for `abvtool`, `libavb`, `libavb_ab`, and 280 `libavb_cert`. 281* `tools/avbctl/` 282 + Contains the source-code for a tool that can be used to control 283 AVB at runtime in Android. 284* `examples/uefi/` 285 + Contains the source-code for a UEFI-based boot-loader utilizing 286 `libavb/` and `libavb_ab/`. 287* `examples/cert/` 288 + Contains example source-code for using the `avb_cert` extension 289* `README.md` 290 + This file. 291* `docs/` 292 + Contains documentation files. 293 294## Portability 295 296The `libavb` code is intended to be used in bootloaders in devices 297that will load Android or other operating systems. The suggested 298approach is to copy the appropriate header and C files mentioned in 299the previous section into the boot loader and integrate as 300appropriate. 301 302As the `libavb/` codebase will evolve over time integration should be 303as non-invasive as possible. The intention is to keep the API of the 304library stable however it will be broken if necessary. As for 305portability, the library is intended to be highly portable, work on 306both little- and big-endian architectures and 32- and 64-bit. It's 307also intended to work in non-standard environments without the 308standard C library and runtime. 309 310If the `AVB_ENABLE_DEBUG` preprocessor symbol is set, the code will 311include useful debug information and run-time checks. Production 312builds should not use this. The preprocessor symbol `AVB_COMPILATION` 313should be set only when compiling the libraries. The code must be 314compiled into a separate library. 315 316Applications using the compiled `libavb` library must only include the 317`libavb/libavb.h` file (which will include all public interfaces) and 318must not have the `AVB_COMPILATION` preprocessor symbol set. This is 319to ensure that internal code that may be change in the future (for 320example `avb_sha.[ch]` and `avb_rsa.[ch]`) will not be visible to 321application code. 322 323## Versioning and Compatibility 324 325AVB uses a version number with three fields - the major, minor, and 326sub version. Here's an example version number 327 328 1.4.3 329 ^ ^ ^ 330 | | | 331 the major version ---+ | | 332 the minor version -----+ | 333 the sub version -------+ 334 335The major version number is bumped only if compatibility is broken, 336e.g. a struct field has been removed or changed. The minor version 337number is bumped only if a new feature is introduced, for example a 338new algorithm or descriptor has been added. The sub version number is 339bumped when bugs are fixed or other changes not affecting 340compatibility are made. 341 342The `AvbVBMetaImageHeader` struct (as defined in the 343`avb_vbmeta_image.h`) carries the major and minor version number of 344`libavb` required to verify the struct in question. This is stored in 345the `required_libavb_version_major` and 346`required_libavb_version_minor` fields. Additionally this struct 347contains a textual field with the version of `avbtool` used to create 348the struct, for example "avbtool 1.4.3" or "avbtool 1.4.3 some_board 349Git-4589fbec". 350 351Note that it's entirely possible to have a `AvbVBMetaImageHeader` 352struct with 353 354 required_libavb_version_major = 1 355 required_libavb_version_minor = 0 356 avbtool_release_string = "avbtool 1.4.3" 357 358if, for example, creating an image that does not use any features 359added after AVB version 1.0. 360 361## Adding New Features 362 363If adding a new feature for example a new algorithm or a new 364descriptor then `AVB_VERSION_MINOR` in `avb_version.h` and `avbtool` 365must be bumped and `AVB_VERSION_SUB` should be set to zero. 366 367Unit tests **MUST** be added to check that 368 369* The feature is used if - and only if - suitable commands/options are 370 passed to `avbtool`. 371* The `required_version_minor` field is set to the bumped value if - 372 and only if - the feature is used. Also add tests to check that the 373 correct value is output when `--print_required_libavb_version` is 374 used. 375 376If `AVB_VERSION_MINOR` has already been bumped since the last release 377there is obviously no need to bump it again. 378 379## Using avbtool 380 381The content for the vbmeta partition can be generated as follows: 382 383 $ avbtool make_vbmeta_image \ 384 [--output OUTPUT] \ 385 [--algorithm ALGORITHM] [--key /path/to/key_used_for_signing_or_pub_key] \ 386 [--public_key_metadata /path/to/pkmd.bin] \ 387 [--rollback_index NUMBER] [--rollback_index_location NUMBER] \ 388 [--include_descriptors_from_image /path/to/image.bin] \ 389 [--setup_rootfs_from_kernel /path/to/image.bin] \ 390 [--chain_partition part_name:rollback_index_location:/path/to/key1.bin] \ 391 [--chain_partition_do_not_use_ab part_name:rollback_index_location:/path/to/key.bin] \ 392 [--signing_helper /path/to/external/signer] \ 393 [--signing_helper_with_files /path/to/external/signer_with_files] \ 394 [--print_required_libavb_version] \ 395 [--append_to_release_string STR] 396 397An integrity footer containing the hash for an entire partition can be 398added to an existing image as follows: 399 400 $ avbtool add_hash_footer \ 401 --partition_name PARTNAME --partition_size SIZE \ 402 [--image IMAGE] \ 403 [--algorithm ALGORITHM] [--key /path/to/key_used_for_signing_or_pub_key] \ 404 [--public_key_metadata /path/to/pkmd.bin] \ 405 [--rollback_index NUMBER] [--rollback_index_location NUMBER] \ 406 [--hash_algorithm HASH_ALG] [--salt HEX] \ 407 [--include_descriptors_from_image /path/to/image.bin] \ 408 [--setup_rootfs_from_kernel /path/to/image.bin] \ 409 [--output_vbmeta_image OUTPUT_IMAGE] [--do_not_append_vbmeta_image] \ 410 [--signing_helper /path/to/external/signer] \ 411 [--signing_helper_with_files /path/to/external/signer_with_files] \ 412 [--print_required_libavb_version] \ 413 [--append_to_release_string STR] \ 414 [--calc_max_image_size] \ 415 [--do_not_use_ab] \ 416 [--use_persistent_digest] 417 418Valid values for `HASH_ALG` above include `sha1` and `sha256`. 419 420An integrity footer containing the root digest and salt for a hashtree 421for a partition can be added to an existing image as follows. The 422hashtree is also appended to the image. 423 424 $ avbtool add_hashtree_footer \ 425 --partition_name PARTNAME --partition_size SIZE \ 426 [--image IMAGE] \ 427 [--algorithm ALGORITHM] [--key /path/to/key_used_for_signing_or_pub_key] \ 428 [--public_key_metadata /path/to/pkmd.bin] \ 429 [--rollback_index NUMBER] [--rollback_index_location NUMBER] \ 430 [--hash_algorithm HASH_ALG] [--salt HEX] [--block_size SIZE] \ 431 [--include_descriptors_from_image /path/to/image.bin] \ 432 [--setup_rootfs_from_kernel /path/to/image.bin] \ 433 [--setup_as_rootfs_from_kernel] \ 434 [--output_vbmeta_image OUTPUT_IMAGE] [--do_not_append_vbmeta_image] \ 435 [--do_not_generate_fec] [--fec_num_roots FEC_NUM_ROOTS] \ 436 [--signing_helper /path/to/external/signer] \ 437 [--signing_helper_with_files /path/to/external/signer_with_files] \ 438 [--print_required_libavb_version] \ 439 [--append_to_release_string STR] \ 440 [--calc_max_image_size] \ 441 [--do_not_use_ab] \ 442 [--no_hashtree] \ 443 [--use_persistent_digest] \ 444 [--check_at_most_once] 445 446Valid values for `HASH_ALG` above include `sha1`, `sha256`, and `blake2b-256`. 447 448The size of an image with integrity footers can be changed using the 449`resize_image` command: 450 451 $ avbtool resize_image \ 452 --image IMAGE \ 453 --partition_size SIZE 454 455The integrity footer on an image can be removed from an image. The 456hashtree can optionally be kept in place. 457 458 $ avbtool erase_footer --image IMAGE [--keep_hashtree] 459 460For hash- and hashtree-images the vbmeta struct can also be written to 461an external file via the `--output_vbmeta_image` option and one can 462also specify that the vbmeta struct and footer not be added to the 463image being operated on. 464 465The hashtree and FEC data in an image can be zeroed out with the following 466command: 467 468 $ avbtool zero_hashtree --image IMAGE 469 470This is useful for trading compressed image size for having to reculculate the 471hashtree and FEC at runtime. If this is done the hashtree and FEC data is set 472to zero except for the first eight bytes which are set to the magic 473`ZeRoHaSH`. Either the hashtree or FEC data or both may be zeroed this way 474so applications should check for the magic both places. Applications can 475use the magic to detect if recalculation is needed. 476 477To calculate the maximum size of an image that will fit in a partition 478of a given size after having used the `avbtool add_hash_footer` or 479`avbtool add_hashtree_footer` commands on it, use the 480`--calc_max_image_size` option: 481 482 $ avbtool add_hash_footer --partition_size $((10*1024*1024)) \ 483 --calc_max_image_size 484 10416128 485 486 $ avbtool add_hashtree_footer --partition_size $((10*1024*1024)) \ 487 --calc_max_image_size 488 10330112 489 490To calculate the required libavb version that would be put in the 491vbmeta struct when using `make_vbmeta_image`, `add_hash_footer`, and 492`add_hashtree_footer` commands use the 493`--print_required_libavb_version` option: 494 495 $ avbtool make_vbmeta_image \ 496 --algorithm SHA256_RSA2048 --key /path/to/key.pem \ 497 --include_descriptors_from_image /path/to/boot.img \ 498 --include_descriptors_from_image /path/to/system.img \ 499 --print_required_libavb_version 500 1.0 501 502Alternatively, `--no_hashtree` can be used with `avbtool add_hashtree_footer` 503command. If `--no_hashtree` is given, the hashtree blob is omitted and only 504its descriptor is added to the vbmeta struct. The descriptor says the size 505of hashtree is 0, which tells an application the need to recalculate 506hashtree. 507 508The `--signing_helper` option can be used in `make_vbmeta_image`, 509`add_hash_footer` and `add_hashtree_footer` commands to specify any 510external program for signing hashes. The data to sign (including 511padding e.g. PKCS1-v1.5) is fed via `STDIN` and the signed data is 512returned via `STDOUT`. If `--signing_helper` is present in a command 513line, the `--key` option need only contain a public key. Arguments for 514a signing helper are `algorithm` and `public key`. If the signing 515helper exits with a non-zero exit code, it means failure. 516 517Here's an example invocation: 518 519 /path/to/my_signing_program SHA256_RSA2048 /path/to/publickey.pem 520 521The `--signing_helper_with_files` is similar to `--signing_helper` 522except that a temporary file is used to communicate with the helper 523instead of `STDIN` and `STDOUT`. This is useful in situations where 524the signing helper is using code which is outputting diagnostics on 525`STDOUT` instead of `STDERR`. Here's an example invocation 526 527 /path/to/my_signing_program_with_files SHA256_RSA2048 \ 528 /path/to/publickey.pem /tmp/path/to/communication_file 529 530where the last positional argument is a file that contains the data to 531sign. The helper should write the signature in this file. 532 533The `append_vbmeta_image` command can be used to append an entire 534vbmeta blob to the end of another image. This is useful for cases when 535not using any vbmeta partitions, for example: 536 537 $ cp boot.img boot-with-vbmeta-appended.img 538 $ avbtool append_vbmeta_image \ 539 --image boot-with-vbmeta-appended.img \ 540 --partition_size SIZE_OF_BOOT_PARTITION \ 541 --vbmeta_image vbmeta.img 542 $ fastboot flash boot boot-with-vbmeta-appended.img 543 544Information about an image can be obtained using the `info_image` command. The 545output of this command should not be relied on and the way information is 546structured may change. 547 548The `verify_image` command can be used to verify the contents of 549several image files at the same time. When invoked on an image the 550following checks are performed: 551 552* If the image has a VBMeta struct the signature is checked against 553 the embedded public key. If the image doesn't look like `vbmeta.img` 554 then a footer is looked for and used if present. 555 556* If the option `--key` is passed then a `.pem` file is expected and 557 it's checked that the embedded public key in said VBMeta struct 558 matches the given key. 559 560* All descriptors in the VBMeta struct are checked in the following 561 way: 562 + For a hash descriptor the image file corresponding to the 563 partition name is loaded and its digest is checked against that 564 in the descriptor. 565 + For a hashtree descriptor the image file corresponding to the 566 partition name is loaded and the hashtree is calculated and its 567 root digest compared to that in the descriptor. 568 + For a chained partition descriptor its contents is compared 569 against content that needs to be passed in via the 570 `--expected_chain_partition` options. The format for this option 571 is similar to that of the `--chain_partition` option. If there 572 is no `--expected_chain_partition` descriptor for the chain 573 partition descriptor the check fails. 574 575Here's an example for a setup where the digests for `boot.img` and 576`system.img` are stored in `vbmeta.img` which is signed with 577`my_key.pem`. It also checks that the chain partition for partition 578`foobar` uses rollback index 8 and that the public key in AVB format 579matches that of the file `foobar_vendor_key.avbpubkey`: 580 581 $ avbtool verify_image \ 582 --image /path/to/vbmeta.img \ 583 --key my_key.pem \ 584 --expect_chained_partition foobar:8:foobar_vendor_key.avbpubkey 585 586 Verifying image /path/to/vbmeta.img using key at my_key.pem 587 vbmeta: Successfully verified SHA256_RSA4096 vbmeta struct in /path_to/vbmeta.img 588 boot: Successfully verified sha256 hash of /path/to/boot.img for image of 10543104 bytes 589 system: Successfully verified sha1 hashtree of /path/to/system.img for image of 1065213952 bytes 590 foobar: Successfully verified chain partition descriptor matches expected data 591 592In this example the `verify_image` command verifies the files 593`vbmeta.img`, `boot.img`, and `system.img` in the directory 594`/path/to`. The directory and file extension of the given image 595(e.g. `/path/to/vbmeta.img`) is used together with the partition name 596in the descriptor to calculate the filenames of the images holding 597hash and hashtree images. 598 599The `verify_image` command can also be used to check that a custom 600signing helper works as intended. 601 602The `calculate_vbmeta_digest` command can be used to calculate the vbmeta digest 603of several image files at the same time. The result is printed as a hexadecimal 604string either on `STDOUT` or a supplied path (using the `--output` option). 605 606 $ avbtool calculate_vbmeta_digest \ 607 --hash_algorithm sha256 \ 608 --image /path/to/vbmeta.img 609 a20fdd01a6638c55065fe08497186acde350d6797d59a55d70ffbcf41e95c2f5 610 611In this example the `calculate_vbmeta_digest` command loads the `vbmeta.img` 612file. If this image has one or more chain partition descriptors, the same logic 613as the `verify_image` command is used to load files for these (e.g. it assumes 614the same directory and file extension as the given image). Once all vbmeta 615structs have been loaded, the digest is calculated (using the hash algorithm 616given by the `--hash_algorithm` option) and printed out. 617 618To print hash and hashtree digests embedded in the verified metadata, use the 619`print_partition_digests` command like this: 620 621 $ avbtool print_partition_digests --image /path/to/vbmeta.img 622 system: ddaa513715fd2e22f3c1cea3c1a1f98ccb515fc6 623 boot: 5cba9a418e04b5f9e29ee6a250f6cdbe30c6cec867c59d388f141c3fedcb28c1 624 vendor: 06993a9e85e46e53d3892881bb75eff48ecadaa8 625 626For partitions with hash descriptors, this prints out the digest and for 627partitions with hashtree descriptors the root digest is printed out. Like the 628`calculate_vbmeta_digest` and `verify_image` commands, chain partitions are 629followed. To use JSON for the output, use the `--json` option. 630 631In case you would like to log all command lines for all avbtool invocations for 632debugging integrations with other tooling, you can configure the envirionment 633variable AVB_INVOCATION_LOGFILE with the name of the log file: 634 635 $ export AVB_INVOCATION_LOGFILE='/tmp/avb_invocation.log' 636 $ ./avbtool.py version 637 $ ./avbtool.py version 638 $ cat /tmp/avb_invocation.log 639 ./avbtool.py version 640 ./avbtool.py version 641 642 643## Build System Integration 644 645In Android, AVB is enabled by the `BOARD_AVB_ENABLE` variable 646 647 BOARD_AVB_ENABLE := true 648 649This will make the build system create `vbmeta.img` which will contain 650a hash descriptor for `boot.img`, a hashtree descriptor for 651`system.img`, a kernel-cmdline descriptor for setting up `dm-verity` 652for `system.img` and append a hash-tree to `system.img`. If the build 653system is set up such that one or many of `vendor.img` / `product.img` 654/ `system_ext.img` / `odm.img` are being built, the hash-tree for each 655of them will also be appended to the image respectively, and their 656hash-tree descriptors will be included into `vbmeta.img` accordingly. 657 658By default, the algorithm `SHA256_RSA4096` is used with a test key 659from the `external/avb/test/data` directory. This can be overriden by 660the `BOARD_AVB_ALGORITHM` and `BOARD_AVB_KEY_PATH` variables to use 661e.g. a 4096-bit RSA key and SHA-512: 662 663 BOARD_AVB_ALGORITHM := SHA512_RSA4096 664 BOARD_AVB_KEY_PATH := /path/to/rsa_key_4096bits.pem 665 666Remember that the public part of this key needs to be available to the 667bootloader of the device expected to verify resulting images. Use 668`avbtool extract_public_key` to extract the key in the expected format 669(`AVB_pk` in the following). If the device is using a different root 670of trust than `AVB_pk` the `--public_key_metadata` option can be used 671to embed a blob (`AVB_pkmd` in the following) that can be used to 672e.g. derive `AVB_pk`. Both `AVB_pk` and `AVB_pkmd` are passed to the 673`validate_vbmeta_public_key()` operation when verifying a slot. 674 675Some devices may support the end-user configuring the root of trust to use, see 676the [Device Specific Notes](#device-specific-notes) section for details. 677 678Devices can be configured to create additional `vbmeta` partitions as 679[chained partitions](#the-vbmeta-struct) in order to update a subset of 680partitions without changing the top-level `vbmeta` partition. For example, 681the following variables create `vbmeta_system.img` as a chained `vbmeta` 682image that contains the hash-tree descriptors for `system.img`, `system_ext.img` 683and `product.img`. `vbmeta_system.img` itself will be signed by the specified 684key and algorithm. 685 686 BOARD_AVB_VBMETA_SYSTEM := system system_ext product 687 BOARD_AVB_VBMETA_SYSTEM_KEY_PATH := external/avb/test/data/testkey_rsa2048.pem 688 BOARD_AVB_VBMETA_SYSTEM_ALGORITHM := SHA256_RSA2048 689 BOARD_AVB_VBMETA_SYSTEM_ROLLBACK_INDEX_LOCATION := 1 690 691Note that the hash-tree descriptors for `system.img`, `system_ext.img` and 692`product.img` will be included only in `vbmeta_system.img`, but not 693`vbmeta.img`. With the above setup, partitions `system.img`, `system_ext.img`, 694`product.img` and `vbmeta_system.img` can be updated independently - but as a 695group - of the rest of the partitions, *or* as part of the traditional updates 696that update all the partitions. 697 698Currently build system supports building chained `vbmeta` images of 699`vbmeta_system.img` (`BOARD_AVB_VBMETA_SYSTEM`) and `vbmeta_vendor.img` 700(`BOARD_AVB_VBMETA_VENDOR`). 701 702To prevent rollback attacks, the rollback index should be increased on 703a regular basis. The rollback index can be set with the 704`BOARD_AVB_ROLLBACK_INDEX` variable: 705 706 BOARD_AVB_ROLLBACK_INDEX := 5 707 708If this is not set, the rollback index defaults to 0. 709 710The variable `BOARD_AVB_MAKE_VBMETA_IMAGE_ARGS` can be used to specify 711additional options passed to `avbtool make_vbmeta_image`. Typical 712options to be used here include `--prop`, `--prop_from_file`, 713`--chain_partition`, `--public_key_metadata`, and `--signing_helper`. 714 715The variable `BOARD_AVB_BOOT_ADD_HASH_FOOTER_ARGS` can be used to 716specify additional options passed to `avbtool add_hash_footer` for 717`boot.img`. Typical options to be used here include `--hash_algorithm` 718and `--salt`. 719 720The variable `BOARD_AVB_SYSTEM_ADD_HASHTREE_FOOTER_ARGS` can be used 721to specify additional options passed to `avbtool add_hashtree_footer` 722for `system.img`. Typical options to be used here include 723`--hash_algorithm`, `--salt`, `--block_size`, and 724`--do_not_generate_fec`. 725 726The variable `BOARD_AVB_VENDOR_ADD_HASHTREE_FOOTER_ARGS` can be used 727to specify additional options passed to `avbtool add_hashtree_footer` 728for `vendor.img`. Typical options to be used here include 729`--hash_algorithm`, `--salt`, `--block_size`, and 730`--do_not_generate_fec`. 731 732The variable `BOARD_AVB_DTBO_ADD_HASH_FOOTER_ARGS` can be used to 733specify additional options passed to `avbtool add_hash_footer` for 734`dtbo.img`. Typical options to be used here include `--hash_algorithm` 735and `--salt`. 736 737Build system variables (such as `PRODUCT_SUPPORTS_VERITY_FEC`) used 738for previous version of Verified Boot in Android are not used in AVB. 739 740A/B related build system variables can be found [here](https://source.android.com/devices/tech/ota/ab_updates#build-variables). 741 742# Device Integration 743 744This section discusses recommendations and best practices for 745integrating `libavb` with a device boot loader. It's important to 746emphasize that these are just recommendations so the use of the word 747`must` should be taken lightly. 748 749Additionally term *HLOS* is used in this chapter to refer to the *High 750Level Operating System*. This obviously includes Android (including 751other form-factors than phones) but could also be other operating 752systems. 753 754## System Dependencies 755 756The `libavb` library is written in a way so it's portable to any 757system with a C99 compiler. It does not require the standard C library 758however the boot loader must implement a simple set of system 759primitives required by `libavb` such as `avb_malloc()`, `avb_free()`, 760and `avb_print()`. 761 762In addition to the system primitives, `libavb` interfaces with the boot 763loader through the supplied `AvbOps` struct. This includes operations 764to read and write data from partitions, read and write rollback 765indexes, check if the public key used to make a signature should be 766accepted, and so on. 767 768## Locked and Unlocked mode 769 770AVB has been designed to support the notion of the device being either 771LOCKED state or UNLOCKED state as used in Android. 772 773In the context of AVB, the LOCKED state means that verification errors 774are fatal whereas in UNLOCKED state they are not. If the device is 775UNLOCKED pass `AVB_SLOT_VERIFY_FLAGS_ALLOW_VERIFICATION_ERROR` flag in 776the `flags` parameter of `avb_slot_verify()` and treat verification 777errors including 778 779* `AVB_SLOT_VERIFY_RESULT_ERROR_PUBLIC_KEY_REJECTED` 780* `AVB_SLOT_VERIFY_RESULT_ERROR_VERIFICATION` 781* `AVB_SLOT_VERIFY_RESULT_ERROR_ROLLBACK_INDEX` 782 783as non-fatal. If the device is in the LOCKED state, don't pass the 784`AVB_SLOT_VERIFY_FLAGS_ALLOW_VERIFICATION_ERROR` flag in the `flags` 785parameter of `avb_slot_verify()` and only treat 786`AVB_SLOT_VERIFY_RESULT_OK` as non-fatal. 787 788On Android, device state may be altered through the fastboot interface 789using, e.g. `fastboot flashing lock` (to transition to the LOCKED 790state) and `fastboot flashing unlock` (to transition to the UNLOCKED 791state). 792 793The device must only allow state transitions (e.g. from LOCKED to 794UNLOCKED or UNLOCKED to LOCKED) after asserting physical presence of 795the user. If the device has a display and buttons this is typically 796done by showing a dialog and requiring the user to confirm or cancel 797using physical buttons. 798 799All user data must be cleared when transitioning from the LOCKED to 800the UNLOCKED state (including the `userdata` partition and any NVRAM 801spaces). Additionally all `stored_rollback_index[n]` locations must be 802cleared (all elements must be set to zero). Similar action (erasing 803`userdata`, NVRAM spaces, and `stored_rollback_index[n]` locations) 804shall also happening when transitioning from UNLOCKED to LOCKED. If 805the device is required to use full disk encryption, then a less 806intensive wipe is required for UNLOCKED to LOCKED. Depending on the 807device form-factor and intended use, the user should be prompted to 808confirm before any data is erased. 809 810## Tamper-evident Storage 811 812In this document, *tamper-evident* means that it's possible to detect 813if the HLOS has tampered with the data, e.g. if it has been 814overwritten. 815 816Tamper-evident storage must be used for stored rollback indexes, keys 817used for verification, device state (whether the device is LOCKED or 818UNLOCKED), and named persistent values. If tampering has been detected 819the corresponding `AvbOps` operation should fail by e.g. returning 820`AVB_IO_RESULT_ERROR_IO`. It is especially important that verification 821keys cannot be tampered with since they represent the root-of-trust. 822 823If verification keys are mutable they must only be set by the end 824user, e.g. it must never be set at the factory or store or any 825intermediate point before the end user. Additionally, it must only be 826possible to set or clear a key while the device is in the UNLOCKED 827state. 828 829## Named Persistent Values 830 831AVB 1.1 introduces support for named persistent values which must be 832tamper evident and allows AVB to store arbitrary key-value pairs. 833Integrators may limit support for these values to a set of fixed 834well-known names, a maximum value size, and / or a maximum number of 835values. 836 837## Persistent Digests 838 839Using a persistent digest for a partition means the digest (or root 840digest in the case of a hashtree) is not stored in the descriptor but 841is stored in a named persistent value. This allows configuration data 842which may differ from device to device to be verified by AVB. It must 843not be possible to modify the persistent digest when the device is in 844the LOCKED state, except if a digest does not exist it may be initialized. 845 846To specify that a descriptor should use a persistent digest, use the 847`--use_persistent_digest` option for the `add_hash_footer` or 848`add_hashtree_footer` avbtool operations. Then, during verification of 849the descriptor, AVB will look for the digest in the named persistent 850value `avb.persistent_digest.$(partition_name)` instead of in the 851descriptor itself. 852 853For hashtree descriptors using a persistent digest, the digest value 854will be available for substitution into kernel command line descriptors 855using a token of the form `$(AVB_FOO_ROOT_DIGEST)` where 'FOO' is the 856uppercase partition name, in this case for the partition named 'foo'. 857The token will be replaced by the digest in hexadecimal form. 858 859By default, when the `--use_persistent_digest` option is used with 860`add_hash_footer` or `add_hashtree_footer`, avbtool will generate a 861descriptor with no salt rather than the typical default of generating a 862random salt equal to the digest length. This is because the digest 863value is stored in persistent storage and thus cannot change over time. 864An alternative option would be to manually provide a random salt using 865`--salt`, but this salt would need to remain unchanged for the life 866of the device once the persistent digest value was written. 867 868## Updating Stored Rollback Indexes 869 870In order for Rollback Protection to work the bootloader will need to 871update the `stored_rollback_indexes[n]` array on the device prior to 872transferring control to the HLOS. If not using A/B this is 873straightforward - just update it to what's in the AVB metadata for the 874slot before booting. In pseudo-code it would look like this: 875 876```c++ 877// The |slot_data| parameter should be the AvbSlotVerifyData returned 878// by avb_slot_verify() for the slot we're about to boot. 879// 880bool update_stored_rollback_indexes_for_slot(AvbOps* ops, 881 AvbSlotVerifyData* slot_data) { 882 for (int n = 0; n < AVB_MAX_NUMBER_OF_ROLLBACK_INDEX_LOCATIONS; n++) { 883 uint64_t rollback_index = slot_data->rollback_indexes[n]; 884 if (rollback_index > 0) { 885 AvbIOResult io_ret; 886 uint64_t current_stored_rollback_index; 887 888 io_ret = ops->read_rollback_index(ops, n, ¤t_stored_rollback_index); 889 if (io_ret != AVB_IO_RESULT_OK) { 890 return false; 891 } 892 893 if (rollback_index > current_stored_rollback_index) { 894 io_ret = ops->write_rollback_index(ops, n, rollback_index); 895 if (io_ret != AVB_IO_RESULT_OK) { 896 return false; 897 } 898 } 899 } 900 } 901 return true; 902} 903``` 904 905However if using A/B more care must be taken to still allow the device 906to fall back to the old slot if the update didn't work. 907 908For an HLOS like Android where rollback is only supported if the 909updated OS version is found to not work, `stored_rollback_index[n]` 910should only be updated from slots that are marked as SUCCESSFUL in the 911A/B metadata. The pseudo-code for that is as follows where 912`is_slot_is_marked_as_successful()` comes from the A/B stack in use: 913 914```c++ 915if (is_slot_is_marked_as_successful(slot->ab_suffix)) { 916 if (!update_stored_rollback_indexes_for_slot(ops, slot)) { 917 // TODO: handle error. 918 } 919} 920``` 921 922This logic should ideally be implemented outside of the HLOS. One 923possible implementation is to update rollback indices in the 924bootloader when booting into a successful slot. This means that 925when booting into a new OS not yet marked as successful, the 926rollback indices would not be updated. The first reboot after the 927slot succeeded would trigger an update of the rollback indices. 928 929For an HLOS where it's possible to roll back to a previous version, 930`stored_rollback_index[n]` should be set to the largest possible value 931allowing all bootable slots to boot. This approach is implemented in 932AVB's experimental (and now deprecated) A/B stack `libavb_ab`, see the 933`avb_ab_flow()` implementation. Note that this requires verifying 934*all* bootable slots at every boot and this may impact boot time. 935 936## Recommended Bootflow 937 938The recommended boot flow for a device using AVB is as follows: 939 940 941 942Notes: 943 944* The device is expected to search through all A/B slots until it 945 finds a valid OS to boot. Slots that are rejected in the LOCKED 946 state might not be rejected in the UNLOCKED state, (e.g. when 947 UNLOCKED any key can be used and rollback index failures are 948 allowed), so the algorithm used for selecting a slot varies 949 depending on what state the device is in. 950 951* If no valid OS (that is, no bootable A/B slot) can be found, the 952 device cannot boot and has to enter repair mode. It is 953 device-dependent what this looks like. If the device has a screen 954 it must convey this state to the user. 955 956* If the device is LOCKED, only an OS signed by an embedded 957 verification key (see the previous section) shall be 958 accepted. Additionally, `rollback_index[n]` as stored in the 959 verified image must be greater or equal than what's in 960 `stored_rollback_index[n]` on the device (for all `n`) and the 961 `stored_rollback_index[n]` array is expected to be updated as 962 specified in the previous section. 963 + If the key used for verification was set by the end user, and 964 the device has a screen, it must show a warning with the key 965 fingerprint to convey that the device is booting a custom 966 OS. The warning must be shown for at least 10 seconds before the 967 boot process continues. If the device does not have a screen, 968 other ways must be used to convey that the device is booting a 969 custom OS (lightbars, LEDs, etc.). 970 971* If the device is UNLOCKED, there is no requirement to check the key 972 used to sign the OS nor is there any requirement to check or update 973 rollback `stored_rollback_index[n]` on the device. Because of this 974 the user must always be shown a warning about verification not 975 occurring. 976 + It is device-dependent how this is implemented since it depends 977 on the device form-factor and intended usage. If the device has 978 a screen and buttons (for example if it's a phone) the warning 979 is to be shown for at least 10 seconds before the boot process 980 continues. If the device does not have a screen, other ways must 981 be used to convey that the device is UNLOCKED (lightbars, LEDs, 982 etc.). 983 984### Booting Into Recovery 985 986On Android devices not using A/B, the `recovery` partition usually isn't 987updated along with other partitions and therefore can't be referenced 988from the main `vbmeta` partition. 989 990It's still possible to use AVB to protect this partition (and others) 991by signing these partitions and passing the 992`AVB_SLOT_VERIFY_FLAGS_NO_VBMETA_PARTITION` flag to `avb_slot_verify()`. 993In this mode, the key used to sign each requested partition is verified 994by the `validate_public_key_for_partition()` operation which is also 995used to return the rollback index location to be used. 996 997## Handling dm-verity Errors 998 999By design, hashtree verification errors are detected by the HLOS and 1000not the bootloader. AVB provides a way to specify how the error should 1001be handled through the `hashtree_error_mode` parameter in the 1002`avb_slot_verify()` function. Possible values include 1003 1004* `AVB_HASHTREE_ERROR_MODE_RESTART_AND_INVALIDATE` means that the HLOS 1005 will invalidate the current slot and restart. On devices with A/B 1006 this would lead to attempting to boot the other slot (if it's marked 1007 as bootable) or it could lead to a mode where no OS can be booted 1008 (e.g. some form of repair mode). In Linux this requires a kernel 1009 built with `CONFIG_DM_VERITY_AVB`. 1010 1011* `AVB_HASHTREE_ERROR_MODE_RESTART` means that the OS will restart 1012 without the current slot being invalidated. Be careful using this 1013 mode unconditionally as it may introduce boot loops if the same 1014 hashtree verification error is hit on every boot. 1015 1016* `AVB_HASHTREE_ERROR_MODE_EIO` means that an `EIO` error will be 1017 returned to the application. 1018 1019* `AVB_HASHTREE_ERROR_MODE_MANAGED_RESTART_AND_EIO` means that either the **RESTART** 1020 or **EIO** mode is used, depending on state. This mode implements a state 1021 machine whereby **RESTART** is used by default and when the 1022 `AVB_SLOT_VERIFY_FLAGS_RESTART_CAUSED_BY_HASHTREE_CORRUPTION` is passed to 1023 `avb_slot_verify()` the mode transitions to **EIO**. When a new OS has been 1024 detected the device transitions back to the **RESTART** mode. 1025 + To do this persistent storage is needed - specifically this means that the 1026 passed in `AvbOps` will need to have the `read_persistent_value()` and 1027 `write_persistent_value()` operations implemented. The name of the 1028 persistent value used is **avb.managed_verity_mode** and 32 bytes of storage 1029 is needed. 1030 1031* `AVB_HASHTREE_ERROR_MODE_LOGGING` means that errors will be logged 1032 and corrupt data may be returned to applications. This mode should 1033 be used for **ONLY** diagnostics and debugging. It cannot be used 1034 unless verification errors are allowed. 1035 1036* `AVB_HASHTREE_ERROR_MODE_PANIC` means that the OS will **panic** without 1037 the current slot being invalidated. Be careful using this mode as it may 1038 introduce boot panic if the same hashtree verification error is hit on 1039 every boot. This mode is available since: 1.7.0 (kernel 5.9) 1040 1041The value passed in `hashtree_error_mode` is essentially just passed on through 1042to the HLOS through the the `androidboot.veritymode`, 1043`androidboot.veritymode.managed`, and `androidboot.vbmeta.invalidate_on_error` 1044kernel command-line parameters in the following way: 1045 1046| | `androidboot.veritymode` | `androidboot.veritymode.managed` | `androidboot.vbmeta.invalidate_on_error` | 1047|------|:------------------------:|:--------------------------------:|:----------------------------------------:| 1048| `AVB_HASHTREE_ERROR_MODE_RESTART_AND_INVALIDATE` | **enforcing** | (unset) | **yes** | 1049| `AVB_HASHTREE_ERROR_MODE_RESTART` | **enforcing** | (unset) | (unset) | 1050| `AVB_HASHTREE_ERROR_MODE_EIO` | **eio** | (unset) | (unset) | 1051| `AVB_HASHTREE_ERROR_MODE_MANAGED_RESTART_AND_EIO` | **eio** or **enforcing** | **yes** | (unset) | 1052| `AVB_HASHTREE_ERROR_MODE_LOGGING` | **ignore_corruption** | (unset) | (unset) | 1053| `AVB_HASHTREE_ERROR_MODE_PANIC` | **panicking** | (unset) | (unset) | 1054 1055The only exception to this table is that if the 1056`AVB_VBMETA_IMAGE_FLAGS_HASHTREE_DISABLED` flag is set in the top-level vbmeta, 1057then `androidboot.veritymode` is set to **disabled** and 1058`androidboot.veritymode.managed` and `androidboot.vbmeta.invalidate_on_error` 1059are unset. 1060 1061The different values of `hashtree_error_mode` parameter in the `avb_slot_verify()` 1062function can be categorized into three groups: 1063 1064* `AVB_HASHTREE_ERROR_MODE_RESTART_AND_INVALIDATE`, which needs `CONFIG_DM_VERITY_AVB` 1065 in the kernel config for the kernel to invalidate the current slot and 1066 restart. This is kept here for legacy Android Things devices and is not 1067 recommended for other device form factors. 1068 1069* The bootloader handles the switch between `AVB_HASHTREE_ERROR_MODE_RESTART` 1070 and `AVB_HASHTREE_ERROR_MODE_EIO`. This would need a persistent storage on the 1071 device to store the vbmeta digest, so the bootloader can detect if a device 1072 ever gets an update or not. Once the new OS is installed and if the device is 1073 in **EIO** mode, the bootloader should switch back to **RESTART** mode. 1074 1075* `AVB_HASHTREE_ERROR_MODE_MANAGED_RESTART_AND_EIO`: `libavb` helps the 1076 bootloader manage **EIO**/**RESTART** state transition. The bootloader needs 1077 to implement the callbacks of `AvbOps->read_persistent_value()` and 1078 `AvbOps->write_persistent_value()` for `libavb` to store the vbmeta digest to 1079 detect whether a new OS is installed. 1080 1081### Which mode should I use for my device? 1082 1083This depends entirely on the device, how the device is intended to be 1084used, and the desired user experience. 1085 1086For Android devices the `AVB_HASHTREE_ERROR_MODE_MANAGED_RESTART_AND_EIO` mode 1087should be used. Also see the [Boot Flow section on source.android.com](https://source.android.com/security/verifiedboot/boot-flow) for the kind of UX and UI the boot loader should implement. 1088 1089If the device doesn't have a screen or if the HLOS supports multiple bootable 1090slots simultaneously it may make more sense to just use 1091`AVB_HASHTREE_ERROR_MODE_RESTART_AND_INVALIDATE`. 1092 1093## Android Specific Integration 1094 1095On Android, the boot loader must set the 1096`androidboot.verifiedbootstate` parameter on the kernel command-line 1097to indicate the boot state. It shall use the following values: 1098 1099* **green**: If in LOCKED state and the key used for verification was not set by the end user. 1100* **yellow**: If in LOCKED state and the key used for verification was set by the end user. 1101* **orange**: If in the UNLOCKED state. 1102 1103## GKI 2.0 Integration 1104 1105Starting from Android 12, devices launching with kernel version 5.10 or higher 1106must ship with the GKI kernel. See [GKI 2.0](https://source.android.com/devices/architecture/kernel/generic-kernel-image#gki2) 1107for details. 1108 1109While incorporating a certified GKI `boot.img` into a device codebase, the 1110following board variables should be configured. The setting shown below is just 1111an example to be adjusted per device. 1112 1113``` 1114# Uses a prebuilt boot.img 1115TARGET_NO_KERNEL := true 1116BOARD_PREBUILT_BOOTIMAGE := device/${company}/${board}/boot.img 1117 1118# Enables chained vbmeta for the boot.img so it can be updated independently, 1119# without updating the vbmeta.img. The following configs are optional. 1120# When they're absent, the hash of the boot.img will be stored then signed in 1121# the vbmeta.img. 1122BOARD_AVB_BOOT_KEY_PATH := external/avb/test/data/testkey_rsa4096.pem 1123BOARD_AVB_BOOT_ALGORITHM := SHA256_RSA4096 1124BOARD_AVB_BOOT_ROLLBACK_INDEX := $(PLATFORM_SECURITY_PATCH_TIMESTAMP) 1125BOARD_AVB_BOOT_ROLLBACK_INDEX_LOCATION := 2 1126``` 1127 1128**NOTE**: The certified GKI `boot.img` isn't signed for verified boot. 1129A device-specific verified boot chain should still be configured for a prebuilt 1130GKI `boot.img`. 1131 1132## Device Specific Notes 1133 1134This section contains information about how AVB is integrated into specific 1135devices. This is not an exhaustive list. 1136 1137### Pixel 2 and later 1138 1139On the Pixel 2, Pixel 2 XL and later Pixel models, the boot loader supports a 1140virtual partition with the name `avb_custom_key`. Flashing and erasing this 1141partition only works in the UNLOCKED state. Setting the custom key is done like 1142this: 1143 1144 avbtool extract_public_key --key key.pem --output pkmd.bin 1145 fastboot flash avb_custom_key pkmd.bin 1146 1147Erasing the key is done by erasing the virtual partition: 1148 1149 fastboot erase avb_custom_key 1150 1151When the custom key is set and the device is in the LOCKED state it will boot 1152images signed with both the built-in key as well as the custom key. All other 1153security features (including rollback-protection) are in effect, e.g. the 1154**only** difference is the root of trust to use. 1155 1156When booting an image signed with a custom key, a yellow screen will be shown as 1157part of the boot process to remind the user that the custom key is in use. 1158 1159# Version History 1160 1161### Version 1.3 1162Version 1.3 adds support for the following: 1163* A 32-bit `flags` element is added to a chain descriptor. 1164* Support for chain partitions which don't use [A/B](#a_b-support). 1165 1166### Version 1.2 1167 1168Version 1.2 adds support for the following: 1169* `rollback_index_location` field of the main vbmeta header. 1170* `check_at_most_once` parameter of dm-verity in a hashtree descriptor. 1171 1172### Version 1.1 1173 1174Version 1.1 adds support for the following: 1175 1176* A 32-bit `flags` element is added to hash and hashtree descriptors. 1177* Support for partitions which don't use [A/B](#a_b-support). 1178* Tamper-evident [named persistent values](#named-persistent-values). 1179* [Persistent digests](#persistent-digests) for hash or hashtree descriptors. 1180 1181### Version 1.0 1182 1183All features not explicitly listed under a later version are supported by 1.0. 1184
