superturtlee/gbl_root_canoe

# GBL Root Canoe [中文版](README_zh.md) `gbl_root_canoe` 是一个基于 EDK2 的工作区，用于修补 Qualcomm ABL (Android Bootloader) 镜像中的 EFI 应用程序。它利用 GBL (Generic Bootloader Loader) 漏洞来注入自定义 EFI，主要用于在骁龙 8 Gen 5 / 8 Elite (Gen 5) 设备上实现**伪装已锁定 Bootloader** 的状态，以绕过 Bootloader 解锁检测。修补后的 EFI 通常会被刷入 `efisp` 分区。 ## 构建指南 本节面向希望从源码编译该工具包的开发者。 ### 前置条件 你必须在 **Linux** 主机上构建此项目： - `gcc` / `clang`, `lld`, `make`, `zip`, `python3` - `liblzma-dev`（用于编译 `extractfv`） - **Android NDK**（运行 `make build_module` 为 Android 交叉编译工具时需要） - **MinGW-w64** ### 构建目标 **注意：** 你**不需要**提供 `abl.img` 即可构建可分发的工具包或 Magisk 模块。 - **`make target_toolkit_linux`** 构建 EDK2 原生 payload (`loader.elf`) 并为 Linux 编译修补工具（`extractfv`、`patch_abl`、`elf_inject` 等）。 - **`make target_toolkit_windows`** 类似于 `dist_loader`，但使用 MinGW-w64 将修补工具交叉编译为 Windows `.exe` 程序。 - **`make target_magisk_module`** 使用你的 NDK 为 Android 交叉编译修补工具，并构建 EDK2 payload。 - **`make target_generic_efi`** 内嵌修补工具，旨在兼容多种设备型号。然而，其对高版本的兼容性较差，正逐渐被弃用。 ## 用户指南 有关更详细的说明，请参阅 [Wiki](https://github.com/superturtlee/gbl_root_canoe/wiki)。 ### 1. 使用 Magisk 模块（设备端） Magisk 模块旨在直接在已 root 的 Android 设备上运行。 **要求：** - 设备必须为骁龙 8 Gen 5 / 8 Elite (Gen 5)。 - Bootloader 必须已解锁。 - Kernel 绝不能带有 Baseband Guard。 **安装与使用：** 通过 root 管理器（如 KernelSU、Magisk 或 APatch）刷入 Magisk 模块时，自定义脚本会通过音量键与你进行交互： - **音量加（首次安装）：** 脚本会自动提取当前的 `.abl` 镜像，对其进行修补，并将修补后的文件直接刷入 `/dev/block/by-name/efisp`。此操作完成后，你必须重启进入 Recovery 模式并**格式化 Data**。再次启动后，再次安装此模块（第二次选择音量减）以完成安装。 - **音量减（OTA 保留或格式化后）：** 用于在 OTA 更新后保留 BL 版本。在进行 OTA 更新前，使用该模块自动降级 ABL，然后重启系统。 ### 2. 使用 PC 工具包（Linux / Windows） 如果你下载了 `target_toolkit_linux` 或 `target_toolkit_windows` zip 文件： 1. 在 PC 上解压工具包 zip。 2. 将你设备的官方 `abl.img` 放入工具包的 `images/`（或 `images\`）目录中。 3. **Linux：** 运行 `bash build.sh`（或 `make build`）。**Windows：** 运行 `build.bat`。 4. 脚本将提取、修补并注入自定义 payload，输出修改后的文件 `ABL_with_superfastboot.efi`。（检查输出日志；如果提示 "Warning: Failed to patch ABL GBL"，则说明设备不易受此漏洞影响，需要降级 ABL）。 ### 3. 使用预修补的 EFI 下载文件名中包含手机型号或代号的特定发布版本。使用压缩包中的 `ABL_with_superfastboot.efi` 或 `ABL.efi` 通过 `fastboot` 命令进行引导或刷入（例如，`fastboot flash efisp ABL_with_superfastboot.efi`）。强烈建议使用带有 `superfastboot` 的版本，以保留后备的 fastboot 刷入功能。 ### 4. 使用通用 EFI（已弃用） 下载 `generic_superfastboot.efi` 并执行相关的刷入步骤。由于不同 OEM 设备功能之间存在兼容性问题和不稳定性，它在某些型号或 OS 版本上可能表现不佳，**不再推荐使用**。 ### 5. OTA 升级 在重启进行 OTA 更新之前，请使用该模块刷入并保留旧的 ABL 版本。如果你正在进行大版本升级，建议勾选“Update efisp”，否则设备可能会卡在开机启动画面。 ### 6. Superfastboot 使用说明 当启用了 OEM Unlocking 并且启动时出现白色警告文字时，你必须按下**音量减**以进入 Superfastboot 模式。 常用命令包括： - **临时引导 EFI 文件（不刷入）**：`fastboot boot xxx.efi` - **锁定与解锁（与 BL 相关）**： - 锁定 BL，会触发数据擦除：`fastboot flashing lock` - 解锁 BL，不擦除数据：`fastboot flashing unlock` 或 `fastboot flashing unlock_critical` - *注意：如果 TEE 状态不一致，设备将拒绝提供数据密钥，导致数据无法访问。* - **刷入与擦除**： - `fastboot flash ` - `fastboot erase ` - **重启**： - `fastboot reboot bootloader`（下次正常启动将进入官方 Fastboot） - `fastboot reboot recovery` - `fastboot reboot` ### 7. 不同版本说明 1. `ABL.efi`：修补后的 ABL。 2. `ABL_original`：供开发者在 IDA 中进行分析，用于错误报告。**切勿刷入**。 3. `ABL_with_superfastboot.efi`：集成了 superfastboot 的修补后 ABL。 4. `loader.elf`：superfastboot 二进制文件。未链接为 EFI 格式，旨在与 toolbox 链接。无法直接刷入。

标签：bootloader, Cutter, EDK2, EFI注入, 安卓, 客户端加密, 底层开发, 移动设备