使用 Android Keystore 的业务代码怎样规划 VMP

Keystore 保护密钥用途，不替调用方做业务决定

Android Keystore 可以让密钥材料保持不可导出，限制密钥用途，并在可用设备上由硬件安全能力支持。应用通过 KeyStore、KeyGenerator、KeyPairGenerator、Cipher、Signature 或 Mac 等接口请求操作。系统负责密钥句柄和加密运算边界，但不知道某个用户是否购买功能、某个请求是否属于当前会话、某次签名是否应该提交给服务端。

这一区分决定 VMP 重点。直接包装 Keystore API 的方法往往只做参数传递、异常转换和平台版本适配，结构稳定且业务价值有限。真正容易被修改后造成损失的逻辑，通常位于上层：选择哪个别名与用途，是否要求用户认证，哪些字段进入请求摘要，何时允许签名，失败时降级还是拒绝，以及服务端返回什么状态才继续业务。

密钥不可导出也不等于明文不可观察。数据进入 Cipher 或 Signature 前已经在应用进程中可用，解密后的内容还会交给业务函数；被控制的调用方可能请求 Keystore 对不应授权的数据执行操作。工程判断是用 Keystore 约束密钥，用 VMP 增加高价值调用规则的分析与修改成本，再由服务端验证主体、请求、权限和重放状态。

先沿调用图找到承载决策的手写方法

从 Keystore API 向上追踪调用图，可以看到平台包装器、密钥仓库、认证协调器、请求签名器、业务用例和界面入口。若从下往上把整条链全部保护，启动、高频加密和异常路径会迅速扩大。更有效的方法是给每层标记输入、输出、业务损失、执行频率、线程、故障回退和服务端复核，然后选择真正改变允许或拒绝结果的方法。

高价值调用方具有具体信号：它决定可签名字段集合，绑定账号和资源，校验一次性挑战，拒绝过期状态，限制操作类型，或把服务端授权结果转换为本地动作。单纯 loadKey、signBytes、decryptBlob 或 catch 平台异常的方法，默认作为兼容边界。若包装器包含定制策略，则按实际分支而不是类名升级优先级。

保护清单需要连接原始符号与最终产物。R8 mapping、DEX 清单、调用图和 VMP 命中报告必须来自同一 APK。Kotlin 挂起函数、默认参数、lambda 和编译器合成方法可能改变最终入口，不能只复制源码方法名。项目证据应说明业务资产如何映射到最终方法，以及未命中的合成入口是否仍能到达受保护核心。

密钥策略参数与业务规则分别保护

密钥生成时的用途、算法、认证要求和有效条件会限制后续操作。参数构造方法值得审阅，但强度取决于其是否承载产品策略。若代码只是固定采用平台批准配置，它更像安全配置；若根据账号、功能或风险动态选择认证窗口、别名或操作集合，就可能成为敏感决策。VMP 保护的是选择规则，不是把 KeyGenParameterSpec 或密钥对象再次包一层。

别名本身通常不是秘密，却连接密钥生命周期。调用方需要防止测试与正式别名串用、账号切换后复用旧身份、应用数据恢复后指向不存在密钥。别名构造应使用稳定但不泄露敏感数据的标识，服务端不把别名当成用户证明。工程判断是将别名和密钥元数据纳入状态机测试，而不是依赖字符串隐藏。

失败策略比成功路径更关键。用户认证取消、密钥永久失效、设备锁变化、存储清除、算法不可用和平台异常，都可能进入恢复分支。业务代码必须区分需要重新认证、重新注册、回到服务端校验和彻底拒绝的情况。若保护后异常类型或传播路径改变，错误恢复可能被错误地当成成功，因此每类异常都要设备端回归。

请求绑定方法比签名调用本身更值得保护

签名函数可能只有几行：取得密钥、初始化 Signature、传入字节并返回结果。真正决定安全语义的是待签名字节如何生成。若请求摘要遗漏账号、资源、操作、金额、版本或 nonce，攻击者可能在其他上下文复用合法签名。VMP 应优先考虑规范化、字段允许列表、上下文绑定和过期判断方法，同时让服务端使用相同协议重建。

