[8/8] doc: avb2.0: add README about AVB2.0 integration

Contains:
1. Overview of Android Verified Boot 2.0
2. Description of avb subset of commands
3. Examples of errors when boot/vendor/system/vbmeta partitions
are tampered
4. Examples of enabling AVB2.0 on your setup

Signed-off-by: Igor Opaniuk <igor.opaniuk@linaro.org>
---
 doc/README.avb2 | 100 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 doc/README.avb2

On 25 April 2018 at 16:18, Igor Opaniuk <igor.opaniuk@linaro.org> wrote:
> Contains:
> 1. Overview of Android Verified Boot 2.0
> 2. Description of avb subset of commands
> 3. Examples of errors when boot/vendor/system/vbmeta partitions
> are tampered
> 4. Examples of enabling AVB2.0 on your setup
>
> Signed-off-by: Igor Opaniuk <igor.opaniuk@linaro.org>
> ---
>  doc/README.avb2 | 100 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 100 insertions(+)
>  create mode 100644 doc/README.avb2
>
> diff --git a/doc/README.avb2 b/doc/README.avb2
> new file mode 100644
> index 0000000..40db7c5
> --- /dev/null
> +++ b/doc/README.avb2
> @@ -0,0 +1,100 @@
> +Android Verified Boot 2.0
> +
> +This file contains information about the current support of Android Verified
> +Boot 2.0 in U-boot
> +
> +1. OVERVIEW
> +---------------------------------
> +Verified Boot establishes a chain of trust from the bootloader to system images
> +* Provides integrity checking for:
> +  - Android Boot image: Linux kernel + ramdisk. RAW hashing of the whole
> +    partition is done and the hash is compared with the one stored in
> +    the VBMeta image
> +  - system/vendor partitions: verifying root hash of dm-verity hashtrees.
> +* Provides capabilities for rollback protection.
> +
> +Integrity of the bootloader (U-boot BLOB and environment) is out of scope.
> +
> +For additional details check:
> +https://android.googlesource.com/platform/external/avb/+/master/README.md
> +
> +
> +2. AVB 2.0 U-BOOT SHELL COMMANDS
> +-----------------------------------
> +Provides CLI interface to invoke AVB 2.0 verification + misc. commands for
> +different testing purposes:
> +
> +avb init <dev> - initialize avb 2.0 for <dev>
> +avb verify - run verification process using hash data from vbmeta structure
> +avb read_rb <num> - read rollback index at location <num>
> +avb write_rb <num> <rb> - write rollback index <rb> to <num>
> +avb is_unlocked - returns unlock status of the device
> +avb get_uuid <partname> - read and print uuid of partition <partname>
> +avb read_part <partname> <offset> <num> <addr> - read <num> bytes from
> +partition <partname> to buffer <addr>
> +avb write_part <partname> <offset> <num> <addr> - write <num> bytes to
> +<partname> by <offset> using data from <addr>
> +
> +
> +3. PARTITIONS TAMPERING (EXAMPLE)
> +-----------------------------------
> +Boot or system/vendor (dm-verity metadata section) is tampered:
> +=> avb init 1
> +=> avb verify
> +avb_slot_verify.c:175: ERROR: boot: Hash of data does not match digest in
> +descriptor.
> +Slot verification result: ERROR_IO
> +
> +Vbmeta partition is tampered:
> +=> avb init 1
> +=> avb verify
> +avb_vbmeta_image.c:206: ERROR: Hash does not match!
> +avb_slot_verify.c:388: ERROR: vbmeta: Error verifying vbmeta image:
> +HASH_MISMATCH
> +Slot verification result: ERROR_IO
> +
> +
> +4. ENABLE ON YOUR BOARD
> +-----------------------------------
> +The following options must be enabled:
> +CONFIG_LIBAVB=y
> +CONFIG_LIBAVB_AB=y
> +CONFIG_CMD_AVB=y
> +
> +
> +Then add `avb verify` invocation to your android boot sequence of commands,
> +e.g.:
> +
> +=> avb_verify=avb init $mmcdev; avb verify;
> +=> if run avb_verify; then                       \
> +        echo AVB verification OK. Continue boot; \
> +        set bootargs $bootargs $avb_bootargs;    \
> +   else                                          \
> +        echo AVB verification failed;            \
> +        exit;                                    \
> +   fi;                                           \
> +
> +=> emmc_android_boot=                                   \
> +       echo Trying to boot Android from eMMC ...;       \
> +       ...                                              \
> +       run avb_verify;                                  \
> +       mmc read ${fdtaddr} ${fdt_start} ${fdt_size};    \
> +       mmc read ${loadaddr} ${boot_start} ${boot_size}; \
> +       bootm $loadaddr $loadaddr $fdtaddr;              \
> +
> +
> +To switch on automatic generation of vbmeta partition in AOSP build, add these
> +lines to device configuration mk file:
> +
> +BOARD_AVB_ENABLE := true
> +BOARD_AVB_ALGORITHM := SHA512_RSA4096
> +BOARD_BOOTIMAGE_PARTITION_SIZE := <boot partition size>
> +
> +After flashing U-boot don't forget to update environment and write new
> +partition table:
> +=> env default -f -a
> +=> setenv partitions $partitions_android
> +=> env save
> +=> fas 1
> +
> +$ fastboot oem format

