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