avbroot

(此页面也可用以下语言查看：俄语 (Русский)。]

avbroot 是一个用于可复现地修改 Android A/B OTA 镜像并使用自定义密钥重新签名的工具。它还包含一系列子命令，用于打包和解包多种 Android 镜像格式。

在使用 avbroot 之前，建议充分了解 AVB 和 A/B OTA 的工作原理。至少，请确保警告和注意事项已被充分理解，以避免变砖的风险。

要求

• 仅支持使用现代 A/B 分区方案的设备。大多数搭载 Android 10 或更高版本且非三星品牌的设备均符合此条件。要检查设备是否使用此分区方案，请打开 OTA zip 文件并确认：

  • payload.bin 存在
  • META-INF/com/android/metadata (Android 10-11) 或 META-INF/com/android/metadata.pb (Android 12+) 存在

• 设备必须支持使用自定义公钥作为引导加载程序的信任根。这通常通过 fastboot flash avb_custom_key 命令完成。

  已知可用的设备列表可在问题跟踪器中的 #299 找到。

补丁

avbroot 会对分区镜像应用以下补丁：

• 根据设备不同，boot 或 init_boot 镜像会被修补，以便在请求时启用 root 访问权限。

• 根据设备不同，boot、recovery 或 vendor_boot 镜像会被修补，以将 OTA 签名验证证书替换为自定义 OTA 签名证书。这使得在引导加载程序锁定后，未来修补的 OTA 可以从恢复模式侧载。它还能防止意外刷入原始的未修补 OTA。

• system 镜像也会被修补，以替换 OTA 签名验证证书。这可以防止操作系统的系统更新器应用安装未修补的 OTA，同时也允许使用自定义 OTA 更新器应用。

警告与注意事项

• 在使用已锁定的引导加载程序且已获取 root 权限时，始终启用 OEM unlocking 复选框。 这一点至关重要。Root 权限可能导致启动分区被意外或故意覆盖为未正确签名的镜像。在这种情况下，如果关闭该复选框，操作系统和恢复模式都将无法启动，并且不允许 fastboot flashing unlock。这实际上会使设备变砖。

  重复强调：如果已获取 root 权限，始终启用 OEM unlocking。

• 任何导致刷入未正确签名的启动镜像的操作，都将导致设备无法启动且无法恢复，除非再次解锁引导加载程序（因此会触发数据擦除）。刷入未正确签名的启动镜像的几种情况包括：

  • 用于更新 Magisk 的 Direct install 方法。Magisk 更新必须通过重新修补 OTA 来完成，而不是通过应用。

• Magisk 中的 Uninstall Magisk 功能。如果不再需要 root 权限，必须通过 --rootless 选项重新修补 OTA 来移除 Magisk，而不是通过应用。

  如果启动镜像曾被修改，请勿重启。提交 issue 以获取支持，并非常清晰地说明导致该状况的操作步骤。如果 Android 仍在运行且 root 权限可用，可能无需清除数据即可恢复。

用法

1. 确保已理解上述注意事项。操作不当可能导致变砖！

2. 从发布页面下载最新版本。要验证数字签名，请参阅验证数字签名部分。

   avbroot 是一个独立的可执行文件。它无需安装，可以从任何位置运行。

3. 按照步骤生成签名密钥。

   如果您已经完成了初始设置，之后更新 Android、Magisk 或 KernelSU 时，请跳过此步骤。更新无需生成新的签名密钥：后续所有更新必须使用初始设置期间创建的密钥。

4. 修补 OTA zip。基础命令如下：

   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 \

根据您希望如何配置 root 访问权限，在命令末尾添加以下额外参数。

* 若要使用 Magisk 启用 root 访问权限：

    ```bash
    --magisk /path/to/magisk.apk \
    --magisk-preinit-device <name>
    ```

如果你不知道 Magisk preinit 分区名称，请参阅 Magisk preinit 设备部分 了解如何查找的步骤。

    如果你更喜欢通过 Magisk 应用手动修补 boot 镜像，而不是让 avbroot 处理，请使用以下参数：

    ```bash
    --prepatched /path/to/magisk_patched-xxxxx_yyyyy.img
    ```

