Android_boot_image_editor
A tool for reverse engineering Android ROM images.
Getting Started
install required packages
Mac: brew install lz4 xz dtc
Linux: sudo apt install git device-tree-compiler lz4 xz-utils zlib1g-dev openjdk-11-jdk gcc g++ python3
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.
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
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) | Y | 12 (spp2.210219.008, 2021) |
||
Pixel 3 (blueline) | Y | 11 (RP1A.200720.009, 2020) |
more ... | |
Pixel 3 (blueline) | 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.