OhMyKeymint Keybox使用指南:结构解析、校验规则与RSA/EC导入教程

原创2026-11-09 09:44:301,677 阅读

OhMyKeymint Keybox使用指南:结构解析、校验规则与RSA/EC导入教程

OhMyKeymint 是面向 Android 的自定义 Keystore / KeyMint 模块,而 Keybox(keybox.xml)是它实现认证证书签名的核心数据文件。本教程带你快速搞懂 OhMyKeymint Keybox 的 XML 结构、导入前的校验规则,以及如何通过 WebUI 一键导入 RSA / EC 双算法 Keybox。

一、什么是 Keybox?为什么需要它

在 Android 的 Keystore 体系中,应用做"密钥认证"(Key Attestation)时,需要一组成对的私钥 + 证书链来为证书签名。OhMyKeymint 把这组数据统称为 Keybox,存放位置固定为:

/data/misc/keystore/omk/keybox.xml

模块首次启动时,如果该文件不存在,会自动用仓库内置的模板 template/keybox.xml 填充一份默认值;解析与校验逻辑集中在 src/keybox.rs。

💡 简单理解:Keybox 就是 OhMyKeymint 的"签名身份"。换一份 Keybox,等于换一套认证身份。

二、keybox.xml 结构解析

一个合法的 keybox.xml 由 4 层结构组成,以下方框图概括:

  • <AndroidAttestation>:根节点
    • <NumberOfKeyboxes>:Keybox 数量,OhMyKeymint 只接受 1
      • <Keybox DeviceID="sw">:容器节点
        • <Key algorithm="ecdsa" | "rsa">:密钥条目,可出现 0~2 个,但至少要有一个
          • <PrivateKey format="pem">:PEM 编码私钥
          • <CertificateChain>:证书链
            • <NumberOfCertificates>:声明证书数量
            • <Certificate format="pem"> × N:PEM 证书,从叶子证书到根证书排列

