Introduction to Android Verified Boot 2.0

Android Verified Boot (AVB) 2.0 is a critical security feature designed to ensure the integrity of the software running on Android devices. It establishes a chain of trust from the hardware root of trust up to the system partition, verifying each stage of the boot process before execution. This prevents malicious actors from tampering with the operating system or replacing it with an unauthorized version, thereby protecting user data and device functionality.

What is AVB and Why is it Essential?

At its core, AVB aims to detect and prevent unauthorized modifications to the Android operating system. Without a robust verification mechanism like AVB, a compromised bootloader or system image could allow attackers to gain deep access to the device, install malware, or steal sensitive information. AVB 2.0 significantly enhances this protection by providing stronger cryptographic verification, rollback protection, and support for modular partition signing. For developers working with custom ROMs, kernels, or system-level modifications, understanding and correctly implementing AVB is paramount to maintaining device security and ensuring compatibility.

Core Concepts of AVB 2.0

To effectively implement AVB 2.0, it’s crucial to grasp its foundational concepts, which collectively form the secure boot chain.

The Secure Boot Chain

The secure boot chain in Android starts with a hardware root of trust, typically a Read-Only Memory (ROM) embedded in the device’s System-on-Chip (SoC). This ROM executes the initial bootloader, which is cryptographically verified. The bootloader then verifies the next stage, often the kernel and ramdisk, and so on, until the entire system is loaded. If any stage in this chain fails verification, the device will either refuse to boot or boot into a limited recovery mode, signaling a potential tampering attempt. AVB 2.0 extends this chain to encompass more partitions, providing granular control and improved resilience.

Key Components: VBMeta, Hash Trees, and Rollback Protection

• VBMeta Descriptor: The vbmeta image is the central metadata block for AVB 2.0. It contains hashes or hash tree descriptors for other verified partitions (e.g., boot, system, vendor, dtbo, product) and is signed with a private key. The public key corresponding to this private key is typically fused into the device hardware or known by the bootloader. If the vbmeta image’s signature is invalid, the entire verification process fails.
• DM-Verity & Hash Trees: For larger partitions like system or vendor, AVB uses dm-verity, a kernel feature that cryptographically verifies blocks of data as they are read. This is achieved by embedding a hash tree (Merkle tree) within the partition footer or in a separate verity partition. Each data block’s hash can be quickly checked against its parent hash, tracing back to a root hash stored in the vbmeta. This ensures ongoing integrity even after the device has booted.
• Rollback Protection: AVB 2.0 incorporates rollback protection using a rollback index. This index is stored both in the vbmeta image and securely on the device’s non-volatile memory. During boot, the bootloader compares the rollback index from the vbmeta with the stored index. If the vbmeta‘s index is lower, it indicates an attempt to downgrade the device to an older, potentially vulnerable software version, and the boot will be blocked. This is crucial for preventing attacks that exploit older security vulnerabilities.

Prerequisites and Setup

Development Environment

Before diving into AVB implementation, ensure you have the following setup:

• AOSP Source Tree: A fully synced and built Android Open Source Project (AOSP) source tree. This provides the necessary build tools and avbtool.
• Device with Unlocked Bootloader: For development and testing, your target device must have an unlocked bootloader, allowing you to flash custom images. For production, keys are typically fused.
• Linux Environment: Most Android build tools and avbtool are designed for Linux.

Generating AVB Keys

AVB requires a set of cryptographic keys. You’ll need a public/private key pair to sign your partitions and vbmeta image. The public key part will eventually be known to the device’s bootloader.

Use the avbtool utility from your AOSP build to generate a key:

cd $AOSP_ROOT/out/host/linux-x86/binavbtool gen_key --output_vbmeta_private_key avb_pkmd.pem --output_vbmeta_public_key avb_pkmd.avbpubkey --output_vbmeta_public_key_metadata avb_pkmd.avbpubkey.metadata

This command generates:

• avb_pkmd.pem: The private key, used for signing. Keep this highly secure.
• avb_pkmd.avbpubkey: The public key in raw format, used by the bootloader.
• avb_pkmd.avbpubkey.metadata: Public key metadata, useful for embedding into vbmeta.

Implementing AVB 2.0: Step-by-Step Guide

Here’s how to sign your Android images and create the necessary AVB metadata.

Signing Individual Partitions

Each partition you wish to verify must be signed. Partitions like boot and dtbo usually get a simple hash footer, while larger partitions like system and vendor use hash trees for dm-verity.

Example for a boot image (hash footer):

avbtool add_hash_footer --image boot.img --partition_name boot --partition_size $(stat -c %s boot.img) --key avb_pkmd.pem --algorithm SHA256_RSA4096 --rollback_index 0 --output_image boot_signed.img

Example for a system image (hash tree footer for dm-verity):

avbtool add_hashtree_footer --image system.img --partition_name system --partition_size $(stat -c %s system.img) --key avb_pkmd.pem --algorithm SHA256_RSA4096 --rollback_index 0 --output_image system_signed.img --hash_algorithm sha256

Repeat these steps for all verified partitions (vendor.img, dtbo.img, product.img, etc.), adjusting the --partition_name and `output_image` accordingly. The --rollback_index should be incremented for new, official releases to prevent downgrades.

Creating the VBMeta Image

After signing individual partitions, you must create the vbmeta.img, which acts as the central hub of verification metadata.

avbtool make_vbmeta_image --output vbmeta.img --arg --prop_a --arg --prop_b 
  --key avb_pkmd.pem --algorithm SHA256_RSA4096 
  --rollback_index 0 
  --include_descriptors_from_image boot_signed.img 
  --include_descriptors_from_image system_signed.img 
  --include_descriptors_from_image vendor_signed.img 
  --include_descriptors_from_image dtbo_signed.img 
  --chain_partition boot:1:avb_pkmd.avbpubkey 
  --chain_partition system:2:avb_pkmd.avbpubkey 
  --setup_hash_partition_footer system:system.img 
  --setup_hash_partition_footer vendor:vendor.img 
  --setup_hash_partition_footer product:product.img

Note: The --chain_partition arguments are important if you’re using different keys for different partitions or want to delegate trust. For a simple setup, you might omit some of these if all partitions are signed with the same key and included directly in vbmeta. For example, if boot_signed.img and system_signed.img were created with --add_hash_footer and --add_hashtree_footer, they already contain their own metadata, which vbmeta then references via --include_descriptors_from_image.

Flashing the Signed Images

Once all images are signed and vbmeta.img is created, you can flash them to your device using fastboot:

fastboot flash boot boot_signed.imgfastboot flash system system_signed.imgfastboot flash vendor vendor_signed.imgfastboot flash dtbo dtbo_signed.imgfastboot flash vbmeta vbmeta.img

Finally, reboot your device:

fastboot reboot

Fusing AVB Keys (Optional for Production)

For production devices, the public key used to verify the vbmeta image’s signature must be permanently stored in a hardware trust anchor (e.g., eFuse or OTP). This is a critical step to prevent an attacker from replacing your public key with their own. During development, especially with an unlocked bootloader, you might use fastboot oem avb_set_key or similar OEM-specific commands to temporarily provision the key, but this offers less security than hardware fusing. Consult your SoC vendor’s documentation for specific instructions on key provisioning.

Integrating AVB into Custom ROMs (e.g., LineageOS)

When building custom ROMs like LineageOS, AVB integration is largely handled by the Android build system, provided you configure it correctly.

Modifying Device Configuration

You’ll need to enable and configure AVB in your device’s BoardConfig.mk file (located at device/<manufacturer>/<device>/BoardConfig.mk or similar).

# Enable AVB 2.0BOARD_AVB_ENABLE := true# Specify the location of your AVB private keyBOARD_AVB_KEY_PATH := $(LOCAL_PATH)/avb_pkmd.pem# Specify the algorithm used for signingBOARD_AVB_ALGORITHM := SHA256_RSA4096# Set the initial rollback indexBOARD_AVB_ROLLBACK_INDEX := 0# List partitions to be verified via VBMetaBOARD_AVB_VBMETA_PARTITIONS := boot system vendor product dtbo# Optionally, use specific keys for different partitions. 
# If not specified, BOARD_AVB_KEY_PATH is used. 
# BOARD_AVB_BOOT_KEY_PATH := $(LOCAL_PATH)/boot_pk.pem# Define how partitions are signed (hash or hashtree)BOARD_AVB_BOOT_HASHTREE_ENABLE := false # boot.img typically uses hash footerBOARD_AVB_SYSTEM_HASHTREE_ENABLE := trueBOARD_AVB_VENDOR_HASHTREE_ENABLE := trueBOARD_AVB_PRODUCT_HASHTREE_ENABLE := trueBOARD_AVB_DTBO_HASHTREE_ENABLE := false

Ensure your AVB keys (avb_pkmd.pem and avb_pkmd.avbpubkey) are placed in a location accessible by the build system, often within your device tree (e.g., device/<manufacturer>/<device>/avb/).

Building with AVB Enabled

With the BoardConfig.mk correctly configured, the standard Android build process will automatically sign the images and generate the vbmeta.img.

source build/envsetup.shlunch lineage_<device>-userdebugmake -j$(nproc)

The signed images and vbmeta.img will be found in your out/target/product/<device>/ directory.

Verifying AVB Status and Troubleshooting

Checking AVB State

After flashing, you can verify the AVB status on your device using adb:

adb shell avbctl get_state

Expected output for a healthy, verified device:

AVB state: green

Other states include:

• yellow: Device boots, but verification failed, possibly due to user action (e.g., unlocking bootloader) or incomplete AVB setup.
• red: Verification failed critically, often preventing boot.

Common Issues and Solutions

• Signature Mismatch Errors: If the bootloader cannot verify the signature of vbmeta.img or a chained partition, it will usually report a signature mismatch. Double-check that you’re using the correct public key provisioned to the bootloader, and that all images were signed with the corresponding private key.
• Boot Loop / Device Unbootable: This is a common symptom of AVB failure. Ensure all required partitions are signed and referenced correctly in vbmeta.img. A missing or corrupted vbmeta.img is a frequent cause. Flashing a known working set of images (e.g., stock ROM or previous build) might be necessary to recover.
• Rollback Index Mismatch: If you flash an image with a lower rollback index than what’s stored on the device, AVB will block the boot. Increment your BOARD_AVB_ROLLBACK_INDEX in BoardConfig.mk for new builds, or if testing downgrades, temporarily disable rollback protection (not recommended for production).

Conclusion

Implementing Android Verified Boot 2.0 is a fundamental step in securing Android devices against malicious tampering. By understanding its core components, meticulously generating and managing cryptographic keys, and correctly integrating AVB into your build process, developers can ensure the integrity of their custom ROMs and kernels. While the initial setup might seem complex, the robust security provided by AVB 2.0 is indispensable for maintaining a trustworthy and secure Android ecosystem. Adhering to these guidelines not only enhances device security but also contributes to a more reliable user experience.