avb2.rst 4.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133
  1. .. SPDX-License-Identifier: GPL-2.0+
  2. Android Verified Boot 2.0
  3. =========================
  4. This file contains information about the current support of Android Verified
  5. Boot 2.0 in U-Boot.
  6. 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. Integrity of the bootloader (U-Boot BLOB and environment) is out of scope.
  16. For additional details check [1]_.
  17. AVB using OP-TEE (optional)
  18. ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  19. If AVB is configured to use OP-TEE (see `Enable on your board`_) rollback
  20. indexes and device lock state are stored in RPMB. The RPMB partition is managed
  21. by OP-TEE (see [2]_ for details) which is a secure OS leveraging ARM
  22. TrustZone.
  23. AVB 2.0 U-Boot shell commands
  24. -----------------------------
  25. Provides CLI interface to invoke AVB 2.0 verification + misc. commands for
  26. different testing purposes::
  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. Partitions tampering (example)
  38. ------------------------------
  39. Boot or system/vendor (dm-verity metadata section) is tampered::
  40. => avb init 1
  41. => avb verify
  42. avb_slot_verify.c:175: ERROR: boot: Hash of data does not match digest in
  43. descriptor.
  44. Slot verification result: ERROR_IO
  45. Vbmeta partition is tampered::
  46. => avb init 1
  47. => avb verify
  48. avb_vbmeta_image.c:206: ERROR: Hash does not match!
  49. avb_slot_verify.c:388: ERROR: vbmeta: Error verifying vbmeta image:
  50. HASH_MISMATCH
  51. Slot verification result: ERROR_IO
  52. Enable on your board
  53. --------------------
  54. The following options must be enabled::
  55. CONFIG_LIBAVB=y
  56. CONFIG_AVB_VERIFY=y
  57. CONFIG_CMD_AVB=y
  58. In addtion optionally if storing rollback indexes in RPMB with help of
  59. OP-TEE::
  60. CONFIG_TEE=y
  61. CONFIG_OPTEE=y
  62. CONFIG_OPTEE_TA_AVB=y
  63. CONFIG_SUPPORT_EMMC_RPMB=y
  64. Then add ``avb verify`` invocation to your android boot sequence of commands,
  65. e.g.::
  66. => avb_verify=avb init $mmcdev; avb verify;
  67. => if run avb_verify; then \
  68. echo AVB verification OK. Continue boot; \
  69. set bootargs $bootargs $avb_bootargs; \
  70. else \
  71. echo AVB verification failed; \
  72. exit; \
  73. fi; \
  74. => emmc_android_boot= \
  75. echo Trying to boot Android from eMMC ...; \
  76. ... \
  77. run avb_verify; \
  78. mmc read ${fdtaddr} ${fdt_start} ${fdt_size}; \
  79. mmc read ${loadaddr} ${boot_start} ${boot_size}; \
  80. bootm $loadaddr $loadaddr $fdtaddr; \
  81. If partitions you want to verify are slotted (have A/B suffixes), then current
  82. slot suffix should be passed to ``avb verify`` sub-command, e.g.::
  83. => avb verify _a
  84. To switch on automatic generation of vbmeta partition in AOSP build, add these
  85. lines to device configuration mk file::
  86. BOARD_AVB_ENABLE := true
  87. BOARD_AVB_ALGORITHM := SHA512_RSA4096
  88. BOARD_BOOTIMAGE_PARTITION_SIZE := <boot partition size>
  89. After flashing U-Boot don't forget to update environment and write new
  90. partition table::
  91. => env default -f -a
  92. => setenv partitions $partitions_android
  93. => env save
  94. => gpt write mmc 1 $partitions_android
  95. References
  96. ----------
  97. .. [1] https://android.googlesource.com/platform/external/avb/+/master/README.md
  98. .. [2] https://www.op-tee.org/