对照模板 template/keybox.xml 可以看到一份同时包含 EC 与 RSA 两条目的完整示例:EC 条目使用 EC PRIVATE KEY(SEC1 格式),RSA 条目使用 RSA PRIVATE KEY(PKCS#1 格式),各自的证书链都是"叶子 → 中间/根"的两级结构。

📌 三种受支持的组合(见 docs/CONFIGURATION.md):

组合 说明
RSA + EC 双条目 最完整,各自签名对应算法的认证叶子
仅 EC 条目 RSA 主题的认证证书也由该 EC 私钥和证书链签名
仅 RSA 条目 同理,EC 主题也回落到 RSA 签名

三、导入前的校验规则(重点)

导入不是"拷贝文件"那么简单。WebUI 背后由原生 keymint 辅助程序执行完整校验,任何一步失败,当前生效的 Keybox 都保持原样。规则清单如下:

  1. 大小限制:文件不得超过 64 KiB(常量 MAX_KEYBOX_XML_BYTES,见 src/keybox.rs),超大的文件在解析前就被拒绝。
  2. 编码要求:必须是合法 UTF-8 文本。
  3. 算法白名单:<Key algorithm> 只接受 ecdsa / ec / rsa,其它算法直接报错。
  4. 条目完整性:<PrivateKey> 块、<NumberOfCertificates>、PEM 证书块缺一不可;声明的证书数量必须与实际解析出的数量一致,否则报 certificate count mismatch。
  5. 私钥与证书链必须匹配:系统会从私钥推导公钥(SubjectPublicKeyInfo),与叶子证书中的公钥逐字节比对(见 src/keybox.rs 的 validate_chain_matches_key)。这是最常见的失败原因——私钥和证书链来自不同密钥对。
  6. 私钥编码格式:
    • RSA:未加密的 PKCS#1 或 PKCS#8 PEM(内部统一归一为 PKCS#1)
    • EC:未加密的 SEC1 或 PKCS#8 PEM(内部统一归一为 SEC1),仅增加/去掉 PKCS#8 包装不会改变 Keybox 身份
    • 不支持加密私钥

校验入口在 src/keybox.rs 的 validate_keybox_xml,导入流程为:读文件 → 查大小 → 解 UTF-8 → 全量 KeyBox 校验 → 原子替换正式文件。

四、通过 WebUI 导入 RSA/EC Keybox 的完整步骤

前置条件:已安装 OhMyKeymint 模块(KernelSU / Magisk + Android 12+),并打开其内置 WebUI。

第 1 步:准备 Keybox 文件 把 keybox.xml 文件放到手机存储中。文件必须以 .xml 结尾(即使某些文件管理器把它显示为 text/plain 也能选到)。

第 2 步:打开更换入口 在 WebUI 首页找到 Keybox 卡片,点击 Change Keybox(更换 Keybox)。系统会弹出 Android 系统文档选择器,可以使用任意已安装的存储提供者(如 MT 管理器);若选择器不可用,WebUI 会自动回退到内置共享存储浏览器(相关交互代码见 webui/src/file_selector/file_selector.ts)。

第 3 步:选择文件并确认 选中文件后,前端先做扩展名与 64 KiB 大小检查,再调用原生命令 keymint --webui-install-keybox 完成校验与安装(见 webui/src/cli.ts)。

第 4 步:查看结果 成功后 WebUI 的 Keybox 卡片会立即刷新。无需重启设备——Keybox 文件监视器会自动热加载新身份(监视逻辑见 src/keybox.rs 的 initialize)。若失败,检查 keymint.log 日志定位原因。

五、导入之后:身份切换与自动清理

OhMyKeymint 用一段 SHA-256 摘要作为 Keybox 身份(identity digest),由 RSA/EC 两条目的私钥与证书链按标签拼接后计算得出(见 src/keybox.rs 的 compute_identity_digest)。

身份发生变化时,系统默认执行一次清理:

  • 普通应用签名密钥(含 passkey 凭据)全部保留;
  • 仅与旧 Keybox 身份绑定的专用 ATTEST_KEY 条目被退役(retire)。

该行为由配置项 retire_stale_keybox_bound_keys(默认 true)控制,详细说明见 docs/CONFIGURATION.md。

六、读懂 WebUI 的 Keybox 状态卡片

导入完成后,首页 Keybox 卡片会解析已安装文件并展示三项关键信息:

状态 含义 判定方式
来源 google_hardware / google_remote / unknown 逐张验签整条链,并比对 Google 固定根公钥(SPKI),再结合出厂序列号、RKP 扩展等标记区分硬件/远程
安全级别 TEE / StrongBox 读取叶子证书 Subject 中的 O=TEE 或 O=StrongBox,老式出厂 Keybox 回退到 X.520 T= 属性
吊销状态 Not revoked / Revoked 用全部证书序列号查询 Google 官方吊销状态列表,本地缓存 12 小时

⚠️ 注意:多算法链必须解析出相同的已知来源,否则整体显示 unknown;"Not revoked" 只表示当前列表未命中,不等于能通过 Play Integrity 检测。

七、常见问题与最佳实践

Q1:必须更换内置 Keybox 吗? 不强制。模块自带一份可用模板,但它属于"捆绑状态",来源会显示为 unknown。需要真实身份时再导入自己的 Keybox。

Q2:从哪里获取 Keybox?

  • 自己从 Pixel 等设备提取;
  • 或使用 WebUI 的 本地 RKP Keybox 签发功能(软件 P-256 密钥 + 本机 RKP 证据向 Google 请求证书链,产物保存在 /data/misc/keystore/omk/data/rkp-artifacts/<id>/keybox.xml,流程见 docs/CONFIGURATION.md)。RKP 提取的 Keybox 天然只含 EC 条目,属正常现象。

Q3:导入失败,当前 Keybox 会损坏吗? 不会。任何读取、大小、UTF-8、校验或写盘失败,正式文件都保持原样;只有全部检查通过才原子替换。

Q4:换 Keybox 后应用需要重新登录吗? 绑定了旧身份的专用认证密钥会被退役,部分依赖旧身份的应用可能需要重新验证。

🔐 安全守则(摘自 docs/FAQ.md):

  • 绝不从未受信来源下载含私钥的 Keybox;
  • 绝不公开分享你在用的 keybox.xml——它包含私钥;
  • 配置与密钥位于 /data/misc/keystore/omk/,权限为 0600,请勿泄露。

八、参考文件速查

掌握"结构 → 校验 → 导入 → 状态"这条主线,你就能安全、高效地管理 OhMyKeymint 的 Keybox 了。

登录后查看全文
OhMyKeymint