• 要使用 KernelSU 启用 root 访问权限：

    ```bash
    --prepatched /path/to/kernelsu/boot.img
    ```
  

• 若要使操作系统保持未 root 状态：

    ```bash
    --rootless
    ```
  

有关上述选项的更多详细信息，请参阅高级用法部分。

如果未指定 `--output`，则输出文件将写入 `<input>.patched`。

5. 修补后的 OTA 已准备就绪！首次刷入时，请按照初始设置部分中的步骤操作。更新时，请按照更新部分中的步骤操作。

生成密钥

avroot 在修补 OTA zip 时会签署多个组件：

• boot 镜像
• vbmeta 镜像
• OTA 负载
• OTA zip 本身

前两个组件使用 AVB 密钥签署，后两个组件使用 OTA 密钥签署。它们可以是同一个密钥，但以下步骤展示了如何生成两个独立的密钥。

在为多个设备修补 OTA 时，强烈建议为每个设备生成唯一的密钥，因为这可以防止错误设备的 OTA 被意外刷入。

1. 生成 AVB 和 OTA 签署密钥。

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

avbroot 还支持后量子 ML-DSA 密钥（-t mldsa65）作为 AVB 签名密钥，但目前尚无设备的引导加载程序支持这些密钥。

2. 将 AVB 签名密钥的公钥部分转换为 AVB 公钥元数据格式。这是引导加载程序在设置自定义信任根时所需的格式。

   avbroot key encode-avb -k avb.key -o avb_pkmd.bin

3. 为 OTA 签名密钥生成自签名证书。此证书用于在侧载时由 recovery 验证 OTA 更新。

   avbroot key generate-cert -k ota.key -o ota.crt

上述命令仅为方便起见而提供。avbroot 兼容任何标准 PKCS#8 编码的 RSA/ML-DSA 私钥和 PEM 编码的 X509 证书，例如由 openssl 生成的密钥。

如果您丢失了 AVB 或 OTA 签名密钥，您将无法再签署新的 OTA zip 文件。您必须生成新的签名密钥并再次解锁 bootloader（这将触发数据清除）。请按照 Usage 部分 进行操作，如同进行初始设置一样。

AOSP 密钥

如果您正在从源代码构建 Android，以下是 avbroot 的密钥与 AOSP 密钥的对应关系：

avbroot	AOSP
avb.key	avb.pem
avb_pkmd.bin	avb_pkmd.bin
ota.key	releasekey.pk8
ota.crt	releasekey.x509.pem

要在 avbroot 中使用 AOSP 的 releasekey.pk8 密钥，必须先将其从 DER 格式转换为 PEM 格式：

openssl pkcs8 -topk8 -scrypt -in releasekey.pk8 -out ota.key -outform PEM

初始设置

1. 确保 fastboot 的版本为 35 或更高版本。旧版本存在 bug，会导致 fastboot flashall 命令（后续需要）无法正常工作。

   fastboot --version

2. 重启进入 fastboot 模式，如果 bootloader 尚未解锁，请解锁它。这将触发数据清除。

   fastboot flashing unlock

3. 首次设置时，设备必须已运行正确的操作系统。如有需要，请刷入原始的未修补 OTA。

4. 从修补后的 OTA 中提取与原始版本不同的分区镜像。

   avbroot ota extract \
       --input /path/to/ota.zip.patched \
       --directory extracted \
       --fastboot

如果你倾向于提取并刷写所有 OS 分区以确保安全，请传入 --all。

5. 将 ANDROID_PRODUCT_OUT 环境变量设置为包含提取文件的目录。

   对于 sh/bash/zsh（Linux、macOS、WSL）：

   export ANDROID_PRODUCT_OUT=extracted

对于 PowerShell（Windows）：

```powershell
$env:ANDROID_PRODUCT_OUT = "extracted"
```

对于 cmd (Windows)：

```bat
set ANDROID_PRODUCT_OUT=extracted
```

6. 刷入已提取的分区镜像。

```bash
fastboot flashall --skip-reboot
```

请注意，这仅会刷写 OS 分区。由于 fastboot 的限制，bootloader 和 modem/radio 分区将保持不变。如果它们尚未更新到最新版本或不确定其状态，请在 fastboot 完成后，按照 updates 部分 的步骤，侧载一次打过补丁的 OTA。侧载 OTA 始终能确保所有分区均为最新版本。

