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
  22 2. AVB 2.0 U-BOOT SHELL COMMANDS
  23 -----------------------------------
  24 Provides CLI interface to invoke AVB 2.0 verification + misc. commands for
  25 different testing purposes:
  26
  27 avb init <dev> - initialize avb 2.0 for <dev>
  28 avb verify - run verification process using hash data from vbmeta structure
  29 avb read_rb <num> - read rollback index at location <num>
  30 avb write_rb <num> <rb> - write rollback index <rb> to <num>
  31 avb is_unlocked - returns unlock status of the device
  32 avb get_uuid <partname> - read and print uuid of partition <partname>
  33 avb read_part <partname> <offset> <num> <addr> - read <num> bytes from
  34 partition <partname> to buffer <addr>
  35 avb write_part <partname> <offset> <num> <addr> - write <num> bytes to
  36 <partname> by <offset> using data from <addr>
  37
  38
  39 3. PARTITIONS TAMPERING (EXAMPLE)
  40 -----------------------------------
  41 Boot or system/vendor (dm-verity metadata section) is tampered:
  42 => avb init 1
  43 => avb verify
  44 avb_slot_verify.c:175: ERROR: boot: Hash of data does not match digest in
  45 descriptor.
  46 Slot verification result: ERROR_IO
  47
  48 Vbmeta partition is tampered:
  49 => avb init 1
  50 => avb verify
  51 avb_vbmeta_image.c:206: ERROR: Hash does not match!
  52 avb_slot_verify.c:388: ERROR: vbmeta: Error verifying vbmeta image:
  53 HASH_MISMATCH
  54 Slot verification result: ERROR_IO
  55
  56
  57 4. ENABLE ON YOUR BOARD
  58 -----------------------------------
  59 The following options must be enabled:
  60 CONFIG_LIBAVB=y
  61 CONFIG_AVB_VERIFY=y
  62 CONFIG_CMD_AVB=y
  63
  64
  65 Then add `avb verify` invocation to your android boot sequence of commands,
  66 e.g.:
  67
  68 => avb_verify=avb init $mmcdev; avb verify;
  69 => if run avb_verify; then                       \
  70         echo AVB verification OK. Continue boot; \
  71         set bootargs $bootargs $avb_bootargs;    \
  72    else                                          \
  73         echo AVB verification failed;            \
  74         exit;                                    \
  75    fi;                                           \
  76
  77 => emmc_android_boot=                                   \
  78        echo Trying to boot Android from eMMC ...;       \
  79        ...                                              \
  80        run avb_verify;                                  \
  81        mmc read ${fdtaddr} ${fdt_start} ${fdt_size};    \
  82        mmc read ${loadaddr} ${boot_start} ${boot_size}; \
  83        bootm $loadaddr $loadaddr $fdtaddr;              \
  84
  85
  86 To switch on automatic generation of vbmeta partition in AOSP build, add these
  87 lines to device configuration mk file:
  88
  89 BOARD_AVB_ENABLE := true
  90 BOARD_AVB_ALGORITHM := SHA512_RSA4096
  91 BOARD_BOOTIMAGE_PARTITION_SIZE := <boot partition size>
  92
  93 After flashing U-boot don't forget to update environment and write new
  94 partition table:
  95 => env default -f -a
  96 => setenv partitions $partitions_android
  97 => env save
  98 => gpt write mmc 1 $partitions_android