OhMyKeymint Keybox使用指南:结构解析、校验规则与RSA/EC导入教程
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 都保持原样。规则清单如下:
- 大小限制:文件不得超过 64 KiB(常量
MAX_KEYBOX_XML_BYTES,见 src/keybox.rs),超大的文件在解析前就被拒绝。 - 编码要求:必须是合法 UTF-8 文本。
- 算法白名单:
<Key algorithm>只接受ecdsa/ec/rsa,其它算法直接报错。 - 条目完整性:
<PrivateKey>块、<NumberOfCertificates>、PEM 证书块缺一不可;声明的证书数量必须与实际解析出的数量一致,否则报certificate count mismatch。 - 私钥与证书链必须匹配:系统会从私钥推导公钥(SubjectPublicKeyInfo),与叶子证书中的公钥逐字节比对(见 src/keybox.rs 的
validate_chain_matches_key)。这是最常见的失败原因——私钥和证书链来自不同密钥对。 - 私钥编码格式:
- 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,请勿泄露。
八、参考文件速查
- 模板示例:template/keybox.xml
- 解析与校验核心:src/keybox.rs
- WebUI 命令封装:webui/src/cli.ts
- 完整配置与生效说明:docs/CONFIGURATION.md
- 常见问题:docs/FAQ.md
- 功能概览:README.md
掌握"结构 → 校验 → 导入 → 状态"这条主线,你就能安全、高效地管理 OhMyKeymint 的 Keybox 了。