diff options
Diffstat (limited to 'doc/android/avb2.rst')
| -rw-r--r-- | doc/android/avb2.rst | 133 |
1 files changed, 133 insertions, 0 deletions
diff --git a/doc/android/avb2.rst b/doc/android/avb2.rst new file mode 100644 index 0000000000..a072119574 --- /dev/null +++ b/doc/android/avb2.rst @@ -0,0 +1,133 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Android Verified Boot 2.0 +========================= + +This file contains information about the current support of Android Verified +Boot 2.0 in U-Boot. + +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 [1]_. + +AVB using OP-TEE (optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If AVB is configured to use OP-TEE (see `Enable on your board`_) rollback +indexes and device lock state are stored in RPMB. The RPMB partition is managed +by OP-TEE (see [2]_ for details) which is a secure OS leveraging ARM +TrustZone. + +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> + +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 + +Enable on your board +-------------------- + +The following options must be enabled:: + + CONFIG_LIBAVB=y + CONFIG_AVB_VERIFY=y + CONFIG_CMD_AVB=y + +In addtion optionally if storing rollback indexes in RPMB with help of +OP-TEE:: + + CONFIG_TEE=y + CONFIG_OPTEE=y + CONFIG_OPTEE_TA_AVB=y + CONFIG_SUPPORT_EMMC_RPMB=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; \ + +If partitions you want to verify are slotted (have A/B suffixes), then current +slot suffix should be passed to ``avb verify`` sub-command, e.g.:: + + => avb verify _a + +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 + +References +---------- + +.. [1] https://android.googlesource.com/platform/external/avb/+/master/README.md +.. [2] https://www.op-tee.org/ |