Contains: 1. Overview of Android Verified Boot 2.0 2. Description of avb subset of commands 3. Examples of errors when boot/vendor/system/vbmeta partitions are tampered 4. Examples of enabling AVB2.0 on your setup
Signed-off-by: Igor Opaniuk igor.opaniuk@linaro.org --- doc/README.avb2 | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 doc/README.avb2
diff --git a/doc/README.avb2 b/doc/README.avb2 new file mode 100644 index 0000000..67784b5 --- /dev/null +++ b/doc/README.avb2 @@ -0,0 +1,97 @@ +Android Verified Boot 2.0 + +This file contains information about the current support of Android Verified +Boot 2.0 in U-boot + +1. OVERVIEW +--------------------------------- +Verified Boot establishes a chain of trust from the bootloader to system images +* Provides integrity checking for: + - Android Boot image: Linux kernel + ramdisk. RAW hashing of the whole + partition is done and the hash is compared with the one stored in + the VBMeta image + - system/vendor partitions: verifying root hash of dm-verity hashtrees. +* Provides capabilities for rollback protection. + +Integrity of the bootloader (U-boot BLOB and environment) is out of scope. + +For additional details check: +https://android.googlesource.com/platform/external/avb/+/master/README.md + + +2. AVB 2.0 U-BOOT SHELL COMMANDS +----------------------------------- +Provides CLI interface to invoke AVB 2.0 verification + misc. commands for +different testing purposes: + +avb init <dev> - initialize avb 2.0 for <dev> +avb verify - run verification process using hash data from vbmeta structure +avb read_rb <num> - read rollback index at location <num> +avb write_rb <num> <rb> - write rollback index <rb> to <num> +avb is_unlocked - returns unlock status of the device +avb get_uuid <partname> - read and print uuid of partition <partname> +avb read_part <partname> <offset> <num> <addr> - read <num> bytes from +partition <partname> to buffer <addr> +avb write_part <partname> <offset> <num> <addr> - write <num> bytes to +<partname> by <offset> using data from <addr> + + +3. PARTITIONS TAMPERING (EXAMPLE) +----------------------------------- +Boot or system/vendor (dm-verity metadata section) is tampered: +=> avb init 1 +=> avb verify +avb_slot_verify.c:175: ERROR: boot: Hash of data does not match digest in +descriptor. +Slot verification result: ERROR_IO + +Vbmeta partition is tampered: +=> avb init 1 +=> avb verify +avb_vbmeta_image.c:206: ERROR: Hash does not match! +avb_slot_verify.c:388: ERROR: vbmeta: Error verifying vbmeta image: +HASH_MISMATCH +Slot verification result: ERROR_IO + + +4. ENABLE ON YOUR BOARD +----------------------------------- +The following options must be enabled: +CONFIG_LIBAVB=y +CONFIG_CMD_AVB=y + + +Then add `avb verify` invocation to your android boot sequence of commands, +e.g.: + +=> avb_verify=avb init $mmcdev; avb verify; +=> if run avb_verify; then \ + echo AVB verification OK. Continue boot; \ + set bootargs $bootargs $avb_bootargs; \ + else \ + echo AVB verification failed; \ + exit; \ + fi; \ + +=> emmc_android_boot= \ + echo Trying to boot Android from eMMC ...; \ + ... \ + run avb_verify; \ + mmc read ${fdtaddr} ${fdt_start} ${fdt_size}; \ + mmc read ${loadaddr} ${boot_start} ${boot_size}; \ + bootm $loadaddr $loadaddr $fdtaddr; \ + + +To switch on automatic generation of vbmeta partition in AOSP build, add these +lines to device configuration mk file: + +BOARD_AVB_ENABLE := true +BOARD_AVB_ALGORITHM := SHA512_RSA4096 +BOARD_BOOTIMAGE_PARTITION_SIZE := <boot partition size> + +After flashing U-boot don't forget to update environment and write new +partition table: +=> env default -f -a +=> setenv partitions $partitions_android +=> env save +=> gpt write mmc 1 $partitions_android