或者，对于 Pixel 设备，从工厂镜像中运行 `flash-base.sh` 也会更新 bootloader 和 modem。

7. 从 fastbootd 重启到 bootloader 后，在 bootloader 中设置自定义 AVB 公钥。

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

8. [可选] 在锁定引导加载程序之前，重启进入 Android 一次，以确认所有内容均已正确签名。

安装 Magisk 或 KernelSU 应用并运行以下命令：

```bash
adb shell su -c 'dmesg | grep libfs_avb'
```

如果 AVB 正常工作，应打印出以下消息：

```bash
init: [libfs_avb]Returning avb_handle with status: Success
```

或者，也可以使用 avbroot 的 Android 版本来 验证设备上的分区。

9. 重新启动进入 fastboot 并锁定 bootloader。这将再次触发数据清除。

   fastboot flashing lock

按音量减键，然后按电源键确认。然后重启。

记住：**不要取消勾选 `OEM unlocking`！**

**警告**：如果你正在刷入 CalyxOS，设置向导会[自动关闭 `OEM unlocking` 开关](https://github.com/CalyxOS/platform_packages_apps_SetupWizard/blob/7d2df25cedcbff83ddb608e628f9d97b38259c26/src/org/lineageos/setupwizard/SetupWizardApp.java#L135-L140)。请确保从 Android 的开发者选项中手动重新启用它。考虑使用 [`OEMUnlockOnBoot` 模块](https://github.com/chenxiaolong/OEMUnlockOnBoot) 以自动确保每次启动时 OEM 解锁都处于启用状态。

10. 就这样！要更新操作系统、Magisk 或 KernelSU，请参阅下一节。

更新

对 Android、Magisk 和 KernelSU 的更新方式都相同：通过修补（或重新修补）OTA。

1. 按照使用部分中的步骤生成一个新的已修补 OTA。

2. 如果正在更新 Magisk 或 KernelSU，请先安装它们的新 .apk。如果你碰巧打开了该应用，请确保它没有刷入 boot 镜像。如有必要，取消 boot 镜像更新提示。

3. 重启到恢复模式：adb reboot recovery。如果屏幕卡在 No command 消息上，请在按住电源键的同时按一次音量加键。

4. 使用 adb sideload 侧载已修补的 OTA。

5. 重启你的设备。请注意，在操作系统更新后的首次启动时，设备启动所需时间可能比平时更长（某些情况下可能需要几分钟）。

警告：由于虚拟 A/B 的工作机制，Android 在安装 OTA 并重启后，会在后台静默执行快照合并操作。在快照合并过程中，无法从恢复模式刷入另一个 OTA。请避免执行任何可能导致启动循环的操作（例如安装模块），直到该过程完成，因为除此之外，唯一恢复的方法是再次解锁引导加载程序（并清除数据）。

可以通过运行 adb logcat -v color -s update_engine 来查看状态。或者，如果已安装 Custota（即使未配置指向自定义 OTA 服务器），它会在快照合并操作完成前显示通知。

恢复至官方固件

若要停止使用 avbroot 并恢复至官方固件：

1. 重启至 fastboot 模式并解锁引导加载程序。这将触发数据清除。

2. 擦除自定义 AVB 公钥。

   fastboot erase avb_custom_key

3. 刷入原厂固件。

4. 完成！没有其他残留需要清理。

OTA 更新

avbroot 会用包含自定义 OTA 签名证书的新 zip 替换 system 和 recovery 分区中的 /system/etc/security/otacerts.zip。这可以防止未修补的 OTA 在启动到 Android 时以及从 recovery 侧载时被意外安装。

建议禁用系统更新器应用，以防止其尝试安装未修补的 OTA。操作方法如下：

• 原厂系统：在 Android 的开发者选项中关闭 Automatic system updates。
• 自定义系统：从 设置 -> 应用 -> 查看所有应用 -> (三点菜单) -> 显示系统 -> (找到更新器应用) 中禁用系统更新器应用（或阻止其网络访问）。

这对于某些自定义系统尤为重要，因为它们的系统更新器应用可能会陷入无限循环，不断下载 OTA 更新，并在签名验证失败后重试。

要自建自定义 OTA 服务器，请参阅 Custota。

维修模式

一些设备现在配备了维修模式功能，该功能使用全新的 userdata 镜像启动系统，以便维修技术人员能够在无需用户凭据解锁设备的情况下运行设备上的诊断程序。

当设备已获取 root 权限时，使用维修模式是不安全的。除非你使用的是使用自己密钥签名的 Magisk/KernelSU 发布版本，否则任何人都可以轻易地在维修模式下安装 Magisk/KernelSU 应用，从而无需身份验证即可获得 root 权限。

要安全地使用 Repair Mode：

1. 使用 --rootless 选项（而不是 --magisk 或 --prepatched）重新修补 OTA 以取消设备的 root 权限，并刷入该 OTA。

2. 开启 Repair Mode。

3. 收到修复后的设备后，退出 Repair Mode。

4. 像往常一样刷入（已 root 的）修补后的 OTA。

由于取消 root 和重新 root 都是通过刷入 OTA 完成的，设备的数据不会被清除。

Magisk preinit device

Magisk 25211 及更高版本需要一个可写分区来存储自定义 SELinux 规则，这些规则需要在早期启动阶段访问。这只能在真实设备上确定，因此 avbroot 要求通过 --magisk-preinit-device <name> 显式指定该分区。要查找分区名称：

1. 从原始/未修补的 OTA 中提取 boot 镜像：

   avbroot ota extract \
       --input /path/to/ota.zip \
       --partition <name> # init_boot or boot, depending on device

2. 通过 Magisk 应用修补 boot 镜像。此操作必须在目标设备或同型号设备上执行！如果在不同型号的设备上通过 Magisk 进行修补，分区名称将会不正确。

   Magisk 应用会在输出中打印出类似以下的一行：

   - Pre-init storage partition device ID: <name>
   

或者，可以通过运行以下命令来打印 avbroot 检测到的 Magisk 信息：

```bash
avbroot boot magisk-info \
    --image magisk_patched-*.img
```

分区名称将显示为 PREINITDEVICE=<name>。

既然已知分区名称，在通过 `--magisk-preinit-device <name>` 修补时可将其传递给 avbroot。由于分区名称在 Magisk 更新中不太可能改变，建议将其保存在某处以供日后参考。

如果无法在目标设备上运行 Magisk 应用（例如设备当前无法启动），请使用 --ignore-magisk-warnings 修补并刷入一次 OTA，按照以下步骤操作，然后使用 --magisk-preinit-device <name> 重新修补并重新刷入 OTA。

验证 OTA

要验证与 OTA 安装和 AVB 启动过程相关的所有签名和哈希值，请运行：

avbroot ota verify \
    --input /path/to/ota.zip \
    --cert-ota /path/to/ota.crt \
    --public-key-avb /path/to/avb_pkmd.bin

此命令适用于任何 OTA，无论其是否经过修补。

如果省略 --cert-ota 和 --public-key-avb 选项，则仅检查签名的有效性，而不检查其是否受信任。

Tab completion

由于 avbroot 拥有大量的命令行选项，为 shell 设置 tab 补全可能很有用。这些配置可以从 avbroot 本身生成。

bash

添加到 ~/.bashrc：

eval "$(avbroot completion -s bash)"

zsh

添加到 ~/.zshrc：

eval "$(avbroot completion -s zsh)"

fish

添加到 ~/.config/fish/config.fish：

avbroot completion -s fish | source

PowerShell

将以下内容添加到 PowerShell 的 profile.ps1 启动脚本中：

Invoke-Expression (& avbroot completion -s powershell)

高级用法

使用预修补的 boot 镜像

avbroot 可以使用预修补的镜像替换 boot 镜像，而不是自行应用 root 补丁。这对于使用由 Magisk 应用或 KernelSU 修补的 boot 镜像非常有用。要使用预修补的 Magisk boot 镜像或 KernelSU boot 镜像，请传入 --prepatched <boot image> 而不是 --magisk <apk>。当使用 --prepatched 时，avbroot 将跳过应用 Magisk root 补丁，但仍会应用 OTA 证书补丁。

请注意，avbroot 会验证预修补镜像是否与原始镜像兼容。例如，如果头部字段不匹配或缺少 boot 镜像部分，则修补过程将中止。这些检查并非万无一失，但应有助于防止意外使用错误的 boot 镜像。要绕过部分“安全”检查子集，请使用 --ignore-prepatched-compat。要忽略所有检查（强烈不建议！），请传入两次。

跳过 root 补丁

avbroot 可以通过指定 --rootless 而不是 --magisk/--prepatched 来仅用于重新签名 OTA。使用此选项时，修补后的 OTA 将不会被 root。唯一应用的修改是替换 OTA 验证证书，以便可以使用未来的（已修补的）OTA 升级操作系统。

跳过 OTA 证书补丁

avbroot 可以使用 --skip-system-ota-cert 和 --skip-recovery-ota-cert 选项跳过修改 otacerts.zip。除非有充分理由，否则请勿使用这些选项。

当使用 --skip-system-ota-cert 时，system 分区中的 OTA 证书将不会被修改。这可以防止自定义 OTA 更新程序应用在启动到 Android 后安装进一步的补丁 OTA。

当使用 --skip-recovery-ota-cert 时，vendor_boot 或 recovery 分区中的 OTA 证书将不会被修改。这可以防止从恢复模式侧载进一步的补丁 OTA。

如果因为 OTA 证书已手动添加到启动镜像而使用 --skip-recovery-ota-cert，则建议随后验证补丁 OTA]，以确保操作正确完成。验证过程只能检查启动镜像中的 OTA 证书副本，而无法检查系统镜像中的副本。

