David Zeuthen | baf59e2 | 2016-11-14 15:39:43 -0500 | [diff] [blame] | 1 | This directory contains avbtool, libavb, and libavb_ab. |
David Zeuthen | 21e9526 | 2016-07-27 17:58:40 -0400 | [diff] [blame] | 2 | |
| 3 | The main job of avbtool is to create vbmeta.img which is the |
| 4 | top-level object for verified boot. This image is designed to go into |
| 5 | the vbmeta partition (or, if using A/B, the slot in question |
| 6 | e.g. vbmeta_a or vbmeta_b) and be of minimal size (for out-of-band |
| 7 | updates). The vbmeta image is cryptographically signed and contains |
| 8 | verification data (e.g. cryptographic digests) for verifying boot.img, |
| 9 | system.img, and other partitions/images. |
| 10 | |
| 11 | The vbmeta image can also contain references to other partitions where |
| 12 | verification data is stored as well as a public key indicating who |
| 13 | should sign the verification data. This indirection provides |
| 14 | delegation, that is, it allows a 3rd party to control content on a given |
| 15 | partition by including the public key said 3rd party is using to sign |
| 16 | the data with, in vbmeta.img. By design, this authority can be easily |
| 17 | revoked by simply updating vbmeta.img with new descriptors for the |
| 18 | partition in question. |
| 19 | |
| 20 | Storing signed verification data on other images - for example |
| 21 | boot.img and system.img - is also done with avbtool. |
| 22 | |
| 23 | In addition to avbtool, a library - libavb - is provided. This library |
| 24 | performs all verification on the device side e.g. it starts by loading |
| 25 | the vbmeta partition, checks the signature, and then goes on to load |
| 26 | the boot partition for verification. |
| 27 | |
| 28 | The libavb library is intended to be used in both boot loaders and |
| 29 | inside Android. It has a simple abstraction for system dependencies |
| 30 | (see libavb/avb_sysdeps.h) as well as operations that the boot loader |
David Zeuthen | baf59e2 | 2016-11-14 15:39:43 -0500 | [diff] [blame] | 31 | or OS is expected to implement (see libavb/avb_ops.h). The main entry |
| 32 | point for verification is avb_slot_verify(). |
David Zeuthen | 21e9526 | 2016-07-27 17:58:40 -0400 | [diff] [blame] | 33 | |
David Zeuthen | baf59e2 | 2016-11-14 15:39:43 -0500 | [diff] [blame] | 34 | It is expected that most devices will use A/B (e.g. multiple copies of |
| 35 | the OS in separate so-called 'slots') in addition to AVB. While |
| 36 | managing A/B metadata and associated metadata (e.g. managing |
| 37 | stored_rollback_index[n] locations) is outside the scope of libavb, |
| 38 | enough interfaces are exposed so the boot loader can integrate its A/B |
| 39 | stack with libavb. In particular avb_slot_verify() takes a |
| 40 | |slot_suffix| parameter and its result struct |AvbSlotVerifyData| |
| 41 | convey the rollback indexes in the image that was verified. |
David Zeuthen | 8b6973b | 2016-09-20 12:39:49 -0400 | [diff] [blame] | 42 | |
David Zeuthen | baf59e2 | 2016-11-14 15:39:43 -0500 | [diff] [blame] | 43 | AVB also includes an A/B implementation that boot loaders may |
| 44 | optionally use. This implementation is in the libavb_ab library and |
| 45 | integrates with image verification including updating the |
| 46 | stored_rollback_index[n] locations on the device as needed. The |
| 47 | bootloader can use this through the avb_ab_flow() function. This |
| 48 | library is built on top of libavb. |
| 49 | |
| 50 | In libavb_ab, A/B metadata is stored in the 'misc' partition using a |
| 51 | format private to libavb_ab in the location on 'misc' reserved for |
| 52 | this. For more information about the misc.img file format see the |
| 53 | bootable/recovery/bootloader.h file. A/B metadata can be written to |
| 54 | misc.img using the set_ab_metadata sub-command of avbtool. A/B |
| 55 | metadata is comprised of (for each slot) a priority field (0 to 15), |
| 56 | number of tries remaining for attempting to boot the slot (0 to 7), |
| 57 | and a flag to indicate whether the slot has successfully booted. |
David Zeuthen | 8b6973b | 2016-09-20 12:39:49 -0400 | [diff] [blame] | 58 | |
| 59 | A/B metadata integrity is provided by a simple magic marker and a |
| 60 | CRC-32 checksum. If invalid A/B metadata is detected, the behavior is |
| 61 | to reset the A/B metadata to a known state where both slots are given |
| 62 | seven boot tries. |
| 63 | |
David Zeuthen | baf59e2 | 2016-11-14 15:39:43 -0500 | [diff] [blame] | 64 | An implementation of a boot_control HAL using AVB-specific A/B |
David Zeuthen | 8b6973b | 2016-09-20 12:39:49 -0400 | [diff] [blame] | 65 | metadata is also provided. |
David Zeuthen | 21e9526 | 2016-07-27 17:58:40 -0400 | [diff] [blame] | 66 | |
| 67 | -- FILES AND DIRECTORIES |
| 68 | |
| 69 | libavb/ |
| 70 | |
David Zeuthen | baf59e2 | 2016-11-14 15:39:43 -0500 | [diff] [blame] | 71 | An implementation of image verification. This code is designed to |
| 72 | be highly portable so it can be used in as many contexts as |
| 73 | possible. This code requires a C99-compliant C compiler. |
David Zeuthen | 21e9526 | 2016-07-27 17:58:40 -0400 | [diff] [blame] | 74 | |
| 75 | Part of this code is considered internal to the implementation and |
| 76 | should not be used outside it. For example, this applies to the |
| 77 | avb_rsa.[ch] and avb_sha.[ch] files. |
| 78 | |
| 79 | System dependencies expected to be provided by the platform is |
| 80 | defined in avb_sysdeps.h. If the platform provides the standard C |
| 81 | runtime avb_sysdeps_posix.c can be used. |
| 82 | |
David Zeuthen | baf59e2 | 2016-11-14 15:39:43 -0500 | [diff] [blame] | 83 | libavb_ab/ |
| 84 | |
| 85 | An A/B implementation for use in boot loaders. This is built on top |
| 86 | of libavb. |
| 87 | |
| 88 | |
| 89 | boot_control/ |
| 90 | |
| 91 | An implemementation of the Android boot_control HAL for use with |
| 92 | boot loaders using libavb_ab. |
| 93 | |
David Zeuthen | 21e9526 | 2016-07-27 17:58:40 -0400 | [diff] [blame] | 94 | Android.mk |
| 95 | |
David Zeuthen | baf59e2 | 2016-11-14 15:39:43 -0500 | [diff] [blame] | 96 | Build instructions for building libavb (a static library for use on |
| 97 | the device), host-side libraries (for unit tests), and unit tests. |
David Zeuthen | 21e9526 | 2016-07-27 17:58:40 -0400 | [diff] [blame] | 98 | |
| 99 | avbtool |
| 100 | |
| 101 | A tool written in Python for working with images related to |
| 102 | verified boot. |
| 103 | |
| 104 | test/ |
| 105 | |
David Zeuthen | baf59e2 | 2016-11-14 15:39:43 -0500 | [diff] [blame] | 106 | Contains unit tests for abvtool, libavb, and libavb_ab. |
David Zeuthen | 21e9526 | 2016-07-27 17:58:40 -0400 | [diff] [blame] | 107 | |
| 108 | -- AUDIENCE AND PORTABILITY NOTES |
| 109 | |
| 110 | This code is intended to be used in bootloaders in devices running |
| 111 | Android. The suggested approach is to copy the appropriate header and |
| 112 | C files mentioned in the previous section into the boot loader and |
| 113 | integrate as appropriate. |
| 114 | |
David Zeuthen | baf59e2 | 2016-11-14 15:39:43 -0500 | [diff] [blame] | 115 | The libavb/ and libavb_ab/ codebase will evolve over time so |
| 116 | integration should be as non-invasive as possible. The intention is to |
| 117 | keep the API of the library stable however it will be broken if |
| 118 | necessary. |
David Zeuthen | 21e9526 | 2016-07-27 17:58:40 -0400 | [diff] [blame] | 119 | |
| 120 | As for portability, the library is intended to be highly portable, |
| 121 | work on both little- and big-endian architectures and 32- and |
| 122 | 64-bit. It's also intended to work in non-standard environments |
| 123 | without the standard C library and runtime. |
| 124 | |
| 125 | If the AVB_ENABLE_DEBUG preprocessor symbol is set, the code will |
| 126 | include useful debug information and run-time checks. Production |
| 127 | builds should not use this. |
| 128 | |
| 129 | The preprocessor symbol AVB_COMPILATION should be set only when |
David Zeuthen | baf59e2 | 2016-11-14 15:39:43 -0500 | [diff] [blame] | 130 | compiling the libraries. The code must be compiled into a separate |
| 131 | libraries. |
David Zeuthen | 21e9526 | 2016-07-27 17:58:40 -0400 | [diff] [blame] | 132 | |
David Zeuthen | baf59e2 | 2016-11-14 15:39:43 -0500 | [diff] [blame] | 133 | Applications using the compiled libavb library must only include the |
David Zeuthen | 21e9526 | 2016-07-27 17:58:40 -0400 | [diff] [blame] | 134 | libavb/libavb.h file (which will include all public interfaces) and |
| 135 | must not have the AVB_COMPILATION preprocessor symbol set. This is to |
| 136 | ensure that internal code that may be change in the future (for |
| 137 | example avb_sha.[ch] and avb_rsa.[ch]) will not be visible to |
| 138 | application code. |
| 139 | |
David Zeuthen | baf59e2 | 2016-11-14 15:39:43 -0500 | [diff] [blame] | 140 | Applications using the compiled libavb_ab library must only include |
| 141 | the libavb_ab/libavb_ab.h file for similar reasons. |
| 142 | |
David Zeuthen | 21e9526 | 2016-07-27 17:58:40 -0400 | [diff] [blame] | 143 | -- COMPATIBILITY NOTES |
| 144 | |
| 145 | The VBMeta structure (as defined in libavb/avb_vbmeta_header.h) |
| 146 | guarantees forwards- and backwards-compatibility provided the major |
| 147 | version does not change. |
| 148 | |
| 149 | When backwards-compatible changes are made - for example, when a new |
| 150 | field is added to AvbVBMetaImageHeader - the minor version will be |
| 151 | bumped. At the same time, libavb will also be modified to test for the |
| 152 | appropriate minor version before attempting to access the newly added |
| 153 | field. This ensures that version 1.N of the library is able to read an |
| 154 | old vbmeta image header produced with version 1.M where N > M. |
| 155 | |
| 156 | The usual scenario is that the code parsing the AvbVBMetaImageHeader |
| 157 | rarely changes (it's usually in the firmware of a device and this |
| 158 | firmware is rarely updated if ever), let's say it's fixed at version |
| 159 | 1.N. At the same time, the version of the avbtool used to produce the |
| 160 | vbmeta image is rolling forward and is at version 1.M where M > N. The |
| 161 | problem with this scenario is that version 1.M may easily and |
| 162 | inadvertently introduce a seemingly compatible change that isn't. For |
| 163 | example, consider if a new verification algorithm is added - in this |
| 164 | case version 1.N of the reference implementation will fail at |
| 165 | verification time when validating the |algorithm_field| of a 1.M image |
| 166 | if it's set to the new algorithm. |
| 167 | |
| 168 | The best approach for dealing with this problem is to always used a |
| 169 | pinned version of avbtool (say, use version 1.N to generate images |
| 170 | targeted for devices running version 1.N) for generating and signing |
| 171 | images but sometimes this is not always possible nor |
| 172 | desirable. Therefore, to avoid this compatibility problem, avbtool is |
| 173 | designed to always take such input as a command-line argument so it |
| 174 | can be kept constant by the caller. In other words, as long as you |
| 175 | keep your command-line options passed to the avb tool the same, images |
| 176 | produced by newer versions of avb will continue to work on the same |
| 177 | version of the reference implementation. |
| 178 | |
| 179 | -- USAGE |
| 180 | |
| 181 | The content for the vbmeta partition can be generated as follows: |
| 182 | |
| 183 | $ avbtool make_vbmeta_image \ |
| 184 | --output OUTPUT \ |
David Zeuthen | 18666ab | 2016-11-15 11:18:05 -0500 | [diff] [blame] | 185 | [--algorithm ALGORITHM] [--key /path/to/key_used_for_signing] \ |
| 186 | [--public_key_metadata /path/to/pkmd.bin] [--rollback_index NUMBER] \ |
David Zeuthen | 21e9526 | 2016-07-27 17:58:40 -0400 | [diff] [blame] | 187 | [--include_descriptors_from_footer /path/to/image.bin] \ |
| 188 | [--generate_dm_verity_cmdline_from_footer /path/to/image.bin] \ |
| 189 | [--chain_partition part_name:rollback_index_slot:/path/to/key1.bin] |
| 190 | |
| 191 | An integrity footer containing the hash for an entire partition can be |
| 192 | added to an existing image as follows: |
| 193 | |
David Zeuthen | 18666ab | 2016-11-15 11:18:05 -0500 | [diff] [blame] | 194 | $ avbtool add_hash_footer \ |
| 195 | --image IMAGE \ |
| 196 | --partition_name PARTNAME --partition_size SIZE \ |
| 197 | [--algorithm ALGORITHM] [--key /path/to/key_used_for_signing] \ |
| 198 | [--public_key_metadata /path/to/pkmd.bin] [--rollback_index NUMBER] \ |
| 199 | [--hash_algorithm HASH_ALG] [--salt HEX] \ |
| 200 | [--include_descriptors_from_footer /path/to/image.bin] \ |
David Zeuthen | 21e9526 | 2016-07-27 17:58:40 -0400 | [diff] [blame] | 201 | [--generate_dm_verity_cmdline_from_footer /path/to/image.bin] |
| 202 | |
| 203 | An integrity footer containing the root digest and salt for a hashtree |
| 204 | for a partition can be added to an existing image as follows. The |
| 205 | hashtree is also appended to the image. |
| 206 | |
David Zeuthen | 18666ab | 2016-11-15 11:18:05 -0500 | [diff] [blame] | 207 | $ avbtool add_hashtree_footer \ |
| 208 | --image IMAGE \ |
| 209 | --partition_name PARTNAME --partition_size SIZE \ |
| 210 | [--algorithm ALGORITHM] [--key /path/to/key_used_for_signing] \ |
| 211 | [--public_key_metadata /path/to/pkmd.bin] [--rollback_index NUMBER] \ |
| 212 | [--hash_algorithm HASH_ALG] [--salt HEX] [--block_size SIZE] \ |
| 213 | [--include_descriptors_from_footer /path/to/image.bin] \ |
David Zeuthen | 21e9526 | 2016-07-27 17:58:40 -0400 | [diff] [blame] | 214 | [--generate_dm_verity_cmdline_from_footer /path/to/image.bin] |
| 215 | |
| 216 | The integrity footer on an image can be removed from an image. The |
| 217 | hashtree can optionally be kept in place. |
| 218 | |
| 219 | $ avbtool erase_footer --image IMAGE [--keep_hashtree] |
| 220 | |
David Zeuthen | 0969269 | 2016-09-30 16:16:40 -0400 | [diff] [blame] | 221 | To calculate the maximum size of an image that will fit in a partition |
| 222 | of a given size after having used the 'avbtool add_hashtree_footer' |
| 223 | command on it, use the --calc_max_image_size option: |
| 224 | |
| 225 | $ avbtool add_hashtree_footer --partition_size $((10*1024*1024)) \ |
| 226 | --calc_max_image_size |
| 227 | 10330112 |
| 228 | |
David Zeuthen | 21e9526 | 2016-07-27 17:58:40 -0400 | [diff] [blame] | 229 | -- BUILD SYSTEM INTEGRATION NOTES |
| 230 | |
| 231 | Android Verified Boot is enabled by the BOARD_AVB_ENABLE variable |
| 232 | |
| 233 | BOARD_AVB_ENABLE := true |
| 234 | |
| 235 | This will make the build system create vbmeta.img which will contain a |
| 236 | hash descriptor for boot.img, a hashtree descriptor for system.img, a |
| 237 | kernel-cmdline descriptor for setting up dm-verity for system.img and |
| 238 | append a hash-tree to system.img. |
| 239 | |
| 240 | By default, the algorithm SHA256_RSA4096 is used with a test key from |
| 241 | this directory. This can be overriden by the BOARD_AVB_ALGORITHM and |
David Zeuthen | a4fee8b | 2016-08-22 15:20:43 -0400 | [diff] [blame] | 242 | BOARD_AVB_KEY_PATH variables to use e.g. a 4096-bit RSA key and |
| 243 | SHA-512: |
David Zeuthen | 21e9526 | 2016-07-27 17:58:40 -0400 | [diff] [blame] | 244 | |
| 245 | BOARD_AVB_ALGORITHM := SHA512_RSA4096 |
| 246 | BOARD_AVB_KEY_PATH := /path/to/rsa_key_4096bits.pem |
| 247 | |
David Zeuthen | 18666ab | 2016-11-15 11:18:05 -0500 | [diff] [blame] | 248 | Remember that the public part of this key needs to be available to the |
| 249 | bootloader of the device expected to verify resulting images. Use |
| 250 | 'avbtool extract_public_key' to extract the key in the expected format |
| 251 | ("AVB_pk" in the following). If the device is using a different root |
| 252 | of trust than AVB_pk the --public_key_metadata option can be used to |
| 253 | embed a blob ("AVB_pkmd" in the following) that can be used to |
| 254 | e.g. derive AVB_pk. Both AVB_pk and AVB_pkmd is passed to the |
| 255 | bootloader for validation as part of verifying a slot. |
David Zeuthen | 21e9526 | 2016-07-27 17:58:40 -0400 | [diff] [blame] | 256 | |
| 257 | To prevent rollback attakcs, the rollback index should be increased on |
| 258 | a regular basis. The rollback index can be set with the |
| 259 | BOARD_AVB_ROLLBACK_INDEX variable: |
| 260 | |
| 261 | BOARD_AVB_ROLLBACK_INDEX := 5 |
| 262 | |
| 263 | If this is not set, the rollback index defaults to 0. |
| 264 | |
David Zeuthen | a4fee8b | 2016-08-22 15:20:43 -0400 | [diff] [blame] | 265 | The variable BOARD_AVB_MAKE_VBMETA_IMAGE_ARGS can be used to specify |
| 266 | additional options passed to 'avbtool make_vbmeta_image'. Typical |
| 267 | options to be used here include '--prop', '--prop_from_file', and |
| 268 | '--chain_partition'. |
| 269 | |
| 270 | The variable BOARD_AVBTOOL_BOOT_ADD_HASH_FOOTER_ARGS can be used to |
| 271 | specify additional options passed to 'avbtool add_hash_footer' for |
| 272 | boot.img. Typical options to be used here include '--hash_algorithm' |
| 273 | and '--salt'. |
| 274 | |
| 275 | The variable BOARD_AVBTOOL_SYSTEM_ADD_HASHTREE_FOOTER_ARGS can be used |
| 276 | to specify additional options passed to 'avbtool add_hashtree_footer' |
| 277 | for systems.img. Typical options to be used here include |
| 278 | '--hash_algorithm', '--salt', and '--block_size'. |