Play Integrity standard requests 提供 requestHash，用于把完整性响应绑定到稳定序列化后的业务请求，并由服务端重算核对。这个事实支持的边界是：客户端先稳定构造业务摘要，服务端收到原始业务字段后独立重算并比较。不能把 requestHash 当成秘密，也不能只在客户端验证后上传一个“可信”布尔值。

稳定序列化必须定义字段顺序、编码、缺省值、大小写、数值和重复字段处理，客户端与服务端共用测试向量。摘要输入不含原始令牌和不必要个人数据，日志只记录摘要和协议版本。工程判断是保护序列化和请求策略可以提高篡改成本，但服务端重算才建立最终绑定；两端协议漂移时应失败而不是退回弱校验。

许可和权益最终由服务端验证

Server-side license verification 描述服务端许可校验需要绑定用户、nonce、签名响应并防止重放。虽然具体流程不等于任意离线授权协议，但边界清楚：客户端可以采集和转发材料，不能独自宣布许可永久有效。服务端验证响应签名、用户与应用关系、nonce、时间和历史状态，再返回短期、限权的业务决定。

Keystore 私钥可以为请求提供安装实例相关签名，但公钥注册、账号绑定、轮换和撤销仍由服务端维护。设备恢复或重装后产生新密钥时，不能自动继承旧账号高权限；服务端要经过合法会话和风险检查更新登记。VMP 可保护注册与调用流程中的本地规则，却不能把未经登记的公钥变成可信身份。

离线需求需要单独威胁模型。某些功能必须在短时离线工作，可以缓存服务端签发、带范围和过期的授权材料，并由 Keystore 保护本地状态或签名；但任何离线决定都存在时钟、回滚和被控制客户端的边界。本文不定义通用离线协议，也不宣称 VMP 能消除该风险。

• 服务端绑定用户、应用、资源和 nonce
• 签名响应在服务端验证而非客户端自证
• 重放状态与业务操作同一事务处理
• 公钥注册和轮换经过合法会话
• 离线授权有明确范围、过期与恢复策略
• 客户端拒绝结果不能被本地布尔值覆盖

用调用图清单定位真正承载业务决策的方法

自动门禁可以读取构建阶段导出的调用图清单。每个方法记录稳定资产标识、最终符号、所属层、直接调用目标、是否含业务决策和预期保护。Keystore API 节点标为 platform，包装层标为 wrapper，授权、请求绑定和风险逻辑标为 business。验证器从每个业务资产沿调用边确认最终到达 Keystore 操作，同时检查包装层没有因为名称命中被整体保护。

下面 Python 示例只读取公开结构 JSON，不解析客户字节码，也不输出真实类名。它要求方法标识唯一、调用目标存在、至少有一个平台节点；从每个 protect-business 方法做有限图遍历，必须能够到达 Keystore 节点；实际保护集合不能包含无例外 wrapper，预期业务方法也不能漏保护。真实流水线还要将清单、mapping 和保护报告绑定同一 APK 摘要。

图可达不等于运行时一定执行，也不证明业务规则正确。反射、JNI、回调和异步状态机可能让静态边缺失，项目需要为这些入口补显式关系或设备证据。工程判断是把无法解释的未知调用标为阻塞，不用模糊包名扩大保护来掩盖清单缺口。

• 调用图和保护报告来自同一候选
• 平台、包装和业务层使用稳定资产标识
• 业务保护目标确实能到达 Keystore
• 无例外包装层不会被整体保护
• 反射与异步入口补显式证据
• 未知调用目标默认阻断

from pathlib import Path
import json
import sys

if len(sys.argv) != 2:
    raise SystemExit("usage: check_keystore_callers.py call-graph.json")

source = Path(sys.argv[1])
if not source.is_file():
    raise SystemExit("call graph file does not exist")

payload = json.loads(source.read_text(encoding="utf-8"))
methods = payload.get("methods")
protected = set(payload.get("protectedMethods", []))
if not isinstance(methods, list) or not methods:
    raise SystemExit("method inventory is required")

