加密SDK架构：模块划分、核心组件与数据流

我刚开始做加密SDK的时候，总觉得架构设计就是画几个方框连几条线。直到第一次被调用方问「你这个初始化到底能不能重入」，我才意识到——架构不是画出来的，是磨出来的。这一章咱们就聊聊加密SDK到底长什么样，哪些组件必须存在，数据在里头怎么流转。

模块划分：按职责切分

一个耐用的加密SDK，通常采用「两横两纵」的分层架构。横向看，从底到顶分三层；纵向看，切两条贯穿线。我习惯这么切：

层级	职责	典型模块
算法层	封装密码学原语	AES、RSA、ECC、Hash、HMAC
协议层	实现安全协议流程	TLS握手、数字签名、密钥协商
接口层	对外暴露语言绑定	C API、Java JNI、Python C扩展
内存管理（贯穿）	敏感数据生命周期控制	安全分配、零化释放、防交换
线程安全（贯穿）	同步与重入保护	锁、原子操作、上下文隔离

核心组件：一个都不能少

每个加密SDK里都有几个绕不开的组件。这不是设计偏好，是刚需。我整理成下面这张对照表，方便你快速把握：

组件	职责	避坑点
上下文对象	保存会话状态、密钥句柄、算法配置	必须设计成不透明句柄，严禁用户直接操作内部指针
会话管理器	创建、复用、销毁会话	我曾经踩过线程池缓存会话导致密钥泄露的坑——记得每次用完后显式清理
策略引擎	校验算法强度、密钥长度、签名曲线	给用户留个覆盖接口，但默认拒绝弱算法
数据通道	负责出入参的序列化/反序列化	只处理字节流，不关心上层协议
日志与审计	记录操作指纹、异常事件	日志里不要打密钥原文！我见过不止一次生产事故

数据流：一次加密调用的完整旅程

咱们拿一个最典型的场景——AES-GCM加密一段数据——来走一遍数据流。你想想看，调一次 aes_encrypt()，背后到底发生了什么？

1. 入口校验：接口层收到字节数组和上下文句柄，检查参数是否合法（空指针、长度越界）。
2. 策略裁决：策略引擎校验当前上下文中的密钥长度是否满足最低安全要求（比如AES-128是否被禁用）。
3. 锁获取：针对该上下文的读写锁加锁。如果是共享上下文，这一步必须小心死锁。
4. 分配临时缓冲：内存管理模块分配一块安全内存，用于存放待加密数据与输出的密文+认证标签。
5. 算法调度：协议层根据上下文里记录的算法编号，路由到对应的AES指令或软件实现。
6. 核心加密：算法层执行GCM模式——先算Counter 0生成初始nonce，然后逐块加密，同时计算GHASH。
7. 结果搬运：将密文和认证标签填入输出缓冲区。原始明文所在的临时缓冲立刻零化并释放。
8. 解锁与返回：释放锁，通过接口层把结果句柄或字节数组返回给调用方。

你看，从入口到出口，走过了接口层 → 策略层 → 内存管理层 → 协议层 → 算法层，再原路返回。每一步都不能跳过。我早期有过一次偷懒——跳过策略裁决，直接调用底层算法——结果上线后才发现用户传了个已经被弃用的RC4密钥进来，整条链路都不安全。

这张图把一次加密调用的完整路径画出来了。你注意两侧的贯穿模块——线程安全和内存管理不是某一层的职责，是从头到尾都要盯住的。

同步与异步：两种数据流模式

接口设计里还有个绕不过去的选择：同步还是异步？我总结一下关键差异：

维度	同步模式	异步模式
调用方体验	函数返回即完成	函数返回一个 future/promise
锁持有时间	短，通常微秒级	长，可能跨越多个时间片
内存管理策略	栈上分配为主	堆上分配，需预分配池
典型适用场景	TLS握手、签名验签	大量小包加解密、长流式处理

关于模块间通信

模块之间怎么通信？我一般只允许三种方式：

• 函数调用：上下层之间通过明确定义的接口函数调用。别用全局变量传数据。
• 回调注册：比如日志模块、异常处理模块。注册一次，由事件触发。
• 共享上下文：上下文对象是整个SDK的「护照」，走到哪带到哪，但内部字段只对协议层和算法层可见。

模块之间不要直接访问对方的内部数据结构。这一点，我希望你从第一天就开始贯彻。我有一次见到同行把一个密钥指针通过全局变量传给算法层——不出所料，上线第三天就出现了密钥被篡改的故障，查起来极其痛苦。