| This directory contains avbtool and libavb. |
| |
| The main job of avbtool is to create vbmeta.img which is the |
| top-level object for verified boot. This image is designed to go into |
| the vbmeta partition (or, if using A/B, the slot in question |
| e.g. vbmeta_a or vbmeta_b) and be of minimal size (for out-of-band |
| updates). The vbmeta image is cryptographically signed and contains |
| verification data (e.g. cryptographic digests) for verifying boot.img, |
| system.img, and other partitions/images. |
| |
| The vbmeta image can also contain references to other partitions where |
| verification data is stored as well as a public key indicating who |
| should sign the verification data. This indirection provides |
| delegation, that is, it allows a 3rd party to control content on a given |
| partition by including the public key said 3rd party is using to sign |
| the data with, in vbmeta.img. By design, this authority can be easily |
| revoked by simply updating vbmeta.img with new descriptors for the |
| partition in question. |
| |
| Storing signed verification data on other images - for example |
| boot.img and system.img - is also done with avbtool. |
| |
| In addition to avbtool, a library - libavb - is provided. This library |
| performs all verification on the device side e.g. it starts by loading |
| the vbmeta partition, checks the signature, and then goes on to load |
| the boot partition for verification. |
| |
| The libavb library is intended to be used in both boot loaders and |
| inside Android. It has a simple abstraction for system dependencies |
| (see libavb/avb_sysdeps.h) as well as operations that the boot loader |
| or OS is expected to implement (see libavb/avb_ops.h). |
| |
| In addition to handling verified boot, libavb also takes care of A/B |
| selection including managing rollback indexes. The bootloader can use |
| this through the avb_ab_flow() function. |
| |
| A/B metadata is stored in the 'misc' partition in the |slot_suffix| |
| field using a format private to libavb. For more information about the |
| misc.img file format see the bootable/recovery/bootloader.h file. A/B |
| metadata can be written to misc.img using the set_ab_metadata |
| sub-command. A/B metadata is comprised of (for each slot) a priority |
| field (0 to 15), number of tries remaining for attempting to boot the |
| slot (0 to 7), and a flag to indicate whether the slot has |
| successfully booted. |
| |
| A/B metadata integrity is provided by a simple magic marker and a |
| CRC-32 checksum. If invalid A/B metadata is detected, the behavior is |
| to reset the A/B metadata to a known state where both slots are given |
| seven boot tries. |
| |
| An implementation of the boot_control HAL using AVB-specific A/B |
| metadata is also provided. |
| |
| -- FILES AND DIRECTORIES |
| |
| libavb/ |
| |
| An implementation for image verification and A/B selection. This |
| code is designed to be highly portable so it can be used in as many |
| contexts as possible. This code requires a C99-compliant C |
| compiler. |
| |
| Part of this code is considered internal to the implementation and |
| should not be used outside it. For example, this applies to the |
| avb_rsa.[ch] and avb_sha.[ch] files. |
| |
| System dependencies expected to be provided by the platform is |
| defined in avb_sysdeps.h. If the platform provides the standard C |
| runtime avb_sysdeps_posix.c can be used. |
| |
| Android.mk |
| |
| Build instructions for building libavb_host (for unit tests), |
| libavb (for use on the device) and associated unit tests. |
| |
| avbtool |
| |
| A tool written in Python for working with images related to |
| verified boot. |
| |
| test/ |
| |
| Contains unit tests for abvtool and libavb. |
| |
| -- AUDIENCE AND PORTABILITY NOTES |
| |
| This code is intended to be used in bootloaders in devices running |
| Android. The suggested approach is to copy the appropriate header and |
| C files mentioned in the previous section into the boot loader and |
| integrate as appropriate. |
| |
| The libavb/ codebase will evolve over time so integration should be as |
| non-invasive as possible. The intention is to keep the API of the |
| library stable however it will be broken if necessary. |
| |
| As for portability, the library is intended to be highly portable, |
| work on both little- and big-endian architectures and 32- and |
| 64-bit. It's also intended to work in non-standard environments |
| without the standard C library and runtime. |
| |
| If the AVB_ENABLE_DEBUG preprocessor symbol is set, the code will |
| include useful debug information and run-time checks. Production |
| builds should not use this. |
| |
| The preprocessor symbol AVB_COMPILATION should be set only when |
| compiling the library. The code must be compiled into a separate |
| library. |
| |
| Applications using the compiled library must only include the |
| libavb/libavb.h file (which will include all public interfaces) and |
| must not have the AVB_COMPILATION preprocessor symbol set. This is to |
| ensure that internal code that may be change in the future (for |
| example avb_sha.[ch] and avb_rsa.[ch]) will not be visible to |
| application code. |
| |
| -- COMPATIBILITY NOTES |
| |
| The VBMeta structure (as defined in libavb/avb_vbmeta_header.h) |
| guarantees forwards- and backwards-compatibility provided the major |
| version does not change. |
| |
| When backwards-compatible changes are made - for example, when a new |
| field is added to AvbVBMetaImageHeader - the minor version will be |
| bumped. At the same time, libavb will also be modified to test for the |
| appropriate minor version before attempting to access the newly added |
| field. This ensures that version 1.N of the library is able to read an |
| old vbmeta image header produced with version 1.M where N > M. |
| |
| The usual scenario is that the code parsing the AvbVBMetaImageHeader |
| rarely changes (it's usually in the firmware of a device and this |
| firmware is rarely updated if ever), let's say it's fixed at version |
| 1.N. At the same time, the version of the avbtool used to produce the |
| vbmeta image is rolling forward and is at version 1.M where M > N. The |
| problem with this scenario is that version 1.M may easily and |
| inadvertently introduce a seemingly compatible change that isn't. For |
| example, consider if a new verification algorithm is added - in this |
| case version 1.N of the reference implementation will fail at |
| verification time when validating the |algorithm_field| of a 1.M image |
| if it's set to the new algorithm. |
| |
| The best approach for dealing with this problem is to always used a |
| pinned version of avbtool (say, use version 1.N to generate images |
| targeted for devices running version 1.N) for generating and signing |
| images but sometimes this is not always possible nor |
| desirable. Therefore, to avoid this compatibility problem, avbtool is |
| designed to always take such input as a command-line argument so it |
| can be kept constant by the caller. In other words, as long as you |
| keep your command-line options passed to the avb tool the same, images |
| produced by newer versions of avb will continue to work on the same |
| version of the reference implementation. |
| |
| -- USAGE |
| |
| The content for the vbmeta partition can be generated as follows: |
| |
| $ avbtool make_vbmeta_image \ |
| --output OUTPUT \ |
| [--algorithm ALGORITHM] [--key /path/to/key_used_for_signing.bin] \ |
| [--rollback_index NUMBER] \ |
| [--include_descriptors_from_footer /path/to/image.bin] \ |
| [--generate_dm_verity_cmdline_from_footer /path/to/image.bin] \ |
| [--chain_partition part_name:rollback_index_slot:/path/to/key1.bin] |
| |
| An integrity footer containing the hash for an entire partition can be |
| added to an existing image as follows: |
| |
| $ avbtool add_hash_footer \ |
| --image IMAGE \ |
| --partition_name PARTNAME --partition_size SIZE \ |
| [--rollback_index NUMBER] \ |
| [--algorithm ALGORITHM] [--key /path/to/key_used_for_signing.bin] \ |
| [--hash_algorithm HASH_ALG] [--salt HEX] \ |
| [--include_descriptors_from_footer /path/to/image.bin] \ |
| [--generate_dm_verity_cmdline_from_footer /path/to/image.bin] |
| |
| An integrity footer containing the root digest and salt for a hashtree |
| for a partition can be added to an existing image as follows. The |
| hashtree is also appended to the image. |
| |
| $ avbtool add_hashtree_footer \ |
| --image IMAGE \ |
| --partition_name PARTNAME --partition_size SIZE \ |
| [--rollback_index NUMBER] \ |
| [--algorithm ALGORITHM] [--key /path/to/key_used_for_signing.bin] \ |
| [--hash_algorithm HASH_ALG] [--salt HEX] [--block_size SIZE] \ |
| [--include_descriptors_from_footer /path/to/image.bin] \ |
| [--generate_dm_verity_cmdline_from_footer /path/to/image.bin] |
| |
| The integrity footer on an image can be removed from an image. The |
| hashtree can optionally be kept in place. |
| |
| $ avbtool erase_footer --image IMAGE [--keep_hashtree] |
| |
| To calculate the maximum size of an image that will fit in a partition |
| of a given size after having used the 'avbtool add_hashtree_footer' |
| command on it, use the --calc_max_image_size option: |
| |
| $ avbtool add_hashtree_footer --partition_size $((10*1024*1024)) \ |
| --calc_max_image_size |
| 10330112 |
| |
| -- BUILD SYSTEM INTEGRATION NOTES |
| |
| Android Verified Boot is enabled by the BOARD_AVB_ENABLE variable |
| |
| BOARD_AVB_ENABLE := true |
| |
| This will make the build system create vbmeta.img which will contain a |
| hash descriptor for boot.img, a hashtree descriptor for system.img, a |
| kernel-cmdline descriptor for setting up dm-verity for system.img and |
| append a hash-tree to system.img. |
| |
| By default, the algorithm SHA256_RSA4096 is used with a test key from |
| this directory. This can be overriden by the BOARD_AVB_ALGORITHM and |
| BOARD_AVB_KEY_PATH variables to use e.g. a 4096-bit RSA key and |
| SHA-512: |
| |
| BOARD_AVB_ALGORITHM := SHA512_RSA4096 |
| BOARD_AVB_KEY_PATH := /path/to/rsa_key_4096bits.pem |
| |
| Remember that the public part of this key needs to be embedded in the |
| bootloader of the device expected to process resulting images. Use |
| 'avbtool extract_public_key' to do this. |
| |
| To prevent rollback attakcs, the rollback index should be increased on |
| a regular basis. The rollback index can be set with the |
| BOARD_AVB_ROLLBACK_INDEX variable: |
| |
| BOARD_AVB_ROLLBACK_INDEX := 5 |
| |
| If this is not set, the rollback index defaults to 0. |
| |
| The variable BOARD_AVB_MAKE_VBMETA_IMAGE_ARGS can be used to specify |
| additional options passed to 'avbtool make_vbmeta_image'. Typical |
| options to be used here include '--prop', '--prop_from_file', and |
| '--chain_partition'. |
| |
| The variable BOARD_AVBTOOL_BOOT_ADD_HASH_FOOTER_ARGS can be used to |
| specify additional options passed to 'avbtool add_hash_footer' for |
| boot.img. Typical options to be used here include '--hash_algorithm' |
| and '--salt'. |
| |
| The variable BOARD_AVBTOOL_SYSTEM_ADD_HASHTREE_FOOTER_ARGS can be used |
| to specify additional options passed to 'avbtool add_hashtree_footer' |
| for systems.img. Typical options to be used here include |
| '--hash_algorithm', '--salt', and '--block_size'. |