3. Keymaster HAL接口：ICryptographicToken、IKeymasterDevice、HIDL与AIDL变迁、关键方法详解
好，咱们今天聊聊Keymaster HAL层。说实话，这一层是Android安全体系的“硬骨头”。很多做应用层的朋友可能一辈子都碰不到它，但如果你要做系统定制、做TEE集成，或者排查一些诡异的密钥存储问题——嗯，你迟早得回来翻这节课。
我个人习惯把Keymaster HAL看作一座桥。桥的这边是Framework，那边是TEE（可信执行环境）。桥本身长什么样？就是今天要讲的ICryptographicToken、IKeymasterDevice，以及它们背后的HIDL和AIDL变迁。
3.1 从HIDL到AIDL：一次“减肥”运动
先说说背景。Android 8.0引入了Treble，把Framework和HAL彻底解耦。那时候用的接口描述语言是HIDL。HIDL的好处是稳定，坏处是——太啰嗦了。
我记得第一次接触Keymaster HIDL接口时，光看那个 .hal 文件就花了半天。一个方法定义能写十几行，各种回调、状态机、内存管理。说白了，HIDL是为C++设计的，它要处理跨进程通信、要处理binder化的内存共享，所以不得不复杂。
到了Android 12，Google终于动手了。他们把Keymaster从HIDL迁移到了AIDL。为什么？因为AIDL更轻量，而且和Java/Kotlin的亲和力更好。你想想看，现在做系统开发的主力语言已经是Kotlin了，再用HIDL那一套，确实有点格格不入。
核心变化：
- HIDL版本：android.hardware.keymaster@4.0
- AIDL版本：android.hardware.security.keymint
- 接口名从 IKeymasterDevice 变成了 IKeyMintDevice
- 方法签名更简洁，去掉了大量模板代码
但别以为只是改个名。底层的数据结构、错误码、甚至密钥的生命周期管理逻辑都有调整。我在项目中遇到过一个问题：用HIDL接口生成的密钥，在AIDL接口下解析失败。查了半天，发现是密钥blob的header格式变了。所以如果你在做跨版本兼容，一定要留意这个细节。
3.2 ICryptographicToken：密钥的“临时身份证”
ICryptographicToken这个接口，说实话，平时不太起眼。但它解决了一个很实际的问题：如何安全地在不同进程间传递密钥操作上下文？
举个例子。你的App要做一个签名操作。Framework层收到请求后，不能直接把密钥材料发给HAL——那样太危险了。它需要先创建一个“令牌”，这个令牌里包含了操作ID、密钥句柄、以及一些授权数据。然后把这个令牌传给HAL，HAL再根据令牌去TEE里执行真正的操作。
这个令牌就是ICryptographicToken。它本质上是一个轻量级的Binder对象，生命周期很短，用完即焚。
避坑指南：我曾经在调试一个指纹支付问题时，发现每次签名都失败。后来定位到是ICryptographicToken的授权数据里，时间戳字段传错了。TEE那边校验时间戳时发现过期，直接拒绝了操作。所以如果你遇到“操作被拒绝”的错误，先检查一下令牌的授权数据对不对。
3.3 IKeymasterDevice：HAL层的“大管家”
IKeymasterDevice（或者新版的IKeyMintDevice）是Keymaster HAL的核心接口。它定义了所有密钥操作的入口。我把它比作“大管家”——你所有的密钥请求，都得经过它。
来看看几个关键方法：
| 方法名 | 作用 | 个人评价 |
|---|---|---|
| generateKey | 在TEE内生成密钥对 | 最常用的方法，注意参数里的keySize和digest要匹配 |
| importKey | 导入外部密钥到TEE | 安全性要求高，需要验证密钥来源 |
| begin | 开启一个加密/签名操作 | 会返回操作句柄，后续操作都要用它 |
| update | 分段处理数据 | 大文件加密时必用，注意分段大小限制 |
| finish | 完成操作并输出结果 | 别忘了调用，否则TEE资源泄漏 |
| abort | 取消正在进行的操作 | 异常处理时一定要调用，我吃过亏 |
这里我想重点说说begin/update/finish这个三段式设计。为什么不用一个方法搞定？因为TEE的内存是受限的。你想想看，TEE里可能只有几MB的可用内存，如果App要加密一个100MB的文件，一次性传进去，TEE直接OOM了。
所以Google设计了这种流式处理模式：begin告诉TEE“我要开始干活了”，update分批把数据喂进去，finish告诉TEE“活干完了，把结果吐出来”。
注意：我曾经在项目中遇到过一个bug——App在加密过程中崩溃了，没有调用abort。结果TEE里那个操作句柄一直没释放，导致后续所有加密请求都被阻塞。最后只能重启设备。所以，一定要在finally块里调用abort，或者用try-with-resources模式管理操作句柄。
3.4 关键方法详解：generateKey
generateKey是大家最常用的方法。它的参数列表很长，但核心就几个：
// HIDL版本
keymaster_error_t generateKey(
const KeymasterArguments& params,
KeymasterBlob& keyBlob,
KeymasterCharacteristics& characteristics);
// AIDL版本
KeyCreationResult generateKey(
in KeyParameter[] params,
in byte[] attestationKeyBlob);
params里可以指定算法（RSA/EC/AES）、用途（签名/加密）、摘要算法、填充模式等等。这里有个坑：如果你指定了RSA算法，但没指定keySize，有些TEE实现会默认生成2048位的密钥。但有些TEE会直接报错。所以我的建议是——显式指定所有参数，不要依赖默认值。
另外，attestationKeyBlob这个参数是新版才有的。它允许你用另一个密钥来签名新生成的密钥，实现密钥链式认证。这个功能在金融类App里很常用，用来证明密钥确实是在TEE里生成的。
3.5 一张图看懂Keymaster HAL架构
说了这么多，咱们用一张SVG图来梳理一下整体流程：
这张图把三层架构和关键流程都画出来了。你仔细看右侧的流程说明——密钥材料始终在TEE内部，HAL层只传递操作指令和结果。这就是Keymaster安全性的根本保障。
3.6 从HIDL到AIDL的迁移实战
最后聊点实际的。如果你需要把旧代码从HIDL迁移到AIDL，有几个地方要特别注意：
- 接口名变了：IKeymasterDevice → IKeyMintDevice，别写错了
- 错误码变了：HIDL用keymaster_error_t枚举，AIDL用int错误码，映射关系要查文档
- 数据结构变了：KeymasterArguments → KeyParameter[]，数组化之后更简洁
- 回调机制变了：HIDL用callback接口，AIDL用oneway方法，注意线程安全
我记得有一次帮客户做迁移，他们有个老模块还在用HIDL的@4.0接口。迁移到AIDL后，发现密钥生成速度变快了——因为AIDL的序列化开销更小。但同时也发现，有些旧密钥在新接口下无法导入，因为密钥blob的版本号不匹配。解决方案是在HAL层加一个兼容层，检测到旧版本blob时自动转换。
嗯，说到兼容层，这其实是个不错的实践。如果你要同时支持HIDL和AIDL，可以在HAL实现里做一个适配器模式。对外暴露AIDL接口，内部根据密钥blob的版本号，选择不同的处理逻辑。这样既保证了向前兼容，又能享受新接口的性能优势。
小技巧：调试Keymaster HAL时，可以打开logcat的keymaster tag。设置prop：setprop log.tag.keymaster VERBOSE。这样能看到每次操作的详细参数和返回值，对排查问题很有帮助。
好了，这一节的内容就到这儿。Keymaster HAL接口虽然看起来复杂，但核心逻辑其实很清晰：Framework发请求，HAL做调度，TEE干实事。理解了这一点，你就能在遇到问题时快速定位是哪个环节出了岔子。