跳过所有补丁

要让 avbroot 进行绝对最小的更改：

• 指定 --skip-system-ota-cert
• 指定 --skip-recovery-ota-cert
• 指定 --rootless
• 省略 --dsu

这将使用自定义密钥重新签名 vbmeta 分区和 OTA，但保持所有其他分区不变。

这仅应用于高级故障排除。 如果没有 OTA 证书补丁，生成的 OTA 将无法安装进一步的更新。

替换分区

avbroot 支持替换 OTA 中的整个分区，即使是非启动镜像的分区（例如 vendor_dlkm）。可以通过传入 --replace <partition name> /path/to/partition.img 来替换分区。

此操作唯一改变的是分区的读取位置。使用 --replace 时，分区镜像不再从原始 OTA 的 payload.bin 中读取，而是从指定文件中读取。因此，替换的分区镜像必须具有正确的 vbmeta 页脚，与原始镜像相同。

这不影响应用的补丁。例如，使用 Magisk 时，无论分区来自原始 payload.bin 还是来自 --replace，root 补丁都会应用于 boot 分区。

重新签名分区

avbroot 会自动重新签名 OTA 中它修改的任何分区。然而，其他未修改的分区也可以使用 --re-sign <partition name> 进行重新签名。这在某些情况下很有用，例如当 OTA 包含使用公共 AOSP 测试密钥签名的分区时。

