1# Android Verified Boot 2.0 2 3This repository contains tools and libraries for working with Android 4Verified Boot 2.0. Usually AVB is used to refer to this codebase. 5 6## Introduction 7 8The main job of `avbtool` is to create `vbmeta.img` which is the 9top-level object for verified boot. This image is designed to go into 10the `vbmeta` partition (or, if using A/B, the slot in question 11e.g. `vbmeta_a` or `vbmeta_b`) and be of minimal size (for out-of-band 12updates). The vbmeta image is cryptographically signed and contains 13verification data (e.g. cryptographic digests) for verifying 14`boot.img`, `system.img`, and other partitions/images. 15 16The vbmeta image can also contain references to other partitions where 17verification data is stored as well as a public key indicating who 18should sign the verification data. This indirection provides 19delegation, that is, it allows a 3rd party to control content on a 20given partition by including their public key in `vbmeta.img`. By 21design, this authority can be easily revoked by simply updating 22`vbmeta.img` with new descriptors for the partition in question. 23 24Storing signed verification data on other images - for example 25`boot.img` and `system.img` - is also done with `avbtool`. 26 27In addition to `avbtool`, a library - `libavb` - is provided. This 28library performs all verification on the device side e.g. it starts by 29loading the vbmeta partition, checks the signature, and then goes on 30to load the boot partition for verification. This library is intended 31to be used in both boot loaders and inside Android. It has a simple 32abstraction for system dependencies (see `avb_sysdeps.h`) as well as 33operations that the boot loader or OS is expected to implement (see 34`avb_ops.h`). The main entry point for verification is 35`avb_slot_verify()`. 36 37It is expected that most devices will use A/B (e.g. multiple copies of 38the OS in separate so-called 'slots') in addition to AVB. While 39managing A/B metadata and associated metadata (e.g. managing 40`stored_rollback_index[n]` locations) is outside the scope of 41`libavb`, enough interfaces are exposed so the boot loader can 42integrate its A/B stack with `libavb`. In particular 43`avb_slot_verify()` takes a `slot_suffix` parameter and its result 44struct `AvbSlotVerifyData` convey the rollback indexes in the image 45that was verified. 46 47AVB also includes an A/B implementation that boot loaders may 48optionally use. This implementation is in the `libavb_ab` library and 49integrates with image verification including updating the 50`stored_rollback_index[n]` locations on the device as needed. The 51bootloader can use this through the `avb_ab_flow()` function which in 52turn calls `avb_slot_verify()` as needed. 53 54In `libavb_ab`, A/B metadata is stored in the `misc` partition using a 55format private to `libavb_ab` in the location on `misc` reserved for 56this. For more information about the `misc.img` file format see 57the 58[bootloader_message.h](https://android.googlesource.com/platform/bootable/recovery/+/master/bootloader_message/include/bootloader_message/bootloader_message.h) file 59in AOSP. A/B metadata can be written to `misc.img` using the 60`set_ab_metadata` sub-command of `avbtool`. A/B metadata is comprised 61of data for each slo and per-slot metadata has a priority field (0 to 6215), number of tries remaining for attempting to boot the slot (0 to 637), and a flag to indicate whether the slot has successfully booted. 64 65A/B metadata integrity is provided by a simple magic marker and a 66CRC-32 checksum. If invalid A/B metadata is detected, the behavior is 67to reset the A/B metadata to a known state where both slots are given 68seven boot tries. 69 70An implementation of a boot_control HAL using AVB-specific A/B 71metadata is also provided. 72 73Android Things has specific requirements and validation logic for the 74vbmeta public key. An extension is provided in `libavb_atx` which 75performs this validation as an implementatio of `libavb`'s public key 76validation operation (see `avb_validate_vbmeta_public_key()` in 77`avb_ops.h`). 78 79## Files and Directories 80 81* `libavb/` 82 + An implementation of image verification. This code is designed 83 to be highly portable so it can be used in as many contexts as 84 possible. This code requires a C99-compliant C compiler. Part of 85 this code is considered internal to the implementation and 86 should not be used outside it. For example, this applies to the 87 `avb_rsa.[ch]` and `avb_sha.[ch]` files. System dependencies 88 expected to be provided by the platform is defined in 89 `avb_sysdeps.h`. If the platform provides the standard C runtime 90 `avb_sysdeps_posix.c` can be used. 91* `libavb_ab/` 92 + An A/B implementation for use in boot loaders. 93* `libavb_atx/` 94 + An Android Things Extension for validating public key metadata. 95* `libavb_user/` 96 + Contains an AvbOps implementation suitable for use in userspace 97 on the device (used in boot_control.avb and avbctl). 98* `boot_control/` 99 + An implemementation of the Android boot_control HAL for use with 100 boot loaders using `libavb_ab`. 101* `Android.mk` 102 + Build instructions for building libavb (a static library for use 103 on the device), host-side libraries (for unit tests), and unit 104 tests. 105* `avbtool` 106 + A tool written in Python for working with images related to 107 verified boot. 108* `test/` 109 + Unit tests for `abvtool`, `libavb`, `libavb_ab`, and 110 `libavb_atx`. 111* `tools/avbctl/` 112 + Contains the source-code for a tool that can be used to control 113 AVB at runtime. 114* `examples/uefi/` 115 + Contains the source-code for a UEFI-based boot-loader utilizing 116 `libavb/` and `libavb_ab/`. 117 118## Audience and portability notes 119 120This code is intended to be used in bootloaders in devices running 121Android. The suggested approach is to copy the appropriate header and 122C files mentioned in the previous section into the boot loader and 123integrate as appropriate. 124 125The `libavb/` and `libavb_ab/` codebase will evolve over time so 126integration should be as non-invasive as possible. The intention is to 127keep the API of the library stable however it will be broken if 128necessary. As for portability, the library is intended to be highly 129portable, work on both little- and big-endian architectures and 32- 130and 64-bit. It's also intended to work in non-standard environments 131without the standard C library and runtime. 132 133If the `AVB_ENABLE_DEBUG` preprocessor symbol is set, the code will 134include useful debug information and run-time checks. Production 135builds should not use this. The preprocessor symbol `AVB_COMPILATION` 136should be set only when compiling the libraries. The code must be 137compiled into a separate libraries. 138 139Applications using the compiled `libavb` library must only include the 140`libavb/libavb.h` file (which will include all public interfaces) and 141must not have the `AVB_COMPILATION` preprocessor symbol set. This is 142to ensure that internal code that may be change in the future (for 143example `avb_sha.[ch]` and `avb_rsa.[ch]`) will not be visible to 144application code. 145 146## Versioning and compatibility 147 148AVB uses a version number with three fields - the major, minor, and 149sub version. Here's an example version number 150 151 1.4.3 152 ^ ^ ^ 153 | | | 154 the major version ---+ | | 155 the minor version -----+ | 156 the sub version -------+ 157 158The major version number is bumped only if compatibility is broken, 159e.g. a struct field has been removed or changed. The minor version 160number is bumped only if a new feature is introduced, for example a 161new algorithm or descriptor has been added. The sub version number is 162bumped when bugs are fixed or other changes not affecting 163compatibility are made. 164 165The `AvbVBMetaImageHeader` struct (as defined in the 166`avb_vbmeta_image.h`) carries the major and minor version number of 167`libavb` required to verify the struct in question. This is stored in 168the `required_libavb_version_major` and 169`required_libavb_version_minor` fields. Additionally this struct 170contains a textual field with the version of `avbtool` used to create 171the struct, for example "avbtool 1.4.3" or "avbtool 1.4.3 some_board 172Git-4589fbec". 173 174Note that it's entirely possible to have a `AvbVBMetaImageHeader` 175struct with 176 177 required_libavb_version_major = 1 178 required_libavb_version_minor = 0 179 avbtool_release_string = "avbtool 1.4.3" 180 181if, for example, creating an image that does not use any features 182added after AVB version 1.0. 183 184## Adding new features 185 186If adding a new feature for example a new algorithm or a new 187descriptor then `AVB_VERSION_MINOR` in `avb_version.h` and `avbtool` 188must be bumped and `AVB_VERSION_SUB` should be set to zero. 189 190Unit tests **MUST** be added to check that 191 192* The feature is used if - and only if - suitable commands/options are 193 passed to `avbtool`. 194* The `required_version_minor` field is set to the bumped value if - 195 and only if - the feature is used. 196 197If `AVB_VERSION_MINOR` has already been bumped since the last release 198there is obviously no need to bump it again. 199 200## Usage 201 202The content for the vbmeta partition can be generated as follows: 203 204 $ avbtool make_vbmeta_image \ 205 --output OUTPUT \ 206 [--algorithm ALGORITHM] [--key /path/to/key_used_for_signing_or_pub_key] \ 207 [--public_key_metadata /path/to/pkmd.bin] [--rollback_index NUMBER] \ 208 [--include_descriptors_from_footer /path/to/image.bin] \ 209 [--setup_rootfs_from_kernel /path/to/image.bin] \ 210 [--chain_partition part_name:rollback_index_location:/path/to/key1.bin] \ 211 [--signing_helper /path/to/external/signer] \ 212 [--append_to_release_string STR] 213 214An integrity footer containing the hash for an entire partition can be 215added to an existing image as follows: 216 217 $ avbtool add_hash_footer \ 218 --image IMAGE \ 219 --partition_name PARTNAME --partition_size SIZE \ 220 [--algorithm ALGORITHM] [--key /path/to/key_used_for_signing_or_pub_key] \ 221 [--public_key_metadata /path/to/pkmd.bin] [--rollback_index NUMBER] \ 222 [--hash_algorithm HASH_ALG] [--salt HEX] \ 223 [--include_descriptors_from_footer /path/to/image.bin] \ 224 [--setup_rootfs_from_kernel /path/to/image.bin] \ 225 [--output_vbmeta_image OUTPUT_IMAGE] [--do_not_append_vbmeta_image] \ 226 [--signing_helper /path/to/external/signer] \ 227 [--append_to_release_string STR] 228 229An integrity footer containing the root digest and salt for a hashtree 230for a partition can be added to an existing image as follows. The 231hashtree is also appended to the image. 232 233 $ avbtool add_hashtree_footer \ 234 --image IMAGE \ 235 --partition_name PARTNAME --partition_size SIZE \ 236 [--algorithm ALGORITHM] [--key /path/to/key_used_for_signing_or_pub_key] \ 237 [--public_key_metadata /path/to/pkmd.bin] [--rollback_index NUMBER] \ 238 [--hash_algorithm HASH_ALG] [--salt HEX] [--block_size SIZE] \ 239 [--include_descriptors_from_footer /path/to/image.bin] \ 240 [--setup_rootfs_from_kernel /path/to/image.bin] \ 241 [--output_vbmeta_image OUTPUT_IMAGE] [--do_not_append_vbmeta_image] \ 242 [--generate_fec] [--fec_num_roots FEC_NUM_ROOTS] \ 243 [--signing_helper /path/to/external/signer] \ 244 [--append_to_release_string STR] 245 246The integrity footer on an image can be removed from an image. The 247hashtree can optionally be kept in place. 248 249 $ avbtool erase_footer --image IMAGE [--keep_hashtree] 250 251For hash- and hashtree-images the vbmeta struct can also be written to 252an external file via the `--output_vbmeta_image` option and one can 253also specify that the vbmeta struct and footer not be added to the 254image being operated on. 255 256To calculate the maximum size of an image that will fit in a partition 257of a given size after having used the `avbtool add_hashtree_footer` 258command on it, use the `--calc_max_image_size` option: 259 260 $ avbtool add_hashtree_footer --partition_size $((10*1024*1024)) \ 261 --calc_max_image_size 262 10330112 263 264The `--signing_helper` option can be used in `make_vbmeta_image`, 265`add_hash_footer` and `add_hashtree_footer` commands to specify any 266external program for signing hashes. The data to sign (including 267padding e.g. PKCS1-v1.5) is fed via `STDIN` and the signed data is 268returned via `STDOUT`. If `--signing_helper` is present in a command 269line, the `--key` option need only contain a public key. Arguments for 270a signing helper are `algorithm` and `public key`. If the signing 271helper exits with a non-zero exit code, it means failure. 272 273Here's an example invocation: 274 275 /path/to/my_signing_program SHA256_RSA2048 /path/to/publickey.pem 276 277The `append_vbmeta_image` command can be used to append an entire 278vbmeta blob to the end of another image. This is useful for cases when 279not using any vbmeta partitions, for example: 280 281 $ cp boot.img boot-with-vbmeta-appended.img 282 $ avbtool append_vbmeta_image \ 283 --image boot-with-vbmeta-appended.img \ 284 --partition_size SIZE_OF_BOOT_PARTITION \ 285 --vbmeta_image vbmeta.img 286 $ fastboot flash boot boot-with-vbmeta-appended.img 287 288## Build system integration notes 289 290Android Verified Boot is enabled by the `BOARD_AVB_ENABLE` variable 291 292 BOARD_AVB_ENABLE := true 293 294This will make the build system create `vbmeta.img` which will contain 295a hash descriptor for `boot.img`, a hashtree descriptor for 296`system.img`, a kernel-cmdline descriptor for setting up `dm-verity` 297for `system.img` and append a hash-tree to `system.img`. 298 299By default, the algorithm `SHA256_RSA4096` is used with a test key 300from the `external/avb/test/data` directory. This can be overriden by 301the `BOARD_AVB_ALGORITHM` and `BOARD_AVB_KEY_PATH` variables to use 302e.g. a 4096-bit RSA key and SHA-512: 303 304 BOARD_AVB_ALGORITHM := SHA512_RSA4096 305 BOARD_AVB_KEY_PATH := /path/to/rsa_key_4096bits.pem 306 307Remember that the public part of this key needs to be available to the 308bootloader of the device expected to verify resulting images. Use 309`avbtool extract_public_key` to extract the key in the expected format 310(**AVB_pk** in the following). If the device is using a different root 311of trust than **AVB_pk** the `--public_key_metadata` option can be 312used to embed a blob (**AVB_pkmd** in the following) that can be used 313to e.g. derive **AVB_pk**. Both **AVB_pk** and **AVB_pkmd** are passed 314to the `validate_vbmeta_public_key()` operation when verifying a slot. 315 316To prevent rollback attacks, the rollback index should be increased on 317a regular basis. The rollback index can be set with the 318`BOARD_AVB_ROLLBACK_INDEX` variable: 319 320 BOARD_AVB_ROLLBACK_INDEX := 5 321 322If this is not set, the rollback index defaults to 0. 323 324The variable `BOARD_AVB_MAKE_VBMETA_IMAGE_ARGS` can be used to specify 325additional options passed to `avbtool make_vbmeta_image`. Typical 326options to be used here include `--prop`, `--prop_from_file`, and 327`--chain_partition`. 328 329The variable `BOARD_AVBTOOL_BOOT_ADD_HASH_FOOTER_ARGS` can be used to 330specify additional options passed to `avbtool add_hash_footer` for 331`boot.img`. Typical options to be used here include `--hash_algorithm` 332and `--salt`. 333 334The variable `BOARD_AVBTOOL_SYSTEM_ADD_HASHTREE_FOOTER_ARGS` can be 335used to specify additional options passed to `avbtool 336add_hashtree_footer` for `system.img`. Typical options to be used here 337include `--hash_algorithm`, `--salt`, `--block_size`, and 338`--generate_fec`. 339 340Build system variables (such as `PRODUCT_SUPPORTS_VERITY_FEC`) used 341for previous version of Verified Boot in Android are not used in AVB 342