Introduction

Android Verified Boot 2.0 (AVB2) is a critical security feature ensuring the integrity of the Android operating system from the moment the device powers on. It establishes a chain of trust from the hardware root of trust up to the system partition, preventing malicious actors from tampering with the device’s software. For developers building custom Android Open Source Project (AOSP) distributions, integrating AVB2 is paramount for device security and user trust. This guide provides an expert-level, step-by-step walkthrough for enabling and configuring AVB2 in your custom AOSP build, ensuring your devices boot a verified and untampered operating system.

Understanding Android Verified Boot 2.0 (AVB2)

Verified Boot is a process that guarantees the authenticity and integrity of all executable code and data on a device. AVB2 builds upon its predecessor by offering enhanced features like rollback protection, header-versioning, and a more robust chain of trust. It ensures:

• Authenticity: All boot images, partitions (system, vendor, product, etc.), and the Android framework are cryptographically signed.
• Integrity: Any unauthorized modification to these signed components will prevent the device from booting or trigger a user warning.
• Rollback Protection: Prevents an attacker from flashing an older, potentially vulnerable version of the Android software.

Key Components of AVB2:

• Root of Trust: A hardware-backed immutable key or hash stored on the device, typically in fuses or a secure element, used to verify the initial bootloader.
• VBMeta Image: A metadata image containing the hashes and public keys for all other verified partitions. It’s signed by the device manufacturer’s private key.
• Bootloader: The first piece of software executed after the hardware, responsible for loading and verifying the VBMeta image using the Root of Trust.
• dm-verity: A Linux kernel feature that transparently verifies the integrity of block devices using a cryptographic hash tree, ensuring that all data read from a partition matches its expected hash.

Prerequisites and Setup

Before proceeding, ensure you have:

• A fully synced AOSP source tree (e.g., Android 12 or newer).
• A working AOSP build environment capable of compiling for your target device.
• Basic familiarity with the Android build system (Make and Soong).
• A custom device configuration (device tree) that you wish to integrate AVB2 into.

Step-by-Step Integration Guide

Step 1: Generating AVB Keys

AVB2 relies on cryptographic key pairs. You’ll need an RSA private key to sign your device images and the corresponding public key embedded in the device’s boot chain. For production, these keys should be securely generated and stored. For development, you can create them with openssl:

# Create a 4096-bit RSA private keyavbtool generate_key --output_key avb_pkmd.pem --algorithm SHA256_RSA4096openssl rsa -in avb_pkmd.pem -pubout -out avb_pkmd.pem.pub# This is a convenience for extracting the public key used by the bootloader# The 'avb_pkmd.pem.pub' is typically used for `BOARD_AVB_VBMETA_PUBLIC_KEY`

Store these keys in a secure location within your device tree, typically in a directory like device/<vendor>/<device>/avb.

Step 2: Configuring Board for AVB2

Next, you need to inform the AOSP build system about your AVB2 intentions. This is primarily done by modifying your device’s BoardConfig.mk and device.mk files.

Modify BoardConfig.mk:

# Enable AVB 2.0BOARD_AVB_ENABLE := true# Specify the algorithm to use for signing. SHA256_RSA4096 is common.BOARD_AVB_ALGORITHM := SHA256_RSA4096# Path to your private key for signing (created in Step 1)BOARD_AVB_KEY_PATH := device/<vendor>/<device>/avb/avb_pkmd.pem# Specify where the rollback index should be stored. This is critical for rollback protection.# '1' usually means the bootloader, '2' for Android OS, '3' for vendor, etc.BOARD_AVB_ROLLBACK_INDEX_LOCATION := 1# Define partitions to be included in vbmeta.img and verified.BOARD_AVB_BOOT_ADD_HASH_FOOTER := trueBOARD_AVB_SYSTEM_ADD_HASH_FOOTER := trueBOARD_AVB_VENDOR_ADD_HASH_FOOTER := trueBOARD_AVB_PRODUCT_ADD_HASH_FOOTER := true# If you have other partitions like odm, oem, etc., add them here.# Example for product partition using hash tree (dm-verity)BOARD_AVB_PRODUCT_ADD_HASHTREE_FOOTER_ARGS := 	--hash_algorithm sha256 	--partition_size $(BOARD_PRODUCTIMAGE_PARTITION_SIZE)BOARD_AVB_SYSTEM_ADD_HASHTREE_FOOTER_ARGS := 	--hash_algorithm sha256 	--partition_size $(BOARD_SYSTEMIMAGE_PARTITION_SIZE)