启动已签名的 GSI

Android 的 动态系统更新 (DSU) 功能使用与常规系统不同的信任根。它不使用引导加载程序的 avb_custom_key，而是从 init_boot 或 vendor_boot ramdisk 中的 first_stage_ramdisk/avb/*.avbpubkey 文件获取可信密钥。这些文件采用与 avb_pkmd.bin 相同的二进制格式编码。

avbroot 可以在修补 OTA 时通过传入 --dsu 将自定义 AVB 公钥添加到该目录。这允许启动由自定义 AVB 密钥签名的 通用系统镜像 (GSI)。

清除 vbmeta 标志

某些 Android 构建版本可能附带一个根 vbmeta 镜像，其标志位设置导致 AVB 实际上被禁用。当 avbroot 遇到这些镜像时，修补过程将失败，并显示类似以下信息的消息：

Verified boot is disabled by vbmeta's header flags: 0x3

要通过清除标志位来强制启用 AVB，请传入 --clear-vbmeta-flags。

更改虚拟 A/B CoW 压缩算法

可以通过将 --vabc-algo <algo> 与 gz 或 lz4 一起传入来更改虚拟 A/B CoW 压缩算法。OTA 通常使用与设备上预装的 Android 初始版本兼容的算法。

• 搭载 Android 12 发布的设备支持 gz 和 brotli（avbroot 不支持）
• 搭载 Android 14 发布的设备支持 lz4
• 搭载 Android 15 发布的设备支持 zstd（avbroot 不支持）

选择 lz4 等快速算法，在通过自定义 OTA 更新器应用安装时，可以显著加快 OTA 安装速度。然而，从恢复模式侧载 OTA 时，性能上没有差异。

请注意，当前运行的 Android 版本必须支持指定的压缩算法，否则 OTA 将安装失败。例如，如果当前运行的系统是 Android 13，尝试安装使用 lz4 CoW 压缩的 Android 14 OTA 将会失败。

非交互式使用

avbroot 默认以交互方式提示输入私钥密码。要以非交互方式运行 avbroot，请执行以下任一操作：

• 通过文件提供密码。

  avbroot ota patch \
      --pass-avb-file /path/to/avb.passphrase \
      --pass-ota-file /path/to/ota.passphrase \
      <...>

在类 Unix 系统上，“文件”可以是管道。对于支持进程替换（process substitution）的 shell（bash、zsh 等），可以通过命令查询密码短语（例如，查询密码管理器）。

```bash
avbroot ota patch \
    --pass-avb-file <(command to query AVB passphrase) \
    --pass-ota-file <(command to query OTA passphrase) \
    <...>
```

• 通过环境变量提供密码短语。这种方式安全性较低，因为以相同用户身份运行的任何进程都可以查看环境变量的值。

  export PASSPHRASE_AVB="the AVB passphrase"
  export PASSPHRASE_OTA="the OTA passphrase"
  
  avbroot ota patch \
      --pass-avb-env-var PASSPHRASE_AVB \
      --pass-ota-env-var PASSPHRASE_OTA \
      <...>

• 使用未加密的私钥。强烈不建议这样做。

提取 OTA

要提取 OTA 的 payload.bin 中包含的分区镜像，请运行：

avbroot ota extract \
    --input /path/to/ota.zip \
    --directory extracted

默认情况下，此操作仅提取 avbroot 可能修补的镜像。要提取所有镜像，请使用 --all 选项。要提取特定镜像，请使用 --partition <name> 选项，该选项可以多次指定。

此命令还支持使用 --cert-ota 和 --public-key-avb 选项提取嵌入的 OTA 证书和 AVB 公钥。若要仅提取这些组件，请传入 --none 以跳过提取分区镜像。

列出 OTA 中的分区

要列出 OTA 中的所有分区，请运行：

avbroot ota list --input ota.zip

输出格式为每行一个分区，无格式。

Zip 写入模式

默认情况下，avbroot 在修补过程中对输出 OTA 使用流式写入。这意味着它在文件写入过程中计算用于数字签名的 sha256 摘要。此模式会导致 zip 文件包含数据描述符，这是 zip 标准的一部分，并且在绝大多数设备上都能正常工作。然而，某些设备可能存在损坏的 zip 文件解析器，无法正确读取包含数据描述符的 OTA zip 文件。如果存在这种情况，请在修补时传入 --zip-mode seekable。

可寻址模式写入不包含数据描述符的 zip 文件，但顾名思义，它需要在文件中来回寻址，而不是顺序写入。用于数字签名的 sha256 摘要在 zip 文件完全写入后计算。

使用外部程序进行签名

avbroot 支持通过 --signing-helper 选项将所有签名操作委托给外部程序。使用此选项时，必须为 --key-avb 和 --key-ota 选项提供公钥，而不是私钥。

对于每个签名操作，avbroot 将使用以下参数调用该程序：

<helper> <algorithm> <public key>

该算法是以下之一：

• SHA256_RSA2048
• SHA256_RSA4096
• SHA256_RSA8192
• SHA512_RSA2048
• SHA512_RSA4096
• SHA512_RSA8192
• MLDSA65
• MLDSA87

公钥是传递给 avbroot 的内容。该程序可以使用公钥来查找对应的私钥（例如，在硬件安全模块上）。

对于 RSA 签名，avbroot 会将 PKCS#1 v1.5 填充的摘要写入 stdin，辅助程序预期执行原始 RSA 签名操作，并将原始签名（与密钥大小匹配的八位字节串）写入 stdout。

对于 ML-DSA 签名，avbroot 会将实际要签名的数据提供到 stdin，辅助程序预期将原始 ML-DSA 签名输出到 stdout。

默认情况下，此行为与 AOSP 的 avbtool 中的 --signing_helper 选项兼容。然而，avbroot 还扩展了参数以支持非交互式使用。如果使用 --pass-{avb,ota}-file 或 --pass-{avb,ota}-env-var，则辅助程序将被调用，并带有两个额外的参数，分别指向密码文件或环境变量。

<helper> <algorithm> <public key> file <pass file>
# or
<helper> <algorithm> <public key> env <env file>

请注意，avbroot 会将辅助程序返回的签名与公钥进行验证。这确保了如果使用错误的私钥，修补过程将适当地失败。

16K 页大小开发者选项

在运行 Android 16 及更高版本的较新设备上，Android 的开发者选项中可能有一个选项，用于切换到 16K 页大小内核。在运行经过 avbroot 修补的操作系统时，此功能将无法正常工作。该切换在内部通过刷入增量 OTA 来实现：

• /vendor/boot_otas/boot_ota_16k.zip 用于切换到 16K 页大小内核（要求 boot 分区当前已刷入 4K 内核）
• /vendor/boot_otas/boot_ota_4k.zip 用于切换到 4K 页大小内核（要求 boot 分区当前已刷入 16K 内核）

在运行经过 avbroot 修补的操作系统时，这些 boot_otas 无法刷入，因为它们内部的 payload.bin 是由 OEM 的密钥签名的。这些也不是标准的 OTA 文件。它们不包含任何 OTA 元数据，且 zip 文件本身未签名。它仅仅是一个普通的 zip 文件，其中存储了一个签名的 payload.bin。

目前没有计划添加对这些 boot_otas 的修补支持。这需要支持修改文件系统以及处理增量 OTA，这两者都非常复杂。

那些决心无论如何都要使其工作的人，可以尝试以下手动步骤，使用自己的密钥对这些 boot_otas 进行签名。由于增量 OTA 不会被重新生成，在运行 avbroot ota patch 时，必须保持 boot 分区未修改。

1. 使用 avbroot 和 afsr 解包 vendor.img。

   avbroot avb unpack -i vendor.img
   afsr unpack -i raw.img

2. 从 boot_otas/boot_ota_16k.zip 中提取 payload.bin。

3. 使用你的 OTA 密钥重新签名 payload.bin。

   avbroot payload repack \
       -i payload.bin.orig \
       -o payload.bin \
       -k ota.key \
       --output-properties payload_properties.txt

4. 创建 payload.bin 和 payload_properties.txt 的新 zip 文件。文件必须以未压缩方式存储（例如使用 zip -0）。

5. 对 boot_otas/boot_ota_4k.zip 重复上述步骤。

6. 重新打包 vendor.img 并使用您的 AVB 密钥对其进行签名。

   afsr pack -o raw.img
   avbroot avb pack -o vendor.img -k avb.key --recompute-size

7. 使用以下内容修补（常规）OTA：

   avbroot ota patch \
       --replace vendor <modified vendor> \
       <normal arguments...>

从源码构建

确保已安装 Rust 工具链。然后运行：

cargo build --release

输出二进制文件写入 target/release/avbroot。

调试构建也可以工作，但由于编译器优化被关闭，它们会运行得明显更慢（在 sha256 计算中）。

Android 交叉编译

要为 Android 进行交叉编译，请安装 cargo-android 并使用 cargo android 包装器。要为 aarch64 创建发布构建，请运行：

cargo android build --release --target aarch64-linux-android

如果主机运行 Linux，已安装 qemu-user-static，并且可执行文件是使用 RUSTFLAGS=-C target-feature=+crt-static 和 --features static 构建的，则可以运行测试。

验证数字签名

要验证下载文件的数字签名，请遵循 此处的步骤。

贡献

欢迎贡献！但是，我可能不会接受用于支持行为与 Pixel 设备存在显著差异的设备的更改。

许可证

avbroot 在 GPL-3.0-only 许可下发布。请参阅 LICENSE 获取完整的许可证文本。