1.. SPDX-License-Identifier: GPL-2.0+
2
3Android Verified Boot 2.0
4=========================
5
6This file contains information about the current support of Android Verified
7Boot 2.0 in U-Boot.
8
9Overview
10--------
11
12Verified Boot establishes a chain of trust from the bootloader to system images:
13
14* Provides integrity checking for:
15
16  * Android Boot image: Linux kernel + ramdisk. RAW hashing of the whole
17    partition is done and the hash is compared with the one stored in
18    the VBMeta image
19  * ``system``/``vendor`` partitions: verifying root hash of dm-verity hashtrees
20
21* Provides capabilities for rollback protection
22
23Integrity of the bootloader (U-Boot BLOB and environment) is out of scope.
24
25For additional details check [1]_.
26
27AVB using OP-TEE (optional)
28^^^^^^^^^^^^^^^^^^^^^^^^^^^
29
30If AVB is configured to use OP-TEE (see `Enable on your board`_) rollback
31indexes and device lock state are stored in RPMB. The RPMB partition is managed
32by OP-TEE (see [2]_ for details) which is a secure OS leveraging ARM
33TrustZone.
34
35AVB 2.0 U-Boot shell commands
36-----------------------------
37
38Provides CLI interface to invoke AVB 2.0 verification + misc. commands for
39different testing purposes::
40
41    avb init <dev> - initialize avb 2.0 for <dev>
42    avb verify - run verification process using hash data from vbmeta structure
43    avb read_rb <num> - read rollback index at location <num>
44    avb write_rb <num> <rb> - write rollback index <rb> to <num>
45    avb is_unlocked - returns unlock status of the device
46    avb get_uuid <partname> - read and print uuid of partition <partname>
47    avb read_part <partname> <offset> <num> <addr> - read <num> bytes from
48    partition <partname> to buffer <addr>
49    avb write_part <partname> <offset> <num> <addr> - write <num> bytes to
50    <partname> by <offset> using data from <addr>
51
52Partitions tampering (example)
53------------------------------
54
55Boot or system/vendor (dm-verity metadata section) is tampered::
56
57   => avb init 1
58   => avb verify
59   avb_slot_verify.c:175: ERROR: boot: Hash of data does not match digest in
60   descriptor.
61   Slot verification result: ERROR_IO
62
63Vbmeta partition is tampered::
64
65   => avb init 1
66   => avb verify
67   avb_vbmeta_image.c:206: ERROR: Hash does not match!
68   avb_slot_verify.c:388: ERROR: vbmeta: Error verifying vbmeta image:
69   HASH_MISMATCH
70   Slot verification result: ERROR_IO
71
72Enable on your board
73--------------------
74
75The following options must be enabled::
76
77   CONFIG_LIBAVB=y
78   CONFIG_AVB_VERIFY=y
79   CONFIG_CMD_AVB=y
80
81In addtion optionally if storing rollback indexes in RPMB with help of
82OP-TEE::
83
84   CONFIG_TEE=y
85   CONFIG_OPTEE=y
86   CONFIG_OPTEE_TA_AVB=y
87   CONFIG_SUPPORT_EMMC_RPMB=y
88
89Then add ``avb verify`` invocation to your android boot sequence of commands,
90e.g.::
91
92   => avb_verify=avb init $mmcdev; avb verify;
93   => if run avb_verify; then                       \
94           echo AVB verification OK. Continue boot; \
95           set bootargs $bootargs $avb_bootargs;    \
96      else                                          \
97           echo AVB verification failed;            \
98           exit;                                    \
99      fi;                                           \
100
101   => emmc_android_boot=                                   \
102          echo Trying to boot Android from eMMC ...;       \
103          ...                                              \
104          run avb_verify;                                  \
105          mmc read ${fdtaddr} ${fdt_start} ${fdt_size};    \
106          mmc read ${loadaddr} ${boot_start} ${boot_size}; \
107               bootm $loadaddr $loadaddr $fdtaddr;         \
108
109If partitions you want to verify are slotted (have A/B suffixes), then current
110slot suffix should be passed to ``avb verify`` sub-command, e.g.::
111
112   => avb verify _a
113
114To switch on automatic generation of vbmeta partition in AOSP build, add these
115lines to device configuration mk file::
116
117   BOARD_AVB_ENABLE := true
118   BOARD_AVB_ALGORITHM := SHA512_RSA4096
119   BOARD_BOOTIMAGE_PARTITION_SIZE := <boot partition size>
120
121After flashing U-Boot don't forget to update environment and write new
122partition table::
123
124   => env default -f -a
125   => setenv partitions $partitions_android
126   => env save
127   => gpt write mmc 1 $partitions_android
128
129References
130----------
131
132.. [1] https://android.googlesource.com/platform/external/avb/+/master/README.md
133.. [2] https://www.op-tee.org/
134