Also, define the public key to be embedded in the vbmeta image, which the bootloader will use for verification:

BOARD_AVB_VBMETA_PUBLIC_KEY := device/<vendor>/<device>/avb/avb_pkmd.pem.pub

Modify device.mk:

Ensure that the vbmeta image is built and included in your device’s build artifacts:

PRODUCT_PACKAGES += 	vbmeta

Step 3: Building and Signing Images

With the configurations in place, the AOSP build system will automatically invoke avbtool to sign the images and generate the vbmeta.img. Navigate to the root of your AOSP directory and initiate the build:

source build/envsetup.shlunch <your_device_target> # e.g., lunch aosp_arm64-userdebugm -j$(nproc)

During the build, you will see messages indicating that partitions are being signed. The final output will include signed images like boot.img, system.img, vendor.img, and most importantly, vbmeta.img.

Step 4: Flashing and Verification

After a successful build, you can flash the images to your device using fastboot. It’s crucial to flash the vbmeta.img first.

fastboot flash vbmeta <path_to_aosp_out>/vbmeta.imgfastboot flash boot <path_to_aosp_out>/boot.imgfastboot flash system <path_to_aosp_out>/system.imgfastboot flash vendor <path_to_aosp_out>/vendor.imgfastboot reboot

Once the device boots, you can verify the AVB2 status:

adb shell getprop ro.boot.verifiedbootstate

Expected outputs include:

• green: Device is booting an official, unmodified, and verified image.
• yellow: Device is booting with a locked bootloader but allows user-signed images (e.g., developer mode).
• orange: Device is booting with an unlocked bootloader, indicating no verification.
• red: Device failed verification, possibly due to tampering or corrupted images.

To test tampering, try modifying a partition (e.g., system.img) and reflashing it without re-signing. The device should refuse to boot or show a warning, confirming AVB2’s effectiveness.

Step 5: Implementing Rollback Protection

Rollback protection is a cornerstone of AVB2. It prevents an attacker from downgrading the device to an older, vulnerable version of the OS. This is managed by rollback indexes, which are incremented with each new, secure update. The bootloader stores these indexes. The vbmeta.img contains the expected rollback index. If the device attempts to boot an image with an index lower than the one stored in the bootloader, AVB2 will prevent it.

The BOARD_AVB_ROLLBACK_INDEX_LOCATION := 1 in BoardConfig.mk specifies that the rollback index for the vbmeta image will be stored at location 1 (typically reserved for the bootloader’s persistent storage). For updates, the build system automatically handles incrementing this index when generating a new vbmeta.img.

Advanced Considerations

• Custom Root of Trust (RoT):

  For production devices, the public key embedded in the bootloader (derived from your AVB key) should ultimately be verified by a hardware-backed RoT. This often involves burning the public key hash into eFuses during manufacturing, making it immutable.

• Debug vs. Production Keys:

  Always use separate key pairs for development/testing and production builds. Never expose your production private keys.

• OTA Updates and AVB:

  Android’s Over-The-Air (OTA) update system is designed to work seamlessly with AVB2. Update packages are signed, and the device verifies the signature of the new images before applying them, ensuring the chain of trust is maintained even through updates.

• Multiple Rollback Indexes:

  AVB2 supports multiple rollback indexes, allowing different components (e.g., bootloader, Android OS, vendor firmware) to have their own version tracking. This adds granularity to rollback protection.

Conclusion

Integrating Android Verified Boot 2.0 into your custom AOSP build is a critical step towards creating a secure and trustworthy device. By following this guide, you’ve learned to generate cryptographic keys, configure your AOSP build for AVB2, build and flash signed images, and understand the fundamental principles of rollback protection. A properly implemented AVB2 chain of trust is your first line of defense against software tampering, providing robust security for your Android devices.