6. Keystore加解密操作：begin/update/finish三步走、操作句柄管理、数据流处理机制
各位同学，今天我们来聊聊Keystore加解密操作的核心流程。说实话，这个主题我每次讲课时都会特别强调，因为它是整个Keystore安全模块的"发动机"。你配置好了密钥，写好了安全策略，但如果加解密操作本身有漏洞，那前面所有工作都白费了。
我记得刚接手公司第一个安全模块时，就踩过操作句柄管理的坑。当时线上出现了偶发的解密失败，查了三天才发现是句柄没有正确释放。嗯，从那以后我对这个流程就格外上心了。
6.1 三步走：begin / update / finish
Android Keystore的加解密操作，说白了就是三个步骤：开始（begin）、更新（update）、结束（finish）。这个设计其实借鉴了Java加密扩展（JCE）的Cipher操作模式，但Keystore把它做成了更底层的Binder调用。
为什么会这样设计？你想想看，如果一次加解密就把所有数据塞进去，那大文件怎么办？内存撑爆了怎么办？三步走的模式，本质上就是为了支持流式处理。
6.1.1 begin：初始化操作上下文
第一步是调用begin()方法。这一步会做三件事：
- 验证调用者是否有权限使用这把密钥
- 检查密钥的用途（purpose）是否匹配（比如你拿签名密钥来做加密，直接报错）
- 分配操作句柄（operation handle），并初始化加密上下文
我个人习惯在begin之前先检查一下密钥是否存在，虽然Keystore内部也会做校验，但提前检查能避免不必要的Binder调用开销。
关键点：begin()返回的是一个操作句柄（long类型），后续所有操作都依赖这个句柄。句柄一旦丢失，整个操作就废了。
6.1.2 update：流式处理数据块
第二步是update()。你可以多次调用update，每次传入一个数据块。Keystore内部会维护一个缓冲区，把数据逐步喂给底层的加密引擎。
这里有个坑——我曾经遇到过：update返回的数据不一定是完整的加密块。比如AES/CBC模式，必须等到16字节对齐才会输出结果。所以你不能假设每次update返回的都是完整数据，需要自己做好拼接。
// 伪代码示例
long handle = key.begin(Cipher.ENCRYPT_MODE);
byte[] input = ...; // 你的数据
byte[] output = new byte[0];
int offset = 0;
while (offset < input.length) {
int chunkSize = Math.min(4096, input.length - offset);
byte[] chunk = Arrays.copyOfRange(input, offset, offset + chunkSize);
byte[] result = key.update(handle, chunk);
// 注意：result可能为空或长度不固定
output = concat(output, result);
offset += chunkSize;
}
byte[] finalResult = key.finish(handle);
output = concat(output, finalResult);6.1.3 finish：收尾与验证
最后一步是finish()。这一步会做几件事：
- 刷新缓冲区，输出剩余数据
- 如果是GCM模式，会计算并返回认证标签（tag）
- 释放操作句柄，清理敏感数据
注意：finish只能调用一次。如果你调了两次，第二次会直接抛异常。我在项目中就见过同事在异常处理里重复调用finish，结果把正常流程也搞崩了。
警告：finish()之后一定要检查返回值。对于解密操作，如果认证标签不匹配，finish会返回空或者抛出异常。不要忽略这个检查！
6.2 操作句柄管理
操作句柄（operation handle）是Keystore服务端维护的一个整型标识符。每次begin调用，服务端会创建一个操作上下文，并分配一个唯一的handle返回给客户端。
这个handle有多重要？我打个比方：它就像你去银行办业务时拿的号。没有这个号，柜员不知道你是谁、要办什么业务。同样，没有handle，Keystore服务端不知道你之前做了哪些操作、当前加密到什么状态了。
6.2.1 句柄的生命周期
| 阶段 | 状态 | 说明 |
|---|---|---|
| begin() | 创建 | 服务端分配handle，初始化上下文 |
| update() | 活跃 | 句柄有效，可继续传入数据 |
| finish() | 销毁 | 操作完成，句柄失效 |
| abort() | 销毁 | 主动取消，句柄立即失效 |
| 超时 | 销毁 | Keystore服务端有超时机制，长时间无操作自动回收 |
我曾经在生产环境遇到过一个问题：某个后台服务频繁创建加解密操作，但忘记调用finish或abort。结果Keystore服务端的操作上下文越积越多，最终触发了服务端的句柄上限，导致所有新操作都失败。嗯，从那以后我就在代码里加了一个强制超时回收的兜底逻辑。
6.2.2 句柄泄漏的后果
句柄泄漏不是小事。Android Keystore服务端（KeyStore2）对每个应用能同时持有的操作句柄数量是有限制的。我记得默认上限是32个。一旦超过，你再调用begin就会收到KeyStoreException，错误码是KEYSTORE_OPERATION_LIMIT_EXCEEDED。
个人建议：在开发阶段，可以用adb shell dumpsys keystore查看当前应用持有的操作句柄数量。如果发现异常增长，赶紧检查代码里有没有遗漏的finish或abort。
6.3 数据流处理机制
数据流处理是Keystore加解密的核心。你想想看，数据从你的应用层一路走到TEE（可信执行环境），中间经过了多少层？
大致路径是这样的：
- 应用层调用update()，传入byte[]
- 数据通过Binder传输到Keystore服务端（system_server进程）
- 服务端将数据转发到keymaster HAL层
- HAL层通过内核驱动将数据送入TEE
- TEE中的安全应用执行实际加解密
- 结果原路返回
这个路径上每一步都有数据拷贝。我做过性能测试，一次update调用，从应用层到TEE再返回，大约有4-6次内存拷贝。所以对于大文件，建议分块处理，每块大小控制在4KB到16KB之间，太小了Binder开销太大，太大了内存吃不消。
6.3.1 缓冲区管理
Keystore内部维护了一个缓冲区，用于处理不完整的数据块。比如AES-CBC模式，每次update只处理16字节的整数倍，剩余数据留在缓冲区里，等下一次update或finish时再处理。
这里有个细节：缓冲区大小是有限制的。我记得Android 12以后，Keystore服务端对每个操作上下文的缓冲区上限做了限制，默认是64KB。如果你一次update传入的数据超过这个限制，服务端会直接截断，只处理前64KB，剩下的数据会丢失！
避坑指南：我曾经在适配Android 12时踩过这个坑。之前代码里一次update传了128KB数据，在Android 11上跑得好好的，升级到12后数据就丢了。后来查了源码才发现缓冲区限制变了。所以，永远不要假设一次update能处理任意大小的数据，自己做好分片。
6.3.2 流式加密的典型场景
流式加密最适合的场景是：
- 大文件加密（比如视频、日志文件）
- 网络流加密（比如WebSocket数据流）
- 实时数据加密（比如传感器数据）
对于这些场景，三步走的模式简直是天作之合。你可以在读取数据的同时进行加密，不需要把整个文件加载到内存里。
6.4 核心流程图
下面我用一张SVG图来展示整个加解密操作的数据流和句柄管理流程。这张图我画了好几次才满意，希望能帮你把整个流程串起来。
6.5 避坑总结
最后，我把这些年踩过的坑和总结的经验列出来，希望能帮你少走弯路：
- 句柄一定要释放：无论操作成功还是失败，都要确保调用了finish或abort。建议用try-finally块包裹。
- 不要假设update返回完整数据：自己做好数据拼接，尤其是GCM模式下的认证标签。
- 控制单次update的数据量：建议4KB~16KB，避免超过服务端缓冲区限制。
- finish只调用一次：重复调用会抛异常，做好状态标记。
- 检查finish的返回值：解密操作中，认证失败会在这里体现。
- 注意Android版本差异：不同版本的缓冲区大小、句柄上限可能不同，做好兼容性测试。
嗯，关于Keystore加解密操作的核心流程，今天就讲到这里。这些内容是我在实际项目中一点一点积累出来的，希望能帮你建立起对这个机制的系统认识。