spblob-rescue

spblob-rescue 是一个离线救援工具，用于处理 Android 已能进入桌面、但凭据加密区（CE）未解锁，导致所有应用持续提示“重启后需等待应用响应”的特定故障。

工具支持通过电脑调用，也可以直接在 TWRP、OrangeFox 等 Recovery 的终端中运行。所有修改均在 Android 系统未启动时完成，原始 handle 会在写入前自动备份。默认只处理主用户 0，其他用户必须显式指定。

Warning

本工具不负责破解锁屏、恢复遗失密码、重建 KeyMint 密钥或修复文件系统。请先执行 info 确认设备存在可切换的备用 protector；如果主、备用 protector 均已失效，只能恢复备份或格式化 Data。

适用范围

适用于同时满足以下条件的设备：

• 系统能够启动并进入桌面；
• 大多数或全部应用持续提示需要等待响应；
• 锁屏未正常出现，或系统始终无法完成 CE 解锁；
• /data/system_de/<uid>/spblob/ 中存在 handle 和多个 .pwd protector；
• 故障发生前使用的 PIN、图案或密码仍然已知。

不适用于以下情况：

• 锁屏界面明确提示密码错误；
• Data 分区损坏、无法挂载或已经被格式化；
• 设备不使用上述 Synthetic Password 目录结构；
• spblob 目录中只有一个 protector，或所有 protector 均已失效；
• 系统无法启动是由槽位、启动镜像、AVB 或动态分区故障引起。

工作原理

Android 的锁屏凭据通过 Synthetic Password（SP）保护凭据加密区。部分设备会同时保留硬件保护和软件回退两条 protector，例如 weaver 与 secdis。

如果 Recovery 在不匹配的 KeyMint 环境中触发密钥 blob 升级，却没有将升级结果可靠写回，当前 protector 可能被永久作废。此时备用 protector 仍可能有效。

本工具不会修改密钥内容，也不会尝试升级密钥。它只会：

1. 读取当前 handle；
2. 查找同一用户 spblob 目录中的备用 .pwd protector；
3. 备份原始 handle；
4. 在用户确认后，将 handle 切换到指定的备用 protector。

重启系统后，再使用原来的 PIN、图案或密码解锁一次。如果备用 protector 有效，CE 数据和应用应恢复正常。

使用条件

• 已进入具有 root shell 的 TWRP、OrangeFox 或其他兼容 Recovery；
• Data 分区能够正常挂载；
• 电脑端使用时已安装 ADB；
• 建议先备份重要数据，以及 /data/system_de/<uid>/spblob/ 目录。

电脑端使用

Windows

进入 Recovery 并连接 USB 后，双击：

rescue.cmd

Linux / macOS

chmod +x rescue.sh
./rescue.sh

脚本会先显示当前 protector 和可用候选项。确认目标无误后，按提示输入 YES 执行切换。

手机端直接执行

将 spblob-rescue.sh 保存到内部存储、SD 卡或 U 盘，在 Recovery 的终端中运行。

先检查，不修改任何文件：

sh /sdcard/Download/spblob-rescue.sh info

确认存在备用 protector 后执行切换：

sh /sdcard/Download/spblob-rescue.sh switch

如果内部存储不可读，可以从 U 盘运行：

sh /usb_otg/spblob-rescue.sh info
sh /usb_otg/spblob-rescue.sh switch

不同 Recovery 的 U 盘路径可能是 /usb_otg、/usb-otg、/usbotg 或其下一级目录。

操作模式

模式	作用	是否修改数据
info	显示用户、当前 handle、候选 protector 和备份状态	否
switch	备份当前 handle，并切换到备用 protector	是
restore	使用 handle.rescue.bak 恢复切换前的 handle	是

存在多个候选 protector 时，可以明确指定目标。既可以填写裸 handle，也可以填写对应的 .pwd 文件名：

TARGET_HANDLE=0123456789abcdef sh /path/spblob-rescue.sh switch
TARGET_HANDLE=0123456789abcdef.pwd sh /path/spblob-rescue.sh switch

自动化环境可以设置 RESCUE_YES=1 跳过交互确认，但只应在已核对目标 protector 后使用。

用户范围

默认只查询或修改 Android 用户 0：

