doc/README.avb2

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