--- /dev/null
+.. 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/
projects / oweals / u-boot.git / blobdiff