avbroot

avbroot is a script for patching Android boot images with Magisk root while preserving AVB (Android Verified Boot) using custom keys.

I do not recommend using this project without a deep understanding of how AVB, init, and fastbootd work. It is meant for use with proprietary stock firmware. For folks running open-source Android firmware, I highly recommend adding Magisk to the build process and then compiling from source instead.

Patches

avbroot applies two patches to the boot images:

• Magisk is applied to the boot image as if it were done from the Magisk Manager app.

• The vendor_boot image is patched to allow the userspace fastbootd mode to flash partitions even when the bootloader is locked. This is done by patching the /system/bin/fastbootd binary in the ramdisk to look at the ro.fake.verifiedbootstate property instead of the ro.boot.verifiedbootstate property. ro.fake.verifiedbootstate=orange is appended to /prop.default. These changes apply only when booted into recovery.

  This is not as secure as the default AVB setup, but is necessary or else patched updates can't be flashed. An attacker with physical access is able to flash partitions, but they should not be bootable because the chain of trust will no longer be intact. That's the theory anyway. It is easier for the attacker to attempt an exploit.

  A future version of avbroot might switch to generating OTAs and patching the list of allowed OTA signing certificates. I do not know if this is a feasible option yet, but it would prevent flashing arbitrary partitions.

Warnings and Caveats

• This project is not meant to be usable for any device. Most devices don't support relocking the bootloader using a custom public key. I've only tested with the Android 13 stock image on a Google Pixel 6 Pro.

• Do not ever disable the OEM unlocking checkbox when using a locked bootloader with root. This is critically important. With root access, it is possible to corrupt the running system, for example by zeroing out the boot partition. In this scenario, if the checkbox is turned off, both the OS and recovery mode will be made unbootable and fastboot flashing unlock will not be allowed. This effectively renders the device hard bricked.

• Any operation that causes an unsigned or differently-signed boot image to be flashed will result in the device being unbootable and unrecoverable without unlocking the bootloader again (and thus, triggering a data wipe). This includes:

  • Sideloading an firmware update. It's critical that newly patched images are flashed before rebooting. Disabling the Automatic system updates option in Android's Developer Options for A/B OTA updates is recommended.

  • The Direct install method for updating Magisk. Magisk updates must be done by repatching as well.

Generating Keys

At least one key is needed for signing the root vbmeta image. The key can be generated by running:

• for an encrypted key:

  openssl genrsa 4096 | openssl pkcs8 -topk8 -scrypt -out avb.pem
  

• for an unencrypted key (not recommended unless stored in eg. a LUKS encrypted container):

  openssl genrsa 4096 -out avb.pem
  

The AVB public key metadata can be extracted by running the following command. This is the file used for fastboot flash avb_custom_key.

external/avb/avbtool extract_public_key --key avb.pem --output avb_pkmd.bin

avbroot tries to maintain the structure of the original signing chain. This means if the original boot or vendor_boot image was separately signed (AVB chainload descriptor) instead of including the hash in the root vbmeta image (AVB hash descriptor), then the patched image must also be signed. The patched image can be signed either with the same AVB root key or with a different key.

To determine whether an image is signed, run:

external/avb/avbtool.py info_image --image /path/to/vbmeta.img

If a partition is listed under a Chain Partition descriptor, then that image itself is signed. Otherwise, if it's listed under a Hash descriptor, then the image is not signed and a hash of the image is included in the (signed) root vbmeta.

Usage

1. Make sure the caveats listed above are understood. It is possible to hard brick by doing the wrong thing!

2. Follow the steps to generate signing keys.

3. Patch the boot, vendor_boot, and vbmeta images. These can be extracted from either a factory image or a full OTA.

   For example, with Android 13 on the Google Pixel 6 Pro, where boot itself is signed, but vendor_boot is not:

   python avbroot.py \
       --input-vbmeta /path/to/vbmeta.img \
       --input-boot /path/to/boot.img \
       --input-vendor-boot /path/to/vendor_boot.img \
       --privkey-vbmeta /path/to/avb.pem \
       --privkey-boot /path/to/avb.pem \
       --magisk /path/to/magisk.apk
   

   This will use avb.pem to sign both the root vbmeta image and the boot image.

   If --output-<image> parameters are not specified, then the output file is written to <input path>.patched.

4. [Initial setup only] Unlock the bootloader.

5. [Initial setup only] Flash the AVB public key metadata.

   fastboot flash avb_custom_key /path/to/avb_pkmd.bin
   

6. Flash the patched images.

   fastboot flash boot /path/to/boot.img.patched
   fastboot flash vendor_boot /path/to/vendor_boot.img.patched
   fastboot flash vbmeta /path/to/vbmeta.img.patched
   

7. [Initial setup only] Lock the bootloader. Do not uncheck OEM unlocking!

Updates

To update Android or Magisk:

1. Follow step 3 in the previous section to repatch the images.

2. Reboot to recovery mode. If stuck at a No command screen, press the volume up button once while holding down the power button.

3. If updating Android, first sideload the Android update. Do not reboot or else a bootloader unlock and factory reset will be required to recover!

4. Follow step 6 in the previous section to flash the patched images.

5. Reboot.

Contributing

I'm currently not accepting contributions for avbroot as I only intend to maintain the minimum amount of code needed for it to work on my devices. I'd encourage others to fork and modify avbroot for their own needs.

License

avbroot is licensed under GPLv3. Please see LICENSE for the full license text.