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