Introduction: The Imperative of Verified Boot in Android

Android’s security architecture relies heavily on Verified Boot, a critical security feature ensuring the integrity of the device’s software from the moment it powers on. It establishes a complete chain of trust, verifying each stage of the boot process before executing it. For developers, researchers, or power users who modify their Android system, understanding and properly implementing Verified Boot (AVB) with custom images is paramount to maintaining device security and avoiding boot failures or compromise warnings. This expert guide dives deep into avbtool, the utility for managing AVB, and provides a comprehensive, step-by-step walkthrough for signing your custom Android boot images.

Ignoring AVB when flashing custom components can lead to a ‘yellow’ or ‘orange’ boot state, indicating a tampered device, or even prevent the device from booting entirely (‘red’ state). Mastering avbtool allows you to create images that your device’s bootloader can verify, ensuring a ‘green’ boot state and preserving the integrity of the boot chain.

Prerequisites: Tools and Environment Setup

Before we begin, ensure you have the following tools and an appropriate environment set up:

• Android Source Code: A full checkout of the Android Open Source Project (AOSP) is recommended, as it contains avbtool, mkbootimg, and related utilities. Alternatively, you can build these tools individually.
• Linux Environment: Ubuntu or Debian is preferred for building AOSP tools.
• ADB and Fastboot: Installed and configured on your system.
• Basic Linux Command-Line Proficiency: Familiarity with shell commands.
• OpenSSL: For generating cryptographic keys.

Demystifying Android Verified Boot (AVB)

What is Verified Boot?

Android Verified Boot is a security mechanism that guarantees all executed code comes from a trusted source. It starts from a hardware root of trust (e.g., a fused public key in the SoC) and cryptographically verifies each stage of the boot process, from the bootloader to the kernel, ramdisk, and system partition. If any stage is tampered with, the device can refuse to boot or display a warning.

AVB’s Role in System Integrity

AVB uses a Merkle tree-like structure to verify entire partitions efficiently. The VBMeta header, stored in a dedicated partition, contains cryptographic hashes and signatures of other partitions (boot, system, vendor, etc.). The bootloader verifies the VBMeta, and then the operating system verifies the integrity of critical partitions using the metadata within VBMeta.

Understanding AVB States: Green, Yellow, Orange, Red

• Green: Device is booting with a verified, untampered operating system. This is the desired state.
• Yellow: Device is booting with a verified, locked custom OS. This usually means a custom key is used, but the device is locked.
• Orange: Device is booting with an unlocked bootloader and may be running a custom OS. This indicates that the integrity checks are bypassed or user-disabled, making the device less secure.
• Red: Device is corrupted or cannot be verified, typically due to severe tampering or a failed flash. The device may refuse to boot or require recovery.

Core Tool: avbtool and Key Management

avbtool is your primary interface for creating, modifying, and signing AVB-compliant images. It handles key generation, VBMeta image creation, and signing. Key management is fundamental to AVB; you’ll need a public/private key pair to sign your custom images.

Generating AVB Keys

First, generate a private key using OpenSSL. This key will be used to sign your images.

openssl genrsa -out rsa4096.pem 4096

Next, use avbtool to extract the public key from your private key and convert it into a format suitable for embedding in the VBMeta image. This creates a .avbpubkey file.

avbtool extract_public_key --key rsa4096.pem --output rsa4096.avbpubkey

For debugging, you might also want to generate a certificate to examine key details:

openssl req -new -x509 -key rsa4096.pem -out rsa4096.crt -days 36500 -subj "/CN=AVB Test Key"

VBMeta: The Heart of AVB Metadata

The VBMeta image is a small partition containing the hashes and signatures of other partitions that AVB verifies. It acts as a manifest for the entire boot chain. When you sign a boot image, avbtool computes its hash and includes it in the VBMeta image, which is then signed with your private key.

Step-by-Step: Signing Your Custom Android Boot Image

This section details the process of taking an existing boot image, modifying it, and then signing it for AVB compliance.

1. Prepare Your Environment and Tools

Navigate to your AOSP build directory and ensure avbtool and mkbootimg are built. If not, build them:

cd /path/to/aosp/source/tree/. build/envsetup.sh lunch <your_device_target> make avbtool mkbootimg

These tools will typically be located in out/host/linux-x86/bin/.

2. Extract and Modify the Boot Image

Obtain the boot.img from your device’s stock firmware or a custom ROM. Use unpackbootimg (from AOSP or your device’s ROM) to extract its components.

unpackbootimg -i boot.img -o boot_extracted/

This will create files like boot_extracted/boot.img-kernel (kernel) and boot_extracted/boot.img-ramdisk.gz (gzipped ramdisk). Decompress the ramdisk:

gunzip boot_extracted/boot.img-ramdisk.gz

Then, unpack the ramdisk CPIO archive to modify its contents. For example, let’s add a simple script:

mkdir boot_extracted/ramdisk cd boot_extracted/ramdisk cpio -id < ../boot.img-ramdisk echo '#!/system/bin/sh' > custom_script.sh echo 'echo "Hello from custom script!" > /dev/kmsg' >> custom_script.sh chmod 755 custom_script.sh cd ../..

Remember to re-pack the ramdisk after modifications:

cd boot_extracted/ramdisk find . | cpio -o -H newc | gzip > ../new_ramdisk.gz cd ../..

3. Re-pack the Custom Boot Image

Now, use mkbootimg to create a new boot.img with your modified ramdisk and the original kernel. You’ll need to replicate the original boot image parameters (page size, base address, board name, cmdline, etc.) that unpackbootimg outputted. Check the boot_extracted/boot.img-header file for these details.

mkbootimg --kernel boot_extracted/boot.img-kernel 	--ramdisk boot_extracted/new_ramdisk.gz 	--base <original_base_address> 	--pagesize <original_page_size> 	--cmdline "<original_cmdline>" 	--board "<original_board_name>" 	-o custom_boot.img

Replace placeholders with actual values from your header file.

4. Generate the VBMeta Image and Sign

This is where avbtool comes into play. We’ll create a vbmeta.img that includes the hash of our custom_boot.img and sign it with our generated key. The --include_descriptors_from_image option ensures that any AVB metadata embedded within custom_boot.img is also included in the generated vbmeta.img.

avbtool make_vbmeta_image 	--output vbmeta.img 	--private_key rsa4096.pem 	--signer_id "avb_test_key" 	--signer_version 1 	--algorithm SHA256_RSA4096 	--set_hashtree_image_size <size_of_boot_partition> 	--hash_image custom_boot.img:16777216:boot 	--include_descriptors_from_image custom_boot.img

The value 16777216 (16MB) for --hash_image is an example for a 16MB boot partition; replace it with the actual size of your device’s boot partition. You can find this using fastboot getvar all or by examining your device’s partition table. The --hash_image custom_boot.img:size:name option tells avbtool to compute the hash of custom_boot.img and associate it with the ‘boot’ partition. The size argument is critical for devices that use AVB hashtree for ‘boot’ partition (e.g., Pixel devices).

For simpler cases where the boot partition is not hashtree protected by AVB directly, you might use --image custom_boot.img:boot instead of --hash_image, which embeds the whole image as a descriptor in vbmeta. Consult your device’s specific AVB implementation details.

5. Flash the Signed Images to Your Device

Reboot your device into bootloader (fastboot) mode and flash the newly created images. Make sure your bootloader is unlocked; otherwise, flashing custom images will fail.

adb reboot bootloader fastboot flash boot custom_boot.img fastboot flash vbmeta vbmeta.img fastboot reboot

It’s crucial to flash both the custom boot image and the corresponding VBMeta image. If you only flash the boot image, the bootloader will try to verify it against the old VBMeta, resulting in a verification failure.

6. Verify Verified Boot Status

After your device reboots, you can check its AVB status using ADB. Look for properties related to AVB.

adb shell getprop ro.boot.verifiedbootstate

This should return green if everything was signed correctly and the bootloader accepted your keys. If you see ‘orange’ or ‘yellow’, it usually means your bootloader is unlocked or using a custom AVB key that’s not officially recognized, which is expected for custom development.

Advanced Hardening and Security Considerations

Key Management Best Practices

The security of your signed images hinges entirely on the security of your private key. Treat rsa4096.pem with extreme care:

• Offline Storage: Store private keys on a machine not connected to the internet.
• Hardware Security Modules (HSMs): For production environments, use HSMs to protect private keys.
• Passphrases: Always protect your private key with a strong passphrase.
• Key Rotation: Periodically generate new keys and sign new builds with them.

Rollback Protection

AVB includes rollback protection, preventing an attacker from flashing an older, potentially vulnerable version of the OS. This is managed by anti-rollback counters (ARBs) stored in the VBMeta image and on protected hardware. When creating VBMeta, you can specify an ARB version with --set_rollback_index <index>:<value>.

avbtool make_vbmeta_image ... --set_rollback_index 0:1 ...

Make sure to increment this value for future updates to leverage rollback protection effectively.

Customizing AVB Hash and Signature Algorithms

avbtool supports various hashing (SHA256, SHA512) and RSA signature algorithms (RSA2048, RSA3072, RSA4096). You can specify these using the --algorithm option. Choose algorithms that balance security requirements with device performance.

Conclusion: Securing the Android Ecosystem

Mastering avbtool and the intricacies of Android Verified Boot is an essential skill for anyone involved in advanced Android development, security research, or creating custom Android distributions. By properly signing your custom boot images, you ensure the integrity of your device’s software, maintain a trusted boot chain, and mitigate the risks associated with tampering. This guide has provided you with the knowledge and practical steps to achieve Verified Boot compliance, empowering you to build and deploy more secure Android systems.