avbroot

(This page is also available in: Russian (Русский).)

avbroot is a tool for modifying Android A/B OTA images reproducibly and re-signing them with custom keys. It also includes a collection of subcommands for packing and unpacking numerous Android image formats.

Having a good understanding of how AVB and A/B OTAs work is recommended prior to using avbroot. At the very least, please make sure the warnings and caveats are well-understood to avoid the risk of hard bricking.

Requirements

Only devices that use modern A/B partitioning are supported. This is the case for most non-Samsung devices launched with Android 10 or newer. To check if a device uses this partitioning scheme, open the OTA zip file and check that:
- payload.bin exists
- META-INF/com/android/metadata (Android 10-11) or META-INF/com/android/metadata.pb (Android 12+) exists
The device must support using a custom public key for the bootloader's root of trust. This is normally done via the fastboot flash avb_custom_key command.

A list of devices known to work can be found in the issue tracker at #299.

Patches

avbroot applies the following patches to the partition images:

The boot or init_boot image, depending on device, is patched to enable root access if requested.
The boot, recovery, or vendor_boot image, depending on device, is patched to replace the OTA signature verification certificates with the custom OTA signing certificate. This allows future patched OTAs to be sideloaded from recovery mode after the bootloader has been locked. It also prevents accidental flashing of the original unpatched OTA.
The system image is also patched to replace the OTA signature verification certificates. This prevents the OS' system updater app from installing an unpatched OTA and also allows the use of custom OTA updater apps.

Warnings and Caveats

Always leave the OEM unlocking checkbox enabled when using a locked bootloader while rooted. This is critically important. Root access allows the boot partition to potentially be overwritten, either accidentally or intentionally, with an image that is not properly signed. 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.

Repeat: ALWAYS leave OEM unlocking enabled if rooted.
Any operation that causes an improperly-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). A couple ways an improperly-signed boot image could be flashed include:
- The Direct install method for updating Magisk. Magisk updates must be done by repatching the OTA, not via the app.
- The Uninstall Magisk feature in Magisk. If root access is no longer needed, Magisk must be removed by repatching the OTA with the --rootless option, not via the app.
If the boot image is ever modified, do not reboot. Open an issue for support and be very clear about what steps were done that lead to the situation. If Android is still running and root access works, it might be possible to recover without wiping and starting over.

Usage

Make sure the caveats listed above are understood. It is possible to hard brick by doing the wrong thing!
Download the latest version from the releases page. To verify the digital signature, see the verifying digital signatures section.

avbroot is a standalone executable. It does not need to be installed and can be run from anywhere.
Follow the steps to generate signing keys.

Skip this step if you're updating Android, Magisk, or KernelSU after you've already performed an initial setup. There's no need to generate new signing keys for updates: any further updates must use the keys that were created during the initial setup.
Patch the OTA zip. The base command is:
```
avbroot ota patch \
    --input /path/to/ota.zip \
    --key-avb /path/to/avb.key \
    --key-ota /path/to/ota.key \
    --cert-ota /path/to/ota.crt \
```
Add the following additional arguments to the end of the command depending on how you want to configure root access.
- To enable root access with Magisk:
```
--magisk /path/to/magisk.apk \
--magisk-preinit-device <name>
```
  If you don't know the Magisk preinit partition name, see the Magisk preinit device section for steps on how to find it.
  
  If you prefer to manually patch the boot image via the Magisk app instead of letting avbroot handle it, use the following arguments instead:
```
--prepatched /path/to/magisk_patched-xxxxx_yyyyy.img
```
- To enable root access with KernelSU:
```
--prepatched /path/to/kernelsu/boot.img
```
- To leave the OS unrooted:
```
--rootless
```
For more details on the options above, see the advanced usage section.

If --output is not specified, then the output file is written to <input>.patched.
The patched OTA is ready to go! To flash it for the first time, follow the steps in the initial setup section. For updates, follow the steps in the updates section.

Generating Keys

avbroot signs several components while patching an OTA zip:

the boot images
the vbmeta images
the OTA payload
the OTA zip itself

The first two components are signed with an AVB key and latter two components are signed with an OTA key. They can be the same key, though the following steps show how to generate two separate keys.

When patching OTAs for multiple devices, generating unique keys for each device is strongly recommended because it prevents an OTA for the wrong device being accidentally flashed.

Generate the AVB and OTA signing keys.

avbroot key generate-key -o avb.key
avbroot key generate-key -o ota.key

Convert the public key portion of the AVB signing key to the AVB public key metadata format. This is the format that the bootloader requires when setting the custom root of trust.
```
avbroot key encode-avb -k avb.key -o avb_pkmd.bin
```
Generate a self-signed certificate for the OTA signing key. This is used by recovery to verify OTA updates when sideloading.
```
avbroot key generate-cert -k ota.key -o ota.crt
```

The commands above are provided for convenience. avbroot is compatible with any standard PKCS#8-encoded 4096-bit RSA private key and PEM-encoded X509 certificate, like those generated by openssl.

If you lose your AVB or OTA signing key, you will no longer be able to sign new OTA zips. You will have to generate new signing keys and unlock your bootloader again (triggering a data wipe). Follow the Usage section as if doing an initial setup.

Initial setup

Make sure that the version of fastboot is 34 or newer. Older versions have bugs that prevent the fastboot flashall command (required later) from working properly.
```
fastboot --version
```
Reboot into fastboot mode and unlock the bootloader if it isn't already unlocked. This will trigger a data wipe.
```
fastboot flashing unlock
```
When setting things up for the first time, the device must already be running the correct OS. Flash the original unpatched OTA if needed.
Extract the partition images from the patched OTA that are different from the original.
```
avbroot ota extract \
    --input /path/to/ota.zip.patched \
    --directory extracted \
    --fastboot
```
If you prefer to extract and flash all OS partitions just to be safe, pass in --all.
Set the ANDROID_PRODUCT_OUT environment variable to the directory containing the extracted files.

For sh/bash/zsh (Linux, macOS, WSL):
```
export ANDROID_PRODUCT_OUT=extracted
```
For PowerShell (Windows):
```
$env:ANDROID_PRODUCT_OUT = "extracted"
```
For cmd (Windows):
```
set ANDROID_PRODUCT_OUT=extracted
```
Flash the partition images that were extracted.
```
fastboot flashall --skip-reboot
```
Note that this only flashes the OS partitions. The bootloader and modem/radio partitions are left untouched due to fastboot limitations. If they are not already up to date or if unsure, after fastboot completes, follow the steps in the updates section to sideload the patched OTA once. Sideloading OTAs always ensures that all partitions are up to date.

Alternatively, for Pixel devices, running flash-base.sh from the factory image will also update the bootloader and modem.

Set up the custom AVB public key in the bootloader after rebooting from fastbootd to bootloader.

fastboot reboot-bootloader
fastboot erase avb_custom_key
fastboot flash avb_custom_key /path/to/avb_pkmd.bin

[Optional] Before locking the bootloader, reboot into Android once to confirm that everything is properly signed.

Install the Magisk or KernelSU app and run the following command:
```
adb shell su -c 'dmesg | grep libfs_avb'
```
If AVB is working properly, the following message should be printed out:
```
init: [libfs_avb]Returning avb_handle with status: Success
```
Alternatively, the Android build of avbroot can also be used

Avbroot

Install / Use

README