by_id = {}
failures = []
for method in methods:
    method_id = method.get("assetId")
    if not method_id or method_id in by_id:
        failures.append(f"invalid or duplicate method: {method_id!r}")
        continue
    by_id[method_id] = method

platform_ids = {key for key, value in by_id.items() if value.get("layer") == "platform-keystore"}
if not platform_ids:
    failures.append("no Keystore platform method is present")

for method_id, method in by_id.items():
    calls = method.get("calls", [])
    unknown = [target for target in calls if target not in by_id]
    if unknown:
        failures.append(f"{method_id}: unknown call targets {unknown!r}")
    decision = method.get("protectionDecision")
    if decision == "protect-business":
        pending = list(calls)
        visited = set()
        reaches_keystore = False
        while pending:
            target = pending.pop()
            if target in visited or target not in by_id:
                continue
            visited.add(target)
            if target in platform_ids:
                reaches_keystore = True
                break
            pending.extend(by_id[target].get("calls", []))
        if not reaches_keystore:
            failures.append(f"{method_id}: business method does not reach Keystore")
        if method_id not in protected:
            failures.append(f"{method_id}: expected business method was not protected")
    if method.get("layer") == "wrapper" and method_id in protected and not method.get("exceptionReason"):
        failures.append(f"{method_id}: wrapper protected without an exception")

if failures:
    print("Keystore caller boundary gate failed:")
    for failure in failures:
        print(f"- {failure}")
    raise SystemExit(2)

print(f"validated {len(by_id)} method records")

设备回归覆盖密钥状态和受保护异常路径

Android instrumented tests 适合验证依赖真实 Android 运行时、组件、锁屏和系统 API 的行为。Keystore 测试不能只在 JVM 模拟里断言接口返回值，应在目标设备覆盖首次生成、已有密钥读取、用户认证成功与取消、应用重启、系统升级、密钥失效、数据清除、并发调用和异常恢复。

VMP 可能改变调用方的执行时延、异常栈和线程行为。高频签名、启动时解密和主线程认证协调需要先建立未保护基线，再用同一设备和候选比较。项目应分别记录 Keystore 操作耗时、上层序列化、服务端往返和业务完成时间，不能把网络与硬件差异全部归因于保护。

硬件保护能力和系统行为随设备而异，单一设备通过不能代表完整 API、ABI 和厂商矩阵。回归报告明确哪些设备支持何种安全级别、哪些异常实际触发、哪些组合未执行。没有真实设备证据时，只能说明方法和边界，不能写成 Keystore 与 VMP 组合已经兼容所有设备。

发布证据连接调用规则、服务端验证和同一候选

NIST SP 800-218 SSDF 将来源、构建、验证、变更和供应链风险纳入安全开发实践。Keystore 调用方的证据包应包含 APK 摘要、变体、密钥策略清单、调用图、R8 mapping、VMP 配置、实际命中报告、请求绑定协议版本、服务端校验规则和设备回归。秘密、私钥和完整用户数据不能进入证据包。

变更需要按边界触发复审。密钥参数、别名状态机、请求字段、nonce、服务端授权、完整性信号、保护范围或目标系统变化，都可能使旧结论失效。流水线比较清单和协议摘要，要求负责人解释扩大或降级。没有服务端回执、设备数据或同候选报告时，结论标为未接入或待验证。

最终结论应限定为指定候选中列出的业务调用方法进入保护，Keystore 包装层按策略处理，请求绑定和服务端验证在列出的场景完成；不能声称密钥绝对不可获取或客户端成为可信执行环境。准备评估时，可通过御盾中央平台提交代表性 APK、Keystore 调用图、密钥策略、请求协议和保护范围，先固定候选身份与验收边界。

• 调用图、mapping 和保护报告绑定同一 APK
• 密钥策略和请求协议都有版本摘要
• 服务端验证规则与客户端字段一一对应
• 设备回归覆盖真实失效与拒绝路径
• 证据包不包含私钥和用户敏感明文
• 结论区分 Keystore、VMP 与服务端责任