doc/android/avb2.rst

   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/