FYI, those commands can be shrank down to a single command:

    => gpt write mmc 1 $partitions_android

because that's exactly what "fastboot oem format" is doing. This way
you can avoid using fastboot, and thus having it as a dependency. But
your way is better w.r.t. user experience (i.e. if environment is
already set, user can just run host command, and avoid tinkering with
U-Boot shell at all). Please choose which one is better depending on
targeting use-case.

> --
> 2.7.4
>

Hi Sam,

Thanks, will include this notice in the v2 patchset

Regards,
Igor

On 2 May 2018 at 22:12, Sam Protsenko <semen.protsenko@linaro.org> wrote:
> On 25 April 2018 at 16:18, Igor Opaniuk <igor.opaniuk@linaro.org> wrote:
>> Contains:
>> 1. Overview of Android Verified Boot 2.0
>> 2. Description of avb subset of commands
>> 3. Examples of errors when boot/vendor/system/vbmeta partitions
>> are tampered
>> 4. Examples of enabling AVB2.0 on your setup
>>
>> Signed-off-by: Igor Opaniuk <igor.opaniuk@linaro.org>
>> ---
>>  doc/README.avb2 | 100 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 100 insertions(+)
>>  create mode 100644 doc/README.avb2
>>
>> diff --git a/doc/README.avb2 b/doc/README.avb2
>> new file mode 100644
>> index 0000000..40db7c5
>> --- /dev/null
>> +++ b/doc/README.avb2
>> @@ -0,0 +1,100 @@
>> +Android Verified Boot 2.0
>> +
>> +This file contains information about the current support of Android Verified
>> +Boot 2.0 in U-boot
>> +
>> +1. OVERVIEW
>> +---------------------------------
>> +Verified Boot establishes a chain of trust from the bootloader to system images
>> +* Provides integrity checking for:
>> +  - Android Boot image: Linux kernel + ramdisk. RAW hashing of the whole
>> +    partition is done and the hash is compared with the one stored in
>> +    the VBMeta image
>> +  - system/vendor partitions: verifying root hash of dm-verity hashtrees.
>> +* Provides capabilities for rollback protection.
>> +
>> +Integrity of the bootloader (U-boot BLOB and environment) is out of scope.
>> +
>> +For additional details check:
>> +https://android.googlesource.com/platform/external/avb/+/master/README.md
>> +
>> +
>> +2. AVB 2.0 U-BOOT SHELL COMMANDS
>> +-----------------------------------
>> +Provides CLI interface to invoke AVB 2.0 verification + misc. commands for
>> +different testing purposes:
>> +
>> +avb init <dev> - initialize avb 2.0 for <dev>
>> +avb verify - run verification process using hash data from vbmeta structure
>> +avb read_rb <num> - read rollback index at location <num>
>> +avb write_rb <num> <rb> - write rollback index <rb> to <num>
>> +avb is_unlocked - returns unlock status of the device
>> +avb get_uuid <partname> - read and print uuid of partition <partname>
>> +avb read_part <partname> <offset> <num> <addr> - read <num> bytes from
>> +partition <partname> to buffer <addr>
>> +avb write_part <partname> <offset> <num> <addr> - write <num> bytes to
>> +<partname> by <offset> using data from <addr>
>> +
>> +
>> +3. PARTITIONS TAMPERING (EXAMPLE)
>> +-----------------------------------
>> +Boot or system/vendor (dm-verity metadata section) is tampered:
>> +=> avb init 1
>> +=> avb verify
>> +avb_slot_verify.c:175: ERROR: boot: Hash of data does not match digest in
>> +descriptor.
>> +Slot verification result: ERROR_IO
>> +
>> +Vbmeta partition is tampered:
>> +=> avb init 1
>> +=> avb verify
>> +avb_vbmeta_image.c:206: ERROR: Hash does not match!
>> +avb_slot_verify.c:388: ERROR: vbmeta: Error verifying vbmeta image:
>> +HASH_MISMATCH
>> +Slot verification result: ERROR_IO
>> +
>> +
>> +4. ENABLE ON YOUR BOARD
>> +-----------------------------------
>> +The following options must be enabled:
>> +CONFIG_LIBAVB=y
>> +CONFIG_LIBAVB_AB=y
>> +CONFIG_CMD_AVB=y
>> +
>> +
>> +Then add `avb verify` invocation to your android boot sequence of commands,
>> +e.g.:
>> +
>> +=> avb_verify=avb init $mmcdev; avb verify;
>> +=> if run avb_verify; then                       \
>> +        echo AVB verification OK. Continue boot; \
>> +        set bootargs $bootargs $avb_bootargs;    \
>> +   else                                          \
>> +        echo AVB verification failed;            \
>> +        exit;                                    \
>> +   fi;                                           \
>> +
>> +=> emmc_android_boot=                                   \
>> +       echo Trying to boot Android from eMMC ...;       \
>> +       ...                                              \
>> +       run avb_verify;                                  \
>> +       mmc read ${fdtaddr} ${fdt_start} ${fdt_size};    \
>> +       mmc read ${loadaddr} ${boot_start} ${boot_size}; \
>> +       bootm $loadaddr $loadaddr $fdtaddr;              \
>> +
>> +
>> +To switch on automatic generation of vbmeta partition in AOSP build, add these
>> +lines to device configuration mk file:
>> +
>> +BOARD_AVB_ENABLE := true
>> +BOARD_AVB_ALGORITHM := SHA512_RSA4096
>> +BOARD_BOOTIMAGE_PARTITION_SIZE := <boot partition size>
>> +
>> +After flashing U-boot don't forget to update environment and write new
>> +partition table:
>> +=> env default -f -a
>> +=> setenv partitions $partitions_android
>> +=> env save
>> +=> fas 1
>> +
>> +$ fastboot oem format
>
> FYI, those commands can be shrank down to a single command:
>
>     => gpt write mmc 1 $partitions_android
>
> because that's exactly what "fastboot oem format" is doing. This way
> you can avoid using fastboot, and thus having it as a dependency. But
> your way is better w.r.t. user experience (i.e. if environment is
> already set, user can just run host command, and avoid tinkering with
> U-Boot shell at all). Please choose which one is better depending on
> targeting use-case.
>
>> --
>> 2.7.4
>>