doc: relocate/rename Android README and add BCB overview

[oweals/u-boot.git] / doc / android / avb2.txt

diff --git a/doc/android/avb2.txt b/doc/android/avb2.txt
new file mode 100644 (file)
index 0000000..a29cee1
--- /dev/null
+++ b/doc/android/avb2.txt
@@ -0,0 +1,111 @@
+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
+
+1.1. AVB using OP-TEE (optional)
+---------------------------------
+If AVB is configured to use OP-TEE (see 4. below) rollback indexes and
+device lock state are stored in RPMB. The RPMB partition is managed by
+OP-TEE (https://www.op-tee.org/) which is a secure OS leveraging ARM
+TrustZone.
+
+
+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_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;              \
+
+
+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