sh /path/spblob-rescue.sh info

指定其他用户：

USER_ID=10 sh /path/spblob-rescue.sh info
USER_ID=10 TARGET_HANDLE=0123456789abcdef sh /path/spblob-rescue.sh switch

只有明确需要处理全部 Android 用户时才使用 all：

USER_ID=all sh /path/spblob-rescue.sh info
USER_ID=all TARGET_HANDLE=0123456789abcdef sh /path/spblob-rescue.sh switch

全部用户切换会在第一次写入前检查每个存在备用 protector 的用户。任何可切换用户不包含指定目标时，操作会在尚未修改文件时停止。未指定目标且某个用户存在多个候选时也会停止，要求先执行 info 后明确选择。没有可读 handle 或没有备用 protector 的用户会保持不变。

USER_ID 只接受非负整数或 all。TARGET_HANDLE 只接受 16 位十六进制，可选 .pwd 后缀。

回退

原始 handle 默认备份为：

/data/system_de/<uid>/spblob/handle.rescue.bak

电脑端回退：

./rescue.sh restore

手机端回退：

sh /path/spblob-rescue.sh restore

Recovery 环境识别

脚本会综合检查以下信息，而不是仅依赖单个 Android 属性：

• TWRP 与 OrangeFox 属性；
• ro.bootmode、内核命令行和启动参数；
• Recovery 进程、日志和 fstab；
• Data 的实际挂载状态。

Data 尚未挂载时，脚本会优先调用 Recovery 自带的挂载命令。脚本会拒绝在已经正常启动的 Android 系统中修改 handle。

极少数精简 Recovery 不提供任何可识别标志。确认 Android 系统没有运行后，可显式允许离线执行：

RESCUE_RECOVERY=1 sh /path/spblob-rescue.sh info
RESCUE_RECOVERY=1 sh /path/spblob-rescue.sh switch

不要在 Android 桌面、ADB root 系统或系统终端中使用 RESCUE_RECOVERY=1。

故障排查

无法确认 Recovery 环境

确认设备确实位于 Recovery，并检查 getprop ro.bootmode、getprop ro.twrp.version。只有在确认 Android 未运行时，才使用 RESCUE_RECOVERY=1。

找不到 /data/system_de

先在 Recovery 中挂载 Data。若仍不存在，设备可能尚未解密、目录结构不同，或不属于本工具支持的故障类型。

没有发现备用 protector

不要执行 switch。只有一个 protector 时，本工具没有可安全尝试的回退目标。

切换后仍无法恢复

可以使用 restore 恢复原 handle，或指定其他候选 protector 再试。若所有候选项均无效，需要恢复完整备份或格式化 Data。

系统提示密码错误

这通常不是 handle 指向失效 protector 的同类故障，本工具无法恢复未知或错误的锁屏凭据。

仓库文件

文件	用途
spblob-rescue.sh	设备端核心脚本，也可直接在 Recovery 终端运行
rescue.sh	Linux/macOS 电脑端入口
rescue.cmd	Windows 电脑端入口
tests/spblob-rescue-test.sh	使用临时目录验证查询、切换和回退流程

测试

在 Git Bash、Linux 或 macOS 中运行：

sh tests/spblob-rescue-test.sh

测试只使用临时模拟数据，不会访问真实设备分区。覆盖默认用户隔离、handle 校验、.pwd 归一化、全部用户预检、切换和回退。

给 Recovery 开发者

• 无法读取已安装系统的真实版本和安全补丁级别时，应停止解密，不要使用 Recovery 自身属性替代；
• keystore2 使用临时数据库时，必须保证升级后的 key blob 能可靠写回；
• 不要在失败重试过程中反复切换 KeyMint 环境；
• 解密链应在可验证的设备环境中完整启动，失败时保留足够日志。

English summary

spblob-rescue is an offline recovery utility for one specific Android FBE failure: the system boots, but credential-encrypted storage remains locked because the active Synthetic Password protector is no longer usable. On compatible devices with a surviving sibling protector, the tool backs up and repoints /data/system_de/<uid>/spblob/handle, then lets the original PIN, pattern, or password unlock CE after reboot. It does not bypass credentials, regenerate keys, or repair damaged filesystems.

License

MIT