You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
365 lines
13 KiB
Markdown
365 lines
13 KiB
Markdown
# Android_boot_image_editor
|
|
[](https://github.com/cfig/Android_boot_image_editor/actions/workflows/main.yml)
|
|
[](http://www.apache.org/licenses/LICENSE-2.0.html)
|
|
|
|
A tool for reverse engineering Android ROM images.
|
|
|
|
## Requirements
|
|
Make sure you have [JDK11+](https://www.oracle.com/java/technologies/downloads/#java17) and [Python3](https://www.python.org/downloads/).
|
|
|
|
* Linux / WSL: `sudo apt install git device-tree-compiler lz4 xz-utils zlib1g-dev openjdk-17-jdk gcc g++ python3 python-is-python3 p7zip-full android-sdk-libsparse-utils erofs-utils`
|
|
|
|
* Mac: `brew install lz4 xz dtc`
|
|
|
|
* Windows: Install openssl and device-tree compiler with [chocolate](https://chocolatey.org/install)
|
|
`choco install openssl dtc-msys2 zip vim`
|
|
|
|
## Getting Started
|
|
Put your boot.img to current directory, then start gradle 'unpack' task:
|
|
|
|
```bash
|
|
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
|
|
<!--  -->
|
|
<p align="center">
|
|
<img src=doc/op.gif width="615" height="492">
|
|
</p>
|
|
|
|
## Supported ROM image types
|
|
|
|
| Image Type | file names | platforms | note |
|
|
| --------------- |----------------------------------------------------------------|-------------|-------------------------|
|
|
| boot | boot.img, init_boot.img, boot-debug.img, boot-test-harness.img | all | |
|
|
|vendor boot | vendor_boot.img, vendor_boot-debug.img, vendor_kernel_boot.img | all | |
|
|
| recovery | recovery.img, recovery-two-step.img | all | |
|
|
| vbmeta | vbmeta.img, vbmeta_system.img etc. | all | |
|
|
| dtbo | dtbo.img | linux & mac | |
|
|
| dtb | *.dtb | linux & mac | |
|
|
| sparse images | system.img, vendor.img, product.img etc. | linux | |
|
|
| OTA payload | payload.bin | all | Windows git-bash |
|
|
|
|
Please note that the boot.img MUST follows AOSP verified boot flow, either [Boot image signature](https://source.android.com/security/verifiedboot/verified-boot#signature_format) in VBoot 1.0 or [AVB HASH footer](https://android.googlesource.com/platform/external/avb/+/master/README.md#The-VBMeta-struct) (a.k.a. AVB) in VBoot 2.0.
|
|
|
|
## compatible devices
|
|
|
|
| Device Model | Manufacturer | Compatible | Android Version | Note |
|
|
|--------------------------------|--------------|----------------------|--------------------------|------|
|
|
| Pixel 7 (panther) | Google | Y | 13 (TQ2A.230505.002) <Br>2023)| |
|
|
| ADT-3 (adt3) | Askey/Google | Y | 12 (spp2.210219.010) | amlogic inside, <Br>Android TV |
|
|
| Pixel 3 (blueline) | Google | Y | 12 (spp2.210219.008, <Br>2021)| |
|
|
| Pixel 3 (blueline) | Google | Y | 11 (RP1A.200720.009, <Br>2020)| [more ...](doc/additional_tricks.md#pixel-3-blueline) |
|
|
| Pixel 3 (blueline) | Google | Y | Q preview (qpp2.190228.023, <Br>2019)| [more ...](doc/additional_tricks.md#pixel-3-blueline) |
|
|
| Redmi K30 4G (phoenix[n]) | XiaoMi | Y | 10 | [verified](https://github.com/cfig/Android_boot_image_editor/issues/17#issuecomment-817169307) by @eebssk1 |
|
|
| TS10 | Topway | Y | 10 | car headunit, @mariodantas |
|
|
| Pixel XL (marlin) | HTC | Y | 9.0.0 (PPR2.180905.006, <Br>Sep 2018)| [more ...](doc/additional_tricks.md#pixel-xl-marlin) |
|
|
| K3 (CPH1955) | OPPO | Y for recovery.img<Br> N for boot.img | Pie | [more](doc/additional_tricks.md#k3-cph1955) |
|
|
| Z18 (NX606J) | ZTE | Y | 8.1.0 | [more...](doc/additional_tricks.md#nx606j) |
|
|
| Nexus 9 (volantis/flounder) | HTC | Y(with some tricks) | 7.1.1 (N9F27M, Oct 2017) | [tricks](doc/additional_tricks.md#tricks-for-nexus-9volantis)|
|
|
| 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](https://github.com/cfig/Android_boot_image_editor/issues/35) |
|
|
| Realme GT Neo 3 | Realme | N | 12 | [Issue 105](https://github.com/cfig/Android_boot_image_editor/issues/105) |
|
|
|
|
## more examples
|
|
<details>
|
|
<summary>working with recovery.img</summary>
|
|
|
|
Please remember to clean the work directory first.
|
|
|
|
```bash
|
|
rm *.img
|
|
cp <your_recovery_image> recovery.img
|
|
./gradlew unpack
|
|
./gradlew pack
|
|
```
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary>working with vbmeta.img</summary>
|
|
|
|
|
|
```bash
|
|
rm *.img
|
|
cp <your_vbmeta_image> vbmeta.img
|
|
./gradlew unpack
|
|
./gradlew pack
|
|
```
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary>clean workspace</summary>
|
|
When you finished current work and need to clean the workspace for next image, it's a good idea to call the `clear` command:
|
|
|
|
```bash
|
|
./gradlew clear
|
|
```
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary>working with boot.img and vbmeta.img</summary>
|
|
|
|
If your vbmeta.img contains hash of boot.img, you MUST update vbmeta image together.
|
|
|
|
```bash
|
|
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.
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary>working with vendor_boot.img + vbmeta.img (Pixel 5 etc.)</summary>
|
|
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.
|
|
|
|
```bash
|
|
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'.
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary>How to edit device tree blob(dtb) inside vendor_boot.img</summary>
|
|
|
|
If you want to edit the device-tree blob in place:
|
|
|
|
```bash
|
|
cp <your_vendor_boot_image> vendor_boot.img
|
|
cp <your_vbmeta_image> vbmeta.img
|
|
./gradlew unpack
|
|
==> now you can edit build/unzip_boot/dtb.dts directly
|
|
./gradlew pack
|
|
```
|
|
|
|
During unpack stage, dtb will be dumped to file `build/unzip_boot/dtb`, dts will be decompiled to `build/unzip_boot/dtb.dts`.
|
|
You can edit `dtb.dts` directly, and it will be compiled to dtb duing repack stage.
|
|
|
|
If you just want to replace the dtb with the one that is compiled outside this tool, please
|
|
|
|
```bash
|
|
cp <your_vendor_boot_image> vendor_boot.img
|
|
cp <your_vbmeta_image> vbmeta.img
|
|
./gradlew unpack
|
|
rm build/unzip_boot/dtb.dts
|
|
cp <your_dtb> build/unzip_boot/dtb
|
|
./gradlew pack
|
|
```
|
|
|
|
</details>
|
|
|
|
<details>
|
|
|
|
<summary>How to pull device tree blob(dtb) from a rooted device</summary>
|
|
|
|
If you have a rooted device and want to pull /proc/device-tree
|
|
```bash
|
|
touch fake.dtb
|
|
./gradlew pull
|
|
```
|
|
This tool will copy `dtc` to the target device via `adb`, and dump the dtb and dts file. Eventually you should get something like this
|
|
```
|
|
+--------+------------------------------+
|
|
| What | Where |
|
|
+--------+------------------------------+
|
|
| source | /proc/device-tree |
|
|
+--------+------------------------------+
|
|
| DTB | panther.dtb |
|
|
+--------+------------------------------+
|
|
| DTS | build/unzip_boot/panther.dts |
|
|
+--------+------------------------------+
|
|
|
|
```
|
|
|
|
</details>
|
|
|
|
<details>
|
|
|
|
<summary>How to work edit device tree blob(dtb) file</summary>
|
|
|
|
If you have a dtb file and want to edit its content
|
|
```bash
|
|
cp <your_dtb_file> .
|
|
./gradlew unpack
|
|
```
|
|
This tool will decompile it and put the decompiled source to build/unzip_boot.
|
|
|
|
```
|
|
Unpack Summary of panther.dtb
|
|
+------+------------------------------+
|
|
| What | Where |
|
|
+------+------------------------------+
|
|
| DTB | panther.dtb |
|
|
+------+------------------------------+
|
|
| DTS | build/unzip_boot/panther.dts |
|
|
+------+------------------------------+
|
|
```
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary>working with system.img</summary>
|
|
|
|
```bash
|
|
cp <your_system_image> system.img
|
|
./gradlew unpack
|
|
```
|
|
You get `system.img.unsparse`, that's a plain ext4 filesystem data.
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary>How to disable AVB verification</summary>
|
|
|
|
The idea is to set flag=2 in main vbmeta.
|
|
|
|
```bash
|
|
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.
|
|
|
|
</details>
|
|
|
|
<details>
|
|
|
|
<summary>How to merge init_boot.img into boot.img</summary>
|
|
|
|
* unpack init_boot.img and copy out "build/unzip_boot/root".
|
|
* clear workspace by `gradle clear`, then unpack boot.img
|
|
* copy back the "build/unzip_boot/root"
|
|
* edit build/unzip_boot/boot.json
|
|
- change `ramdisk.size` to 1
|
|
- change `ramdisk.file` from "build/unzip_boot/ramdisk.img" to "build/unzip_boot/ramdisk.img.lz4"
|
|
|
|
</details>
|
|
|
|
<details>
|
|
|
|
<summary>work with payload.bin</summary>
|
|
|
|
- extract everything
|
|
|
|
Usage:
|
|
```
|
|
gradle unpack
|
|
```
|
|
|
|
- extract only 1 specified partition
|
|
Usage:
|
|
```
|
|
gradle unpack -Dpart=<part_name>
|
|
```
|
|
Example:
|
|
```
|
|
gradle unpack -Dpart=boot
|
|
gradle unpack -Dpart=system
|
|
```
|
|
|
|
Note:
|
|
"build/payload/" will be deleted before each "unpack" task
|
|
|
|
</details>
|
|
|
|
|
|
<details>
|
|
|
|
<summary>work with apex images</summary>
|
|
|
|
AOSP already has tools like apexer, deapexer, sign_apex.py, these should suffice the needs on .apex and .capex.
|
|
Refer to Issue https://github.com/cfig/Android_boot_image_editor/issues/120
|
|
|
|
- For those who may be interested in apex generation flow, there is a graph here
|
|
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary>How to work with vendor_dlkm.img</summary>
|
|
|
|
```bash
|
|
cp <your_vendor_dlkm.img> vendor_dlkm.img
|
|
cp <your_vbmeta_image> vbmeta.img
|
|
./gradlew unpack
|
|
# replace your .ko
|
|
./gradlew pack
|
|
```
|
|
Then flash `vbmeta.img.signed` and `vendor_dlkm.img.signed` to the device.
|
|
|
|
</details>
|
|
|
|
## boot.img layout
|
|
Read [boot layout](doc/layout.md) of Android boot.img and vendor\_boot.img.
|
|
Read [misc layout](doc/misc_image_layout.md) of misc\.img
|
|
|
|
## References and Acknowledgement
|
|
<details>
|
|
<summary>more ...</summary>
|
|
|
|
Android version list https://source.android.com/source/build-numbers.html<br/>
|
|
Android build-numbers https://source.android.com/setup/start/build-numbers
|
|
|
|
cpio & fs\_config<br>
|
|
https://android.googlesource.com/platform/system/core<br/>
|
|
https://www.kernel.org/doc/Documentation/early-userspace/buffer-format.txt<br/>
|
|
AVB<br/>
|
|
https://android.googlesource.com/platform/external/avb/<br/>
|
|
boot\_signer<br/>
|
|
https://android.googlesource.com/platform/system/extras<br/>
|
|
mkbootimg<br/>
|
|
https://android.googlesource.com/platform/system/tools/mkbootimg/+/refs/heads/master/<br/>
|
|
boot header definition<br/>
|
|
https://android.googlesource.com/platform/system/tools/mkbootimg/+/refs/heads/master/include/bootimg/bootimg.h<br/>
|
|
kernel info extractor<br/>
|
|
https://android.googlesource.com/platform/build/+/refs/heads/master/tools/extract_kernel.py<br/>
|
|
mkdtboimg<br/>
|
|
https://android.googlesource.com/platform/system/libufdt/<br/>
|
|
libsparse<br/>
|
|
https://android.googlesource.com/platform/system/core/+/refs/heads/master/libsparse/<br/>
|
|
Android Nexus/Pixle factory images<br/>
|
|
https://developers.google.cn/android/images<br/>
|
|
|
|
</details>
|
|
|