Introduction to Android Verified Boot 2.0 (AVB2)

Android Verified Boot 2.0 (AVB2) is a critical security feature designed to ensure the integrity of the entire software running on an Android device, from the bootloader all the way to the system partition. Its primary goal is to detect and prevent malicious or unauthorized modifications to the operating system, thereby protecting users from potential threats like rootkits, malware, and data breaches. For custom ROM developers, device manufacturers, and security researchers, a deep understanding of AVB2’s mechanics and the `avbtool` utility is indispensable for creating secure and verifiable Android builds.

The Imperative of a Secure Boot Chain

In an increasingly threat-laden digital landscape, the integrity of a device’s software is paramount. AVB2 establishes a “chain of trust” where each stage of the boot process cryptographically verifies the next. This chain starts from a hardware root of trust (typically in the SoC’s immutable boot ROM) and extends through the bootloader, various partitions (boot, system, vendor), and ultimately to the Android framework. If any link in this chain is broken—meaning a modification is detected—AVB2 will prevent the device from booting or present a warning to the user, effectively safeguarding the device’s software environment.

Core Principles of AVB2

Cryptographic Verification and Rollback Protection

AVB2 relies heavily on cryptographic signatures. Each verifiable partition (e.g., `boot.img`, `system.img`, `vendor.img`, `dtbo.img`) is signed with a private key. The corresponding public key is embedded in a metadata image, typically `vbmeta.img`, which itself is signed and verified by the bootloader using a public key fused into the device’s hardware or trusted boot partition. This ensures that only authorized, untampered images can boot.

Beyond basic integrity, AVB2 incorporates robust rollback protection. Each image is assigned a rollback index. During an update, the new image’s rollback index must be greater than or equal to the currently stored index on the device. This mechanism prevents attackers from flashing older, potentially vulnerable versions of the OS, even if they have access to valid, signed old images. The rollback index is typically stored in Replay Protected Memory Blocks (RPMB) or a similar secure storage solution.

Verified Boot States

AVB2 defines various boot states, indicated by visual cues during boot, to inform the user about the device’s integrity:

• Green: The device is booting with official, unmodified software. This is the most secure state.
• Yellow: The device is booting with official software, but a minor issue or warning is present (rare).
• Orange: The device is unlocked and running custom software. The user is explicitly warned that the boot image has been altered, and verification has been skipped or changed.
• Red: The device has detected a serious corruption or tampering that prevents it from booting safely. This usually indicates a critical integrity compromise.

These states provide transparency to the user and allow them to make informed decisions, especially in the context of custom ROMs where an Orange state is expected.

Demystifying `avbtool`: Your AVB2 Command-Line Companion

`avbtool` is the primary command-line utility for managing Android Verified Boot 2.0 images and metadata. It’s an essential tool for signing partitions, creating `vbmeta.img`, and extracting public keys, particularly when building custom Android images.

What is `avbtool`?

`avbtool` is a Python-based script found in the Android Open Source Project (AOSP) under `system/core/avb/avbtool.py`. It’s used by the Android build system to apply AVB2 signatures and metadata to various images during the build process. For custom builds, understanding its direct usage is critical for offline signing or debugging.

Key `avbtool` Commands Explained

Here are some of the most frequently used `avbtool` commands:

• `add_hash_footer`: This command computes the hash of an image and appends a hash footer containing the hash, signing key ID, and other metadata. This signed image can then be referenced by `vbmeta.img`.

  avbtool add_hash_footer 
    --image boot.img 
    --partition_name boot 
    --partition_size $(stat -c %s boot.img) 
    --key avb_private_key.pem 
    --algorithm SHA256_RSA40996

• `add_rollback_index`: Used to set or update the rollback index for a partition in the `vbmeta.img`. This is crucial for rollback protection.
• `make_vbmeta_image`: This is the central command for creating the `vbmeta.img` file, which aggregates metadata and hashes for other partitions.

  avbtool make_vbmeta_image 
    --output vbmeta.img 
    --algorithm SHA256_RSA4096 
    --key avb_private_key.pem 
    --rollback_index 1 
    --additional_image_descriptor boot.img:200000000:boot 
    --additional_image_descriptor system.img:3000000000:system 
    --additional_image_descriptor vendor.img:1000000000:vendor

  Note: The sizes here are examples; use actual partition sizes.

• `extract_public_key`: Extracts the public key from a private key file (or `vbmeta.img`) into a `.bin` file, which can then be fused into the device or included in the bootloader for verification.

  avbtool extract_public_key 
    --key avb_private_key.pem 
    --output avb_pkmd.bin

• `verify_image`: Verifies a given image locally. Useful for debugging.

  avbtool verify_image --image path/to/vbmeta.img

Practical `avbtool` Examples

Let’s walk through a simplified custom build signing process:

1. Generate a new RSA key pair (if you don’t have one):

   openssl genrsa -out avb_private_key.pem 4096 
   openssl pkcs8 -in avb_private_key.pem -inform PEM -out avb_private_key_pk8.pem -topk8 -nocrypt

2. Sign your individual images (e.g., `boot.img`, `system.img`):

   avbtool add_hash_footer 
     --image boot.img 
     --partition_name boot 
     --partition_size $(stat -c %s boot.img) 
     --key avb_private_key_pk8.pem 
     --algorithm SHA256_RSA4096 
     --rollback_index 1

   Repeat for other images like `system.img`, `vendor.img`, etc.

3. Create the `vbmeta.img` that references these signed images:

   avbtool make_vbmeta_image 
     --output vbmeta.img 
     --algorithm SHA256_RSA4096 
     --key avb_private_key_pk8.pem 
     --rollback_index 1 
     --padding_size 4096 
     --additional_image_descriptor boot.img:$(stat -c %s boot.img):boot 
     --additional_image_descriptor system.img:$(stat -c %s system.img):system

4. Flash the `vbmeta.img` and other images to your device using `fastboot`.

Integrating AVB2 into Custom Android Builds (AOSP)

For those working with AOSP, AVB2 integration is primarily handled via configuration in your device’s `BoardConfig.mk` file. The Android build system then uses these settings to invoke `avbtool` automatically.

Configuring AVB2 in BoardConfig.mk

Here are essential `BoardConfig.mk` variables for AVB2:

# Enable AVB2
BOARD_AVB_ENABLE := true

# Choose signing algorithm (e.g., SHA256_RSA4096, SHA512_RSA8192)
BOARD_AVB_ALGORITHM := SHA256_RSA4096

# Path to your private key (PKCS#8 format)
BOARD_AVB_KEY_PATH := device/<vendor>/<device>/security/avb_private_key_pk8.pem

# Path to the public key metadata for device enrollment
BOARD_AVB_LOCAL_PUBLIC_KEY_PATH := device/<vendor>/<device>/security/avb_pkmd.bin

# Initial rollback index for images
BOARD_AVB_ROLLBACK_INDEX := 1

# Enable hashtree for dynamic partitions (e.g., system, vendor)
BOARD_AVB_HASHTREE_ENABLE := true

# List partitions included in vbmeta.img and signed
BOARD_AVB_VBMETA_INCLUDE_PARTITIONS := boot system vendor product dtbo

# Arguments for partitions requiring hashtree (often dynamic partitions)
BOARD_AVB_VBMETA_ADD_HASHTREE_FOOTER_ARGS += n  --hash_algorithm sha256 n  --partition_name system:$(BOARD_SYSTEMIMAGE_PARTITION_SIZE) n  --partition_name vendor:$(BOARD_VENDORIMAGE_PARTITION_SIZE) n  --partition_name product:$(BOARD_PRODUCTIMAGE_PARTITION_SIZE)

Generating Custom AVB Keys

It is crucial to use your own unique key pair for custom builds instead of relying on default AOSP test keys. This ensures that only you can sign and verify your custom images. Generate them as shown in the `avbtool` examples and place `avb_private_key_pk8.pem` and `avb_pkmd.bin` in the path specified by `BOARD_AVB_KEY_PATH` and `BOARD_AVB_LOCAL_PUBLIC_KEY_PATH` respectively. The `avb_pkmd.bin` is derived from your private key using `avbtool extract_public_key`.

Building with AVB2 Enabled

After configuring your `BoardConfig.mk` and placing your keys, a standard AOSP build command will incorporate AVB2:

source build/envsetup.sh
breakfast <device_codename>
make -j $(nproc)

The build process will automatically invoke `avbtool` to sign your images and generate the `vbmeta.img` based on your configuration. You can find the generated `vbmeta.img` and signed partition images in your `out/target/product/<device_codename>/` directory.

Runtime Policy Enforcement and User Experience

The Bootloader’s Role

When an AVB2-enabled device boots, the bootloader (or a trusted part of it) performs the following:

1. Reads the `vbmeta.img` from its dedicated partition.
2. Verifies the signature of `vbmeta.img` using the embedded public key, which is usually fused into the SoC’s immutable boot ROM or a trusted partition.
3. Parses the `vbmeta.img` to obtain the hashes and rollback indices of other partitions (e.g., `boot`, `system`, `vendor`).
4. For each partition, it calculates the hash and compares it against the expected hash from `vbmeta.img`. It also checks the rollback index against the stored value.
5. Based on these checks, it determines the verified boot state (Green, Yellow, Orange, Red) and proceeds with booting or displays a warning/error.

Displaying Boot State Warnings

If the device detects tampering or is in an unlocked state (Orange), it will display a warning message on the screen during boot, typically lasting for a few seconds. This is a critical user notification. For an Orange state (unlocked bootloader), this is normal. For a Red state, it indicates a severe security breach or corrupted image.

Debugging AVB2 Issues

Debugging AVB2 issues can be challenging. Here are some techniques:

• Local `avbtool verify_image`: Use this to check the integrity of your generated `vbmeta.img` and other signed images offline before flashing.
• `adb shell avb_info`: If your device successfully boots, this command (available in some Android versions) can provide runtime information about the AVB status, active rollback indexes, and verified partitions.
• Fastboot commands: In fastboot mode, you can often query the device’s boot state and security settings (e.g., `fastboot getvar all`).
• Bootloader logs: If you have access to bootloader logs (e.g., via serial console), they can provide detailed insights into where the AVB verification process is failing.

Conclusion

Android Verified Boot 2.0 is a cornerstone of device security, and mastering `avbtool` and AOSP configuration is essential for anyone involved in custom Android development or device manufacturing. By understanding the cryptographic principles, correctly using `avbtool` to sign your images, and properly configuring AVB2 in your build system, you can ensure the integrity of your custom Android builds, protect against tampering, and provide a secure experience for your users. Implementing AVB2 correctly is not just a best practice; it’s a fundamental requirement for a trustworthy Android system.