Sam Protsenko | cd43fa1 | 2020-01-24 17:53:44 +0200 | [diff] [blame] | 1 | .. SPDX-License-Identifier: GPL-2.0+ |
| 2 | |
| 3 | Android Verified Boot 2.0 |
| 4 | ========================= |
| 5 | |
| 6 | This file contains information about the current support of Android Verified |
| 7 | Boot 2.0 in U-Boot. |
| 8 | |
| 9 | Overview |
| 10 | -------- |
| 11 | |
| 12 | Verified 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 | |
| 23 | Integrity of the bootloader (U-Boot BLOB and environment) is out of scope. |
| 24 | |
| 25 | For additional details check [1]_. |
| 26 | |
| 27 | AVB using OP-TEE (optional) |
| 28 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 29 | |
| 30 | If AVB is configured to use OP-TEE (see `Enable on your board`_) rollback |
| 31 | indexes and device lock state are stored in RPMB. The RPMB partition is managed |
| 32 | by OP-TEE (see [2]_ for details) which is a secure OS leveraging ARM |
| 33 | TrustZone. |
| 34 | |
| 35 | AVB 2.0 U-Boot shell commands |
| 36 | ----------------------------- |
| 37 | |
| 38 | Provides CLI interface to invoke AVB 2.0 verification + misc. commands for |
| 39 | different 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 | |
| 52 | Partitions tampering (example) |
| 53 | ------------------------------ |
| 54 | |
| 55 | Boot 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 | |
| 63 | Vbmeta 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 | |
| 72 | Enable on your board |
| 73 | -------------------- |
| 74 | |
| 75 | The following options must be enabled:: |
| 76 | |
| 77 | CONFIG_LIBAVB=y |
| 78 | CONFIG_AVB_VERIFY=y |
| 79 | CONFIG_CMD_AVB=y |
| 80 | |
| 81 | In addtion optionally if storing rollback indexes in RPMB with help of |
| 82 | OP-TEE:: |
| 83 | |
| 84 | CONFIG_TEE=y |
| 85 | CONFIG_OPTEE=y |
| 86 | CONFIG_OPTEE_TA_AVB=y |
| 87 | CONFIG_SUPPORT_EMMC_RPMB=y |
| 88 | |
| 89 | Then add ``avb verify`` invocation to your android boot sequence of commands, |
| 90 | e.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 | |
| 109 | If partitions you want to verify are slotted (have A/B suffixes), then current |
| 110 | slot suffix should be passed to ``avb verify`` sub-command, e.g.:: |
| 111 | |
| 112 | => avb verify _a |
| 113 | |
| 114 | To switch on automatic generation of vbmeta partition in AOSP build, add these |
| 115 | lines 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 | |
| 121 | After flashing U-Boot don't forget to update environment and write new |
| 122 | partition table:: |
| 123 | |
| 124 | => env default -f -a |
| 125 | => setenv partitions $partitions_android |
| 126 | => env save |
| 127 | => gpt write mmc 1 $partitions_android |
| 128 | |
| 129 | References |
| 130 | ---------- |
| 131 | |
| 132 | .. [1] https://android.googlesource.com/platform/external/avb/+/master/README.md |
| 133 | .. [2] https://www.op-tee.org/ |