Android_boot_image_editor

A tool for reverse engineering Android ROM images.

Getting Started

install required packages

Linux: sudo apt install git device-tree-compiler lz4 xz-utils zlib1g-dev openjdk-11-jdk gcc g++ python3 python-is-python3

Mac: brew install lz4 xz dtc

Windows Subsystem for Linux(WSL): sudo apt install git device-tree-compiler lz4 xz-utils zlib1g-dev openjdk-11-jdk gcc g++ python

Windows: Make sure you have python3, JDK9+ and openssl properly installed. An easy way is to install Anaconda and Oracle JDK 11, then run the program under anaconda PowerShell. Or install them with chocolate: choco install openssl dtc-msys2

Parsing and packing

Put your boot.img to current directory, then start gradle 'unpack' task:

cp <original_boot_image> boot.img
./gradlew unpack

Your get the flattened kernel and /root filesystem under ./build/unzip_boot:

build/unzip_boot/
├── boot.json     (boot image info)
├── boot.avb.json (AVB only)
├── kernel
├── second        (2nd bootloader, if exists)
├── dtb           (dtb, if exists)
├── dtbo          (dtbo, if exists)
└── root          (extracted initramfs)

Then you can edit the actual file contents, like rootfs or kernel. Now, pack the boot.img again

./gradlew pack

You get the repacked boot.img at $(CURDIR):

boot.img.signed

Well done you did it! The last step is to star this repo :smile

live demo

<img src=doc/op.gif width="615" height="492">

Supported ROM image types

Image Type	file names	platforms
boot images	boot.img, vendor_boot.img	all
recovery images	recovery.img, recovery-two-step.img	all
vbmeta images	vbmeta.img, vbmeta_system.img etc.	all
dtbo images	dtbo.img	linux & mac
sparse images	system.img, vendor.img, product.img etc.	linux & mac

Please note that the boot.img MUST follows AOSP verified boot flow, either Boot image signature in VBoot 1.0 or AVB HASH footer (a.k.a. AVB) in VBoot 2.0.

compatible devices

Device Model	Manufacturer	Compatible	Android Version	Note
ADT-3 (adt3)	Askey/Google	Y	12 (spp2.210219.010)	amlogic inside,

Android TV | | Pixel 3 (blueline) | Google | Y | 12 (spp2.210219.008,

2021)| | | Pixel 3 (blueline) | Google | Y | 11 (RP1A.200720.009,

2020)| more ... | | Pixel 3 (blueline) | Google | Y | Q preview (qpp2.190228.023,

2019)| more ... | | Redmi K30 4G (phoenix[n]) | XiaoMi | Y | 10 | verified by @eebssk1 | | TS10 | Topway | Y | 10 | car headunit, @mariodantas | | Pixel XL (marlin) | HTC | Y | 9.0.0 (PPR2.180905.006,

Sep 2018)| more ... | | K3 (CPH1955) | OPPO | Y for recovery.img

N for boot.img | Pie | more | | Z18 (NX606J) | ZTE | Y | 8.1.0 | more... | | Nexus 9 (volantis/flounder) | HTC | Y(with some tricks) | 7.1.1 (N9F27M, Oct 2017) | tricks| | Nexus 5x (bullhead) | LG | Y | 6.0.0_r12 (MDA89E) | | | Moto X (2013) T-Mobile | Motorola | N | | | | X7 (PD1602_A_3.12.8) | VIVO | N | ? | Issue 35 |

more examples

working with recovery.img

Please remember to clean the work directory first.

rm *.img
cp <your_recovery_image> recovery.img
./gradlew unpack
./gradlew pack

working with vbmeta.img

rm *.img
cp <your_vbmeta_image> vbmeta.img
./gradlew unpack
./gradlew pack

working with boot.img and vbmeta.img

If your vbmeta.img contains hash of boot.img, you MUST update vbmeta image together.

rm *.img
cp <your_boot_image> boot.img
cp <your_vbmeta_image> vbmeta.img
./gradlew unpack
./gradlew pack

Your boot.img.signed and vbmeta.img.signd will be updated together, then you can flash them to your device.

working with vendor_boot.img + vbmeta.img (Pixel 5 etc.)

Most devices include hash descriptor of vendor_boot.img in vbmeta.img, so if you need to modify vendor_boot.img, you need to update vbmeta.img together.

rm *.img
cp <your_vendor_boot_image> vendor_boot.img
cp <your_vbmeta_image> vbmeta.img
./gradlew unpack
./gradlew pack
./gradlew flash

Please note that to use 'gradle flash', your host machine must be connectted to your DUT with adb, and you already 'adb root'.

How to disable AVB verification

The idea is to set flag=2 in main vbmeta.

rm *.img
cp <your_vbmeta_image> vbmeta.img
./gradlew unpack
vim -u NONE -N build/unzip_boot/vbmeta.avb.json  -c ":19s/0/2/g" -c ":wq"
./gradlew pack

Then flash vbmeta.img.signed to your device.

boot.img layout

Read layout of Android boot.img and vendor_boot.img.

References and Acknowledgement

more ...

Android version list https://source.android.com/source/build-numbers.html

Android build-numbers https://source.android.com/setup/start/build-numbers

cpio & fs_config

https://android.googlesource.com/platform/system/core

https://www.kernel.org/doc/Documentation/early-userspace/buffer-format.txt

AVB

https://android.googlesource.com/platform/external/avb/

boot_signer

https://android.googlesource.com/platform/system/extras

mkbootimg

https://android.googlesource.com/platform/system/tools/mkbootimg/+/refs/heads/master/

boot header definition

https://android.googlesource.com/platform/system/tools/mkbootimg/+/refs/heads/master/include/bootimg/bootimg.h

kernel info extractor

https://android.googlesource.com/platform/build/+/refs/heads/master/tools/extract_kernel.py

mkdtboimg

https://android.googlesource.com/platform/system/libufdt/

libsparse

https://android.googlesource.com/platform/system/core/+/refs/heads/master/libsparse/

Android Nexus/Pixle factory images

https://developers.google.cn/android/images

This project is developed with products by Jetbrains.