1 # Android Verified Boot 2.0 2 --- 3 4 This repository contains tools and libraries for working with Android 5 Verified 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 * [Tools and Libraries](#Tools-and-Libraries) 14 + [avbtool and libavb](#avbtool-and-libavb) 15 + [Files and Directories](#Files-and-Directories) 16 + [Portability](#Portability) 17 + [Versioning and Compatibility](#Versioning-and-Compatibility) 18 + [Adding New Features](#Adding-New-Features) 19 + [Using avbtool](#Using-avbtool) 20 + [Build System Integration](#Build-System-Integration) 21 * [Device Integration](#Device-Integration) 22 + [System Dependencies](#System-Dependencies) 23 + [Locked and Unlocked mode](#Locked-and-Unlocked-mode) 24 + [Tamper-evident Storage](#Tamper_evident-Storage) 25 + [Named Persistent Values](#Named-Persistent-Values) 26 + [Persistent Digests](#Persistent-Digests) 27 + [Updating Stored Rollback Indexes](#Updating-Stored-Rollback-Indexes) 28 + [Recommended Bootflow](#Recommended-Bootflow) 29 + [Handling dm-verity Errors](#Handling-dm_verity-Errors) 30 + [Android Specific Integration](#Android-Specific-Integration) 31 + [Device Specific Notes](#Device-Specific-Notes) 32 * [Version History](#Version-History) 33 34 # What is it? 35 36 Verified boot is the process of assuring the end user of the integrity 37 of the software running on a device. It typically starts with a 38 read-only portion of the device firmware which loads code and executes 39 it only after cryptographically verifying that the code is authentic 40 and doesn't have any known security flaws. AVB is one implementation 41 of verified boot. 42 43 ## The VBMeta struct 44 45 The central data structure used in AVB is the VBMeta struct. This data 46 structure contains a number of descriptors (and other metadata) and 47 all of this data is cryptographically signed. Descriptors are used for 48 image hashes, image hashtree metadata, and so-called *chained 49 partitions*. A simple example is the following: 50 51 ![AVB with boot, system, and vendor](docs/avb-integrity-data-in-vbmeta.png) 52 53 where the `vbmeta` partition holds the hash for the `boot` partition 54 in a hash descriptor. For the `system` and `vendor` partitions a 55 hashtree follows the filesystem data and the `vbmeta` partition holds 56 the root hash, salt, and offset of the hashtree in hashtree 57 descriptors. Because the VBMeta struct in the `vbmeta` partition is 58 cryptographically signed, the boot loader can check the signature and 59 verify it was made by the owner of `key0` (by e.g. embedding the 60 public part of `key0`) and thereby trust the hashes used for `boot`, 61 `system`, and `vendor`. 62 63 A chained partition descriptor is used to delegate authority - it 64 contains the name of the partition where authority is delegated as 65 well as the public key that is trusted for signatures on this 66 particular partition. As an example, consider the following setup: 67 68 ![AVB with a chained partition](docs/avb-chained-partition.png) 69 70 In this setup the `xyz` partition has a hashtree for 71 integrity-checking. Following the hashtree is a VBMeta struct which 72 contains the hashtree descriptor with hashtree metadata (root hash, 73 salt, offset, etc.) and this struct is signed with `key1`. Finally, at 74 the end of the partition is a footer which has the offset of the 75 VBMeta struct. 76 77 This setup allows the bootloader to use the chain partition descriptor 78 to find the footer at the end of the partition (using the name in the 79 chain partition descriptor) which in turns helps locate the VBMeta 80 struct and verify that it was signed by `key1` (using `key1_pub` stored in the 81 chain partition descriptor). Crucially, because there's a footer with 82 the offset, the `xyz` partition can be updated without the `vbmeta` 83 partition needing any changes. 84 85 The VBMeta struct is flexible enough to allow hash descriptors and 86 hashtree descriptors for any partition to live in either the `vbmeta` 87 partition or - via a chain partition descriptor - in the partition 88 that they are used to integrity check. This allows for a wide range of 89 organizational and trust relationships. 90 91 ## Rollback Protection 92 93 AVB includes Rollback Protection which is used to protect against 94 known security flaws. Each VBMeta struct has a *rollback index* baked 95 into it like the following: 96 97 ![AVB rollback indexes](docs/avb-rollback-indexes.png) 98 99 These numbers are referred to as `rollback_index[n]` and are increased 100 for each image as security flaws are discovered and 101 fixed. Additionally the device stores the last seen rollback index in 102 tamper-evident storage: 103 104 ![AVB stored rollback indexes](docs/avb-stored-rollback-indexes.png) 105 106 and these are referred to as `stored_rollback_index[n]`. 107 108 Rollback protection is having the device reject an image unless 109 `rollback_index[n]` >= `stored_rollback_index[n]` for all `n`, and 110 having the device increase `stored_rollback_index[n]` over 111 time. Exactly how this is done is discussed in 112 the 113 [Updating Stored Rollback Indexes](#Updating-Stored-Rollback-Indexes) 114 section. 115 116 ## A/B Support 117 118 AVB has been designed to work with A/B by requiring that the A/B 119 suffix is never used in any partition names stored in 120 descriptors. Here's an example with two slots: 121 122 ![AVB with A/B partitions](docs/avb-ab-partitions.png) 123 124 Note how the rollback indexes differ between slots - for slot A the 125 rollback indexes are `[42, 101]` and for slot B they are `[43, 103]`. 126 127 In version 1.1 or later, avbtool supports `--do_not_use_ab` for 128 `add_hash_footer` and `add_hashtree_footer` operations. This makes it 129 possible to work with a partition that does not use A/B and should 130 never have the prefix. This corresponds to the 131 `AVB_HASH[TREE]_DESCRIPTOR_FLAGS_DO_NOT_USE_AB` flags. 132 133 # Tools and Libraries 134 135 This section contains information about the tools and libraries 136 included in AVB. 137 138 ## avbtool and libavb 139 140 The main job of `avbtool` is to create `vbmeta.img` which is the 141 top-level object for verified boot. This image is designed to go into 142 the `vbmeta` partition (or, if using A/B, the slot in question 143 e.g. `vbmeta_a` or `vbmeta_b`) and be of minimal size (for out-of-band 144 updates). The vbmeta image is cryptographically signed and contains 145 verification data (e.g. cryptographic digests) for verifying 146 `boot.img`, `system.img`, and other partitions/images. 147 148 The vbmeta image can also contain references to other partitions where 149 verification data is stored as well as a public key indicating who 150 should sign the verification data. This indirection provides 151 delegation, that is, it allows a 3rd party to control content on a 152 given partition by including their public key in `vbmeta.img`. By 153 design, this authority can be easily revoked by simply updating 154 `vbmeta.img` with new descriptors for the partition in question. 155 156 Storing signed verification data on other images - for example 157 `boot.img` and `system.img` - is also done with `avbtool`. 158 159 In addition to `avbtool`, a library - `libavb` - is provided. This 160 library performs all verification on the device side e.g. it starts by 161 loading the `vbmeta` partition, checks the signature, and then goes on 162 to load the `boot` partition for verification. This library is 163 intended to be used in both boot loaders and inside Android. It has a 164 simple abstraction for system dependencies (see `avb_sysdeps.h`) as 165 well as operations that the boot loader or OS is expected to implement 166 (see `avb_ops.h`). The main entry point for verification is 167 `avb_slot_verify()`. 168 169 Android Things has specific requirements and validation logic for the 170 vbmeta public key. An extension is provided in `libavb_atx` which 171 performs this validation as an implementation of `libavb`'s public key 172 validation operation (see `avb_validate_vbmeta_public_key()` in 173 `avb_ops.h`). 174 175 ## Files and Directories 176 177 * `libavb/` 178 + An implementation of image verification. This code is designed 179 to be highly portable so it can be used in as many contexts as 180 possible. This code requires a C99-compliant C compiler. Part of 181 this code is considered internal to the implementation and 182 should not be used outside it. For example, this applies to the 183 `avb_rsa.[ch]` and `avb_sha.[ch]` files. System dependencies 184 expected to be provided by the platform is defined in 185 `avb_sysdeps.h`. If the platform provides the standard C runtime 186 `avb_sysdeps_posix.c` can be used. 187 * `libavb_atx/` 188 + An Android Things Extension for validating public key metadata. 189 * `libavb_user/` 190 + Contains an `AvbOps` implementation suitable for use in Android 191 userspace. This is used in `boot_control.avb` and `avbctl`. 192 * `libavb_ab/` 193 + An experimental A/B implementation for use in boot loaders and 194 AVB examples. **NOTE**: This code is *DEPRECATED* and you must 195 define `AVB_AB_I_UNDERSTAND_LIBAVB_AB_IS_DEPRECATED` to use 196 it. The code will be removed Jun 1 2018. 197 * `boot_control/` 198 + An implementation of the Android `boot_control` HAL for use with 199 boot loaders using the experimental `libavb_ab` A/B stack. 200 **NOTE**: This code is *DEPRECATED* and will be removed Jun 1 201 2018. 202 * `contrib/` 203 + Contains patches needed in other projects for interoperability with AVB. 204 For example, `contrib/linux/4.4` has the patches for Linux kernel 4.4, 205 which are generated by `git format-patch`. 206 * `Android.bp` 207 + Build instructions for building `libavb` (a static library for use 208 on the device), host-side libraries (for unit tests), and unit 209 tests. 210 * `avbtool` 211 + A tool written in Python for working with images related to 212 verified boot. 213 * `test/` 214 + Unit tests for `abvtool`, `libavb`, `libavb_ab`, and 215 `libavb_atx`. 216 * `tools/avbctl/` 217 + Contains the source-code for a tool that can be used to control 218 AVB at runtime in Android. 219 * `examples/uefi/` 220 + Contains the source-code for a UEFI-based boot-loader utilizing 221 `libavb/` and `libavb_ab/`. 222 * `examples/things/` 223 + Contains the source-code for a slot verification suitable for Android 224 Things. 225 * `README.md` 226 + This file. 227 * `docs/` 228 + Contains documentation files. 229 230 ## Portability 231 232 The `libavb` code is intended to be used in bootloaders in devices 233 that will load Android or other operating systems. The suggested 234 approach is to copy the appropriate header and C files mentioned in 235 the previous section into the boot loader and integrate as 236 appropriate. 237 238 As the `libavb/` codebase will evolve over time integration should be 239 as non-invasive as possible. The intention is to keep the API of the 240 library stable however it will be broken if necessary. As for 241 portability, the library is intended to be highly portable, work on 242 both little- and big-endian architectures and 32- and 64-bit. It's 243 also intended to work in non-standard environments without the 244 standard C library and runtime. 245 246 If the `AVB_ENABLE_DEBUG` preprocessor symbol is set, the code will 247 include useful debug information and run-time checks. Production 248 builds should not use this. The preprocessor symbol `AVB_COMPILATION` 249 should be set only when compiling the libraries. The code must be 250 compiled into a separate library. 251 252 Applications using the compiled `libavb` library must only include the 253 `libavb/libavb.h` file (which will include all public interfaces) and 254 must not have the `AVB_COMPILATION` preprocessor symbol set. This is 255 to ensure that internal code that may be change in the future (for 256 example `avb_sha.[ch]` and `avb_rsa.[ch]`) will not be visible to 257 application code. 258 259 ## Versioning and Compatibility 260 261 AVB uses a version number with three fields - the major, minor, and 262 sub version. Here's an example version number 263 264 1.4.3 265 ^ ^ ^ 266 | | | 267 the major version ---+ | | 268 the minor version -----+ | 269 the sub version -------+ 270 271 The major version number is bumped only if compatibility is broken, 272 e.g. a struct field has been removed or changed. The minor version 273 number is bumped only if a new feature is introduced, for example a 274 new algorithm or descriptor has been added. The sub version number is 275 bumped when bugs are fixed or other changes not affecting 276 compatibility are made. 277 278 The `AvbVBMetaImageHeader` struct (as defined in the 279 `avb_vbmeta_image.h`) carries the major and minor version number of 280 `libavb` required to verify the struct in question. This is stored in 281 the `required_libavb_version_major` and 282 `required_libavb_version_minor` fields. Additionally this struct 283 contains a textual field with the version of `avbtool` used to create 284 the struct, for example "avbtool 1.4.3" or "avbtool 1.4.3 some_board 285 Git-4589fbec". 286 287 Note that it's entirely possible to have a `AvbVBMetaImageHeader` 288 struct with 289 290 required_libavb_version_major = 1 291 required_libavb_version_minor = 0 292 avbtool_release_string = "avbtool 1.4.3" 293 294 if, for example, creating an image that does not use any features 295 added after AVB version 1.0. 296 297 ## Adding New Features 298 299 If adding a new feature for example a new algorithm or a new 300 descriptor then `AVB_VERSION_MINOR` in `avb_version.h` and `avbtool` 301 must be bumped and `AVB_VERSION_SUB` should be set to zero. 302 303 Unit tests **MUST** be added to check that 304 305 * The feature is used if - and only if - suitable commands/options are 306 passed to `avbtool`. 307 * The `required_version_minor` field is set to the bumped value if - 308 and only if - the feature is used. Also add tests to check that the 309 correct value is output when `--print_required_libavb_version` is 310 used. 311 312 If `AVB_VERSION_MINOR` has already been bumped since the last release 313 there is obviously no need to bump it again. 314 315 ## Using avbtool 316 317 The content for the vbmeta partition can be generated as follows: 318 319 $ avbtool make_vbmeta_image \ 320 [--output OUTPUT] \ 321 [--algorithm ALGORITHM] [--key /path/to/key_used_for_signing_or_pub_key] \ 322 [--public_key_metadata /path/to/pkmd.bin] [--rollback_index NUMBER] \ 323 [--include_descriptors_from_image /path/to/image.bin] \ 324 [--setup_rootfs_from_kernel /path/to/image.bin] \ 325 [--chain_partition part_name:rollback_index_location:/path/to/key1.bin] \ 326 [--signing_helper /path/to/external/signer] \ 327 [--signing_helper_with_files /path/to/external/signer_with_files] \ 328 [--print_required_libavb_version] \ 329 [--append_to_release_string STR] 330 331 An integrity footer containing the hash for an entire partition can be 332 added to an existing image as follows: 333 334 $ avbtool add_hash_footer \ 335 --partition_name PARTNAME --partition_size SIZE \ 336 [--image IMAGE] \ 337 [--algorithm ALGORITHM] [--key /path/to/key_used_for_signing_or_pub_key] \ 338 [--public_key_metadata /path/to/pkmd.bin] [--rollback_index NUMBER] \ 339 [--hash_algorithm HASH_ALG] [--salt HEX] \ 340 [--include_descriptors_from_image /path/to/image.bin] \ 341 [--setup_rootfs_from_kernel /path/to/image.bin] \ 342 [--output_vbmeta_image OUTPUT_IMAGE] [--do_not_append_vbmeta_image] \ 343 [--signing_helper /path/to/external/signer] \ 344 [--signing_helper_with_files /path/to/external/signer_with_files] \ 345 [--print_required_libavb_version] \ 346 [--append_to_release_string STR] \ 347 [--calc_max_image_size] \ 348 [--do_not_use_ab] \ 349 [--use_persistent_digest] 350 351 An integrity footer containing the root digest and salt for a hashtree 352 for a partition can be added to an existing image as follows. The 353 hashtree is also appended to the image. 354 355 $ avbtool add_hashtree_footer \ 356 --partition_name PARTNAME --partition_size SIZE \ 357 [--image IMAGE] \ 358 [--algorithm ALGORITHM] [--key /path/to/key_used_for_signing_or_pub_key] \ 359 [--public_key_metadata /path/to/pkmd.bin] [--rollback_index NUMBER] \ 360 [--hash_algorithm HASH_ALG] [--salt HEX] [--block_size SIZE] \ 361 [--include_descriptors_from_image /path/to/image.bin] \ 362 [--setup_rootfs_from_kernel /path/to/image.bin] \ 363 [--setup_as_rootfs_from_kernel] \ 364 [--output_vbmeta_image OUTPUT_IMAGE] [--do_not_append_vbmeta_image] \ 365 [--do_not_generate_fec] [--fec_num_roots FEC_NUM_ROOTS] \ 366 [--signing_helper /path/to/external/signer] \ 367 [--signing_helper_with_files /path/to/external/signer_with_files] \ 368 [--print_required_libavb_version] \ 369 [--append_to_release_string STR] \ 370 [--calc_max_image_size] \ 371 [--do_not_use_ab] \ 372 [--use_persistent_digest] 373 374 The size of an image with integrity footers can be changed using the 375 `resize_image` command: 376 377 $ avbtool resize_image \ 378 --image IMAGE \ 379 --partition_size SIZE 380 381 The integrity footer on an image can be removed from an image. The 382 hashtree can optionally be kept in place. 383 384 $ avbtool erase_footer --image IMAGE [--keep_hashtree] 385 386 For hash- and hashtree-images the vbmeta struct can also be written to 387 an external file via the `--output_vbmeta_image` option and one can 388 also specify that the vbmeta struct and footer not be added to the 389 image being operated on. 390 391 To calculate the maximum size of an image that will fit in a partition 392 of a given size after having used the `avbtool add_hash_footer` or 393 `avbtool add_hashtree_footer` commands on it, use the 394 `--calc_max_image_size` option: 395 396 $ avbtool add_hash_footer --partition_size $((10*1024*1024)) \ 397 --calc_max_image_size 398 10416128 399 400 $ avbtool add_hashtree_footer --partition_size $((10*1024*1024)) \ 401 --calc_max_image_size 402 10330112 403 404 To calculate the required libavb version that would be put in the 405 vbmeta struct when using `make_vbmeta_image`, `add_hash_footer`, and 406 `add_hashtree_footer` commands use the 407 `--print_required_libavb_version` option: 408 409 $ avbtool make_vbmeta_image \ 410 --algorithm SHA256_RSA2048 --key /path/to/key.pem \ 411 --include_descriptors_from_image /path/to/boot.img \ 412 --include_descriptors_from_image /path/to/system.img \ 413 --print_required_libavb_version 414 1.0 415 416 The `--signing_helper` option can be used in `make_vbmeta_image`, 417 `add_hash_footer` and `add_hashtree_footer` commands to specify any 418 external program for signing hashes. The data to sign (including 419 padding e.g. PKCS1-v1.5) is fed via `STDIN` and the signed data is 420 returned via `STDOUT`. If `--signing_helper` is present in a command 421 line, the `--key` option need only contain a public key. Arguments for 422 a signing helper are `algorithm` and `public key`. If the signing 423 helper exits with a non-zero exit code, it means failure. 424 425 Here's an example invocation: 426 427 /path/to/my_signing_program SHA256_RSA2048 /path/to/publickey.pem 428 429 The `--signing_helper_with_files` is similar to `--signing_helper` 430 except that a temporary file is used to communicate with the helper 431 instead of `STDIN` and `STDOUT`. This is useful in situations where 432 the signing helper is using code which is outputting diagnostics on 433 `STDOUT` instead of `STDERR`. Here's an example invocation 434 435 /path/to/my_signing_program_with_files SHA256_RSA2048 \ 436 /path/to/publickey.pem /tmp/path/to/communication_file 437 438 where the last positional argument is a file that contains the data to 439 sign. The helper should write the signature in this file. 440 441 The `append_vbmeta_image` command can be used to append an entire 442 vbmeta blob to the end of another image. This is useful for cases when 443 not using any vbmeta partitions, for example: 444 445 $ cp boot.img boot-with-vbmeta-appended.img 446 $ avbtool append_vbmeta_image \ 447 --image boot-with-vbmeta-appended.img \ 448 --partition_size SIZE_OF_BOOT_PARTITION \ 449 --vbmeta_image vbmeta.img 450 $ fastboot flash boot boot-with-vbmeta-appended.img 451 452 The `verify_image` command can be used to verify the contents of 453 several image files at the same time. When invoked on an image the 454 following checks are performed: 455 456 * If the image has a VBMeta struct the signature is checked against 457 the embedded public key. If the image doesn't look like `vbmeta.img` 458 then a footer is looked for and used if present. 459 460 * If the option `--key` is passed then a `.pem` file is expected and 461 it's checked that the embedded public key in said VBMeta struct 462 matches the given key. 463 464 * All descriptors in the VBMeta struct are checked in the following 465 way: 466 + For a hash descriptor the image file corresponding to the 467 partition name is loaded and its digest is checked against that 468 in the descriptor. 469 + For a hashtree descriptor the image file corresponding to the 470 partition name is loaded and the hashtree is calculated and its 471 root digest compared to that in the descriptor. 472 + For a chained partition descriptor its contents is compared 473 against content that needs to be passed in via the 474 `--expected_chain_partition` options. The format for this option 475 is similar to that of the `--chain_partition` option. If there 476 is no `--expected_chain_partition` descriptor for the chain 477 partition descriptor the check fails. 478 479 Here's an example for a setup where the digests for `boot.img` and 480 `system.img` are stored in `vbmeta.img` which is signed with 481 `my_key.pem`. It also checks that the chain partition for partition 482 `foobar` uses rollback index 8 and that the public key in AVB format 483 matches that of the file `foobar_vendor_key.avbpubkey`: 484 485 $ avbtool verify_image \ 486 --image /path/to/vbmeta.img \ 487 --key my_key.pem \ 488 --expect_chained_partition foobar:8:foobar_vendor_key.avbpubkey 489 490 Verifying image /path/to/vbmeta.img using key at my_key.pem 491 vbmeta: Successfully verified SHA256_RSA4096 vbmeta struct in /path_to/vbmeta.img 492 boot: Successfully verified sha256 hash of /path/to/boot.img for image of 10543104 bytes 493 system: Successfully verified sha1 hashtree of /path/to/system.img for image of 1065213952 bytes 494 foobar: Successfully verified chain partition descriptor matches expected data 495 496 In this example the `verify_image` command verifies the files 497 `vbmeta.img`, `boot.img`, and `system.img` in the directory 498 `/path/to`. The directory and file extension of the given image 499 (e.g. `/path/to/vbmeta.img`) is used together with the partition name 500 in the descriptor to calculate the filenames of the images holding 501 hash and hashtree images. 502 503 The `verify_image` command can also be used to check that a custom 504 signing helper works as intended. 505 506 ## Build System Integration 507 508 In Android, AVB is enabled by the `BOARD_AVB_ENABLE` variable 509 510 BOARD_AVB_ENABLE := true 511 512 This will make the build system create `vbmeta.img` which will contain 513 a hash descriptor for `boot.img`, a hashtree descriptor for 514 `system.img`, a kernel-cmdline descriptor for setting up `dm-verity` 515 for `system.img` and append a hash-tree to `system.img`. If the build 516 system is set up such that `vendor.img` is being built, a hash-tree 517 will also be appended to this image and its hash-tree descriptor will 518 be included in `vbmeta.img`. 519 520 By default, the algorithm `SHA256_RSA4096` is used with a test key 521 from the `external/avb/test/data` directory. This can be overriden by 522 the `BOARD_AVB_ALGORITHM` and `BOARD_AVB_KEY_PATH` variables to use 523 e.g. a 4096-bit RSA key and SHA-512: 524 525 BOARD_AVB_ALGORITHM := SHA512_RSA4096 526 BOARD_AVB_KEY_PATH := /path/to/rsa_key_4096bits.pem 527 528 Remember that the public part of this key needs to be available to the 529 bootloader of the device expected to verify resulting images. Use 530 `avbtool extract_public_key` to extract the key in the expected format 531 (`AVB_pk` in the following). If the device is using a different root 532 of trust than `AVB_pk` the `--public_key_metadata` option can be used 533 to embed a blob (`AVB_pkmd` in the following) that can be used to 534 e.g. derive `AVB_pk`. Both `AVB_pk` and `AVB_pkmd` are passed to the 535 `validate_vbmeta_public_key()` operation when verifying a slot. 536 537 Some devices may support the end-user configuring the root of trust to use, see 538 the [Device Specific Notes](#Device-Specific-Notes) section for details. 539 540 To prevent rollback attacks, the rollback index should be increased on 541 a regular basis. The rollback index can be set with the 542 `BOARD_AVB_ROLLBACK_INDEX` variable: 543 544 BOARD_AVB_ROLLBACK_INDEX := 5 545 546 If this is not set, the rollback index defaults to 0. 547 548 The variable `BOARD_AVB_MAKE_VBMETA_IMAGE_ARGS` can be used to specify 549 additional options passed to `avbtool make_vbmeta_image`. Typical 550 options to be used here include `--prop`, `--prop_from_file`, 551 `--chain_partition`, `--public_key_metadata`, and `--signing_helper`. 552 553 The variable `BOARD_AVB_BOOT_ADD_HASH_FOOTER_ARGS` can be used to 554 specify additional options passed to `avbtool add_hash_footer` for 555 `boot.img`. Typical options to be used here include `--hash_algorithm` 556 and `--salt`. 557 558 The variable `BOARD_AVB_SYSTEM_ADD_HASHTREE_FOOTER_ARGS` can be used 559 to specify additional options passed to `avbtool add_hashtree_footer` 560 for `system.img`. Typical options to be used here include 561 `--hash_algorithm`, `--salt`, `--block_size`, and 562 `--do_not_generate_fec`. 563 564 The variable `BOARD_AVB_VENDOR_ADD_HASHTREE_FOOTER_ARGS` can be used 565 to specify additional options passed to `avbtool add_hashtree_footer` 566 for `vendor.img`. Typical options to be used here include 567 `--hash_algorithm`, `--salt`, `--block_size`, and 568 `--do_not_generate_fec`. 569 570 The variable `BOARD_AVB_DTBO_ADD_HASH_FOOTER_ARGS` can be used to 571 specify additional options passed to `avbtool add_hash_footer` for 572 `dtbo.img`. Typical options to be used here include `--hash_algorithm` 573 and `--salt`. 574 575 Build system variables (such as `PRODUCT_SUPPORTS_VERITY_FEC`) used 576 for previous version of Verified Boot in Android are not used in AVB. 577 578 A/B related build system variables can be found [here](https://source.android.com/devices/tech/ota/ab_updates#build-variables). 579 580 # Device Integration 581 582 This section discusses recommendations and best practices for 583 integrating `libavb` with a device boot loader. It's important to 584 emphasize that these are just recommendations so the use of the word 585 `must` should be taken lightly. 586 587 Additionally term *HLOS* is used in this chapter to refer to the *High 588 Level Operating System*. This obviously includes Android (including 589 other form-factors than phones) but could also be other operating 590 systems. 591 592 ## System Dependencies 593 594 The `libavb` library is written in a way so it's portable to any 595 system with a C99 compiler. It does not require the standard C library 596 however the boot loader must implement a simple set of system 597 primitives required by `libavb` such as `avb_malloc()`, `avb_free()`, 598 and `avb_print()`. 599 600 In addition to the system primitives, `libavb` interfaces with the boot 601 loader through the supplied `AvbOps` struct. This includes operations 602 to read and write data from partitions, read and write rollback 603 indexes, check if the public key used to make a signature should be 604 accepted, and so on. 605 606 ## Locked and Unlocked mode 607 608 AVB has been designed to support the notion of the device being either 609 LOCKED state or UNLOCKED state as used in Android. 610 611 In the context of AVB, the LOCKED state means that verification errors 612 are fatal whereas in UNLOCKED state they are not. If the device is 613 UNLOCKED pass `AVB_SLOT_VERIFY_FLAGS_ALLOW_VERIFICATION_ERROR` flag in 614 the `flags` parameter of `avb_slot_verify()` and treat verification 615 errors including 616 617 * `AVB_SLOT_VERIFY_RESULT_ERROR_PUBLIC_KEY_REJECTED` 618 * `AVB_SLOT_VERIFY_RESULT_ERROR_VERIFICATION` 619 * `AVB_SLOT_VERIFY_RESULT_ERROR_ROLLBACK_INDEX` 620 621 as non-fatal. If the device is in the LOCKED state, don't pass the 622 `AVB_SLOT_VERIFY_FLAGS_ALLOW_VERIFICATION_ERROR` flag in the `flags` 623 parameter of `avb_slot_verify()` and only treat 624 `AVB_SLOT_VERIFY_RESULT_OK` as non-fatal. 625 626 On Android, device state may be altered through the fastboot interface 627 using, e.g. `fastboot flashing lock` (to transition to the LOCKED 628 state) and `fastboot flashing unlock` (to transition to the UNLOCKED 629 state). 630 631 The device must only allow state transitions (e.g. from LOCKED to 632 UNLOCKED or UNLOCKED to LOCKED) after asserting physical presence of 633 the user. If the device has a display and buttons this is typically 634 done by showing a dialog and requiring the user to confirm or cancel 635 using physical buttons. 636 637 All user data must be cleared when transitioning from the LOCKED to 638 the UNLOCKED state (including the `userdata` partition and any NVRAM 639 spaces). Additionally all `stored_rollback_index[n]` locations must be 640 cleared (all elements must be set to zero). Similar action (erasing 641 `userdata`, NVRAM spaces, and `stored_rollback_index[n]` locations) 642 shall also happening when transitioning from UNLOCKED to LOCKED. If 643 the device is required to use full disk encryption, then a less 644 intensive wipe is required for UNLOCKED to LOCKED. Depending on the 645 device form-factor and intended use, the user should be prompted to 646 confirm before any data is erased. 647 648 ## Tamper-evident Storage 649 650 In this document, *tamper-evident* means that it's possible to detect 651 if the HLOS has tampered with the data, e.g. if it has been 652 overwritten. 653 654 Tamper-evident storage must be used for stored rollback indexes, keys 655 used for verification, device state (whether the device is LOCKED or 656 UNLOCKED), and named persistent values. If tampering has been detected 657 the corresponding `AvbOps` operation should fail by e.g. returning 658 `AVB_IO_RESULT_ERROR_IO`. It is especially important that verification 659 keys cannot be tampered with since they represent the root-of-trust. 660 661 If verification keys are mutable they must only be set by the end 662 user, e.g. it must never be set at the factory or store or any 663 intermediate point before the end user. Additionally, it must only be 664 possible to set or clear a key while the device is in the UNLOCKED 665 state. 666 667 ## Named Persistent Values 668 669 AVB 1.1 introduces support for named persistent values which must be 670 tamper evident and allows AVB to store arbitrary key-value pairs. 671 Integrators may limit support for these values to a set of fixed 672 well-known names, a maximum value size, and / or a maximum number of 673 values. 674 675 ## Persistent Digests 676 677 Using a persistent digest for a partition means the digest (or root 678 digest in the case of a hashtree) is not stored in the descriptor but 679 is stored in a named persistent value. This allows configuration data 680 which may differ from device to device to be verified by AVB. It must 681 not be possible to modify the persistent digest when the device is in 682 the LOCKED state. 683 684 To specify that a descriptor should use a persistent digest, use the 685 `--use_persistent_digest` option for the `add_hash_footer` or 686 `add_hashtree_footer` avbtool operations. Then, during verification of 687 the descriptor, AVB will look for the digest in the named persistent 688 value `avb.persistent_digest.$(partition_name)` instead of in the 689 descriptor itself. 690 691 For hashtree descriptors using a persistent digest, the digest value 692 will be available for substitution into kernel command line descriptors 693 using a token of the form `$(AVB_FOO_ROOT_DIGEST)` where 'FOO' is the 694 uppercase partition name, in this case for the partition named 'foo'. 695 The token will be replaced by the digest in hexadecimal form. 696 697 ## Updating Stored Rollback Indexes 698 699 In order for Rollback Protection to work the bootloader will need to 700 update the `stored_rollback_indexes[n]` array on the device prior to 701 transferring control to the HLOS. If not using A/B this is 702 straightforward - just update it to what's in the AVB metadata for the 703 slot before booting. In pseudo-code it would look like this: 704 705 ```c++ 706 // The |slot_data| parameter should be the AvbSlotVerifyData returned 707 // by avb_slot_verify() for the slot we're about to boot. 708 // 709 bool update_stored_rollback_indexes_for_slot(AvbOps* ops, 710 AvbSlotVerifyData* slot_data) { 711 for (int n = 0; n < AVB_MAX_NUMBER_OF_ROLLBACK_INDEX_LOCATIONS; n++) { 712 uint64_t rollback_index = slot_data->rollback_indexes[n]; 713 if (rollback_index > 0) { 714 AvbIOResult io_ret; 715 uint64_t current_stored_rollback_index; 716 717 io_ret = ops->read_rollback_index(ops, n, ¤t_stored_rollback_index); 718 if (io_ret != AVB_IO_RESULT_OK) { 719 return false; 720 } 721 722 if (rollback_index > current_stored_rollback_index) { 723 io_ret = ops->write_rollback_index(ops, n, rollback_index); 724 if (io_ret != AVB_IO_RESULT_OK) { 725 return false; 726 } 727 } 728 } 729 } 730 return true; 731 } 732 ``` 733 734 However if using A/B more care must be taken to still allow the device 735 to fall back to the old slot if the update didn't work. 736 737 For an HLOS like Android where rollback is only supported if the 738 updated OS version is found to not work, `stored_rollback_index[n]` 739 should only be updated from slots that are marked as SUCCESSFUL in the 740 A/B metadata. The pseudo-code for that is as follows where 741 `is_slot_is_marked_as_successful()` comes from the A/B stack in use: 742 743 ```c++ 744 if (is_slot_is_marked_as_successful(slot->ab_suffix)) { 745 if (!update_stored_rollback_indexes_for_slot(ops, slot)) { 746 // TODO: handle error. 747 } 748 } 749 ``` 750 751 For an HLOS where it's possible to roll back to a previous version, 752 `stored_rollback_index[n]` should be set to the largest possible value 753 allowing all bootable slots to boot. This approach is implemented in 754 AVB's experimental (and now deprecated) A/B stack `libavb_ab`, see the 755 `avb_ab_flow()` implementation. Note that this requires verifying 756 *all* bootable slots at every boot and this may impact boot time. 757 758 ## Recommended Bootflow 759 760 The recommended boot flow for a device using AVB is as follows: 761 762 ![Recommended AVB boot flow](docs/avb-recommended-boot-flow.png) 763 764 Notes: 765 766 * The device is expected to search through all A/B slots until it 767 finds a valid OS to boot. Slots that are rejected in the LOCKED 768 state might not be rejected in the UNLOCKED state, (e.g. when 769 UNLOCKED any key can be used and rollback index failures are 770 allowed), so the algorithm used for selecting a slot varies 771 depending on what state the device is in. 772 773 * If no valid OS (that is, no bootable A/B slot) can be found, the 774 device cannot boot and has to enter repair mode. It is 775 device-dependent what this looks like. If the device has a screen 776 it must convey this state to the user. 777 778 * If the device is LOCKED, only an OS signed by an embedded 779 verification key (see the previous section) shall be 780 accepted. Additionally, `rollback_index[n]` as stored in the 781 verified image must be greater or equal than what's in 782 `stored_rollback_index[n]` on the device (for all `n`) and the 783 `stored_rollback_index[n]` array is expected to be updated as 784 specified in the previous section. 785 + If the key used for verification was set by the end user, and 786 the device has a screen, it must show a warning with the key 787 fingerprint to convey that the device is booting a custom 788 OS. The warning must be shown for at least 10 seconds before the 789 boot process continues. If the device does not have a screen, 790 other ways must be used to convey that the device is booting a 791 custom OS (lightbars, LEDs, etc.). 792 793 * If the device is UNLOCKED, there is no requirement to check the key 794 used to sign the OS nor is there any requirement to check or update 795 rollback `stored_rollback_index[n]` on the device. Because of this 796 the user must always be shown a warning about verification not 797 occurring. 798 + It is device-dependent how this is implemented since it depends 799 on the device form-factor and intended usage. If the device has 800 a screen and buttons (for example if it's a phone) the warning 801 is to be shown for at least 10 seconds before the boot process 802 continues. If the device does not have a screen, other ways must 803 be used to convey that the device is UNLOCKED (lightbars, LEDs, 804 etc.). 805 806 ## Handling dm-verity Errors 807 808 By design, hashtree verification errors are detected by the HLOS and 809 not the bootloader. AVB provides a way to specify how the error should 810 be handled through the `hashtree_error_mode` parameter in the 811 `avb_slot_verify()` function. Possible values include 812 813 * `AVB_HASHTREE_ERROR_MODE_RESTART_AND_INVALIDATE` means that the HLOS 814 will invalidate the current slot and restart. On devices with A/B 815 this would lead to attempting to boot the other slot (if it's marked 816 as bootable) or it could lead to a mode where no OS can be booted 817 (e.g. some form of repair mode). 818 819 * `AVB_HASHTREE_ERROR_MODE_RESTART` means that the OS will restart 820 without the current slot being invalidated. Be careful using this 821 mode unconditionally as it may introduce boot loops if the same 822 hashtree verification error is hit on every boot. 823 824 * `AVB_HASHTREE_ERROR_MODE_EIO` means that an `EIO` error will be 825 returned to the application. 826 827 * `AVB_HASHTREE_ERROR_MODE_LOGGING` means that errors will be logged 828 and corrupt data may be returned to applications. This mode should 829 be used for **ONLY** diagnostics and debugging. It cannot be used 830 unless verification errors are allowed. 831 832 The value passed in `hashtree_error_mode` is essentially just passed 833 on through to the HLOS through the the `androidboot.veritymode` and 834 `androidboot.vbmeta.invalidate_on_error` kernel command-line 835 parameters. The HLOS - including the Linux kernel when using 836 `CONFIG_DM_VERITY_AVB` - will then act upon hashtree verification 837 errors as specified. 838 839 ### Which mode should I use for my device? 840 841 This depends entirely on the device, how the device is intended to be 842 used, and the desired user experience. 843 844 For example, consider 845 the 846 [EIO mode in an earlier version of Android Verified Boot](https://source.android.com/security/verifiedboot/verified-boot) (see 847 the "Recovering from dm-verity errors" section). In a nutshell this 848 mode uses `AVB_HASHTREE_ERROR_MODE_RESTART` mode until an error is 849 encounted and then it switches to `AVB_HASHTREE_ERROR_MODE_EIO` mode 850 on the reboot. Additionally when in `AVB_HASHTREE_ERROR_MODE_EIO` mode 851 the user is informed that the device experienced corruption and then 852 asked to click through a screen to continue. 853 854 To implement this mode in a boot loader, a combination of the 855 `AVB_HASHTREE_ERROR_MODE_RESTART` mode and 856 `AVB_HASHTREE_ERROR_MODE_EIO` mode could be used along with persistent 857 storage recording what mode the bootloader is currently in. This would 858 need to include transition rules e.g. if the kernel indicates that it 859 rebooted because of a `dm-verity` error the bootloader would need to 860 transition from the `AVB_HASHTREE_ERROR_MODE_RESTART` mode to the 861 `AVB_HASHTREE_ERROR_MODE_EIO` mode. Ditto, when the slot is updated 862 the bootloader needs to transition from the 863 `AVB_HASHTREE_ERROR_MODE_EIO` mode back to the 864 `AVB_HASHTREE_ERROR_MODE_RESTART` mode so the user doesn't have to 865 click through a screen on every boot. 866 867 On the other hand, if the device doesn't have a screen or if the HLOS 868 supports multiple bootable slots simultaneously it may make more sense 869 to just use `AVB_HASHTREE_ERROR_MODE_RESTART_AND_INVALIDATE`. 870 871 ## Android Specific Integration 872 873 On Android, the boot loader must set the 874 `androidboot.verifiedbootstate` parameter on the kernel command-line 875 to indicate the boot state. It shall use the following values: 876 877 * **green**: If in LOCKED state and the key used for verification was not set by the end user. 878 * **yellow**: If in LOCKED state and the key used for verification was set by the end user. 879 * **orange**: If in the UNLOCKED state. 880 881 ## Device Specific Notes 882 883 This section contains information about how AVB is integrated into specific 884 devices. This is not an exhaustive list. 885 886 ### Pixel 2 887 888 On the Pixel 2 and Pixel 2 XL the boot loader supports a virtual partition with 889 the name `avb_custom_key`. Flashing and erasing this partition only works in the 890 UNLOCKED state. Setting the custom key is done like this: 891 892 avbtool extract_public_key --key key.pem --output pkmd.bin 893 fastboot flash avb_custom_key pkmd.bin 894 895 Erasing the key is done by erasing the virtual partition: 896 897 fastboot erase avb_custom_key 898 899 When the custom key is set and the device is in the LOCKED state it will boot 900 images signed with both the built-in key as well as the custom key. All other 901 security features (including rollback-protection) are in effect, e.g. the 902 **only** difference is the root of trust to use. 903 904 When booting an image signed with a custom key, a yellow screen will be shown as 905 part of the boot process to remind the user that the custom key is in use. 906 907 # Version History 908 909 ### Version 1.1 910 911 Version 1.1 adds support for the following: 912 913 * A 32-bit `flags` element is added to hash and hashtree descriptors. 914 * Support for partitions which don't use [A/B](#A_B-Support). 915 * Tamper-evident [named persistent values](#Named-Persistent-Values). 916 * [Persistent digests](#Persistent-Digests) for hash or hashtree descriptors. 917 918 ### Version 1.0 919 920 All features not explicitly listed under a later version are supported by 1.0. 921