第2章 架构设计原则：模块化、可扩展、安全性
做HSM SDK接入这件事，说实话，我踩过的坑比写过的代码还多。早年有个项目，团队一上来就堆功能，结果半年后连个密钥对都抽不出来——代码耦合得像一团乱麻。后来我强制重构，才把三个核心原则立住：模块化、可扩展、安全性。这三个词看着普通，但真正落地时，每一步都得想清楚。
2.1 模块化：别让所有东西塞进一个文件
我见过最夸张的HSM SDK，单个源文件快两万行。你敢信？要修个RSA签名的小bug，得先读半小时代码才知道从哪里下手。模块化说白了就是：把系统拆成高内聚、低耦合的块。
我的模块拆分层级（以C语言为例）
- 接口层（API）：统一暴露给用户，只负责参数校验和结果封装
- 协议层：处理与HSM设备的通信，比如PKCS#11、KMIP协议头解析
- 安全层：密钥生命周期管理、会话加密、随机数生成
- 硬件抽象层（HAL）：封装对硬件密码卡或TPM的驱动调用
每个模块只负责一件事。接口层绝不碰硬件寄存器，协议层也不该直接生成密钥。我在做某金融项目时，客户要求HSM必须同时支持国密和国际算法。如果没分层，换算法得改半套代码。但因为我们把算法运算单独抽成了crypto_engine模块，替换时只需要实现对应的回调函数。嗯，这就是模块化的威力。
避坑指南：我曾经为了性能优化，把三个模块的函数写在一个源文件里，还用了全局变量传参。结果后来要集成FIPS认证，安全审计员直接卡死——因为没法单独测试每个模块的边界。从那以后我学乖了：模块间的通信必须经过明确的接口，哪怕多写两个头文件。
2.2 可扩展：给未来留条后路
你想想看，HSM的算法标准几年更新一次？ECDSA刚冒头时，很多SDK还只支持RSA。等客户要上SM2的时候，如果你没预留扩展点，就得重新发版、重新认证——周期三个月起。所以可扩展性的核心是：把变化点提前抽象出来。
| 扩展场景 | 我的设计方式 | 举例 |
|---|---|---|
| 新增算法 | 算法注册表 + 工厂模式 | algo_register("SM2", sm2_impl) |
| 新增密钥类型 | 密钥对象多态 | 基类 key_base，派生 rsa_key/ec_key |
| 新增连接方式 | 传输层插件式 | tcp_transport、usb_transport 统一接口 |
| 新增安全策略 | 策略链表 | 用户可配“密钥必须双人授权” |
我个人习惯把扩展点的接口定义得尽量简单，比如下面的算法注册函数：
// 算法引擎注册表
typedef int (*algo_sign_fn)(const uint8_t *input, size_t len,
uint8_t *sig, size_t *siglen, void *ctx);
typedef struct {
const char *name;
algo_sign_fn sign;
algo_verify_fn verify;
// … 其他操作
} algo_entry_t;
int algo_register(const algo_entry_t *entry);这样外部开发者只需要实现一个algo_entry_t实例，调用注册函数，SDK自动接入。我在项目中遇到过客户自己写了个SM9算法插件，三天就集成好了——靠的就是这个扩展点。
注意：可扩展不等于过度设计。我见过有人为每个函数都加回调，结果性能陡降。我的原则是：只对可能变的部分设扩展，不变的部分硬编码也没问题。比如密钥的存储路径，基本不会变，写成宏就足够了。
2.3 安全性：这不是一个Feature，是底线
做HSM的SDK，安全性是地基。你功能再强，如果密钥能被侧信道攻击提取出来，客户分分钟起诉你。安全不是单纯加个加密函数就完事，它必须贯穿整个架构：
- 最小权限：每个模块只开放它能操作的资源。比如协议层不需要知道密钥长什么样，它只能看到密文和句柄。
- 安全启动与完整性校验：SDK加载时，必须校验固件签名，防止被篡改。
- 密钥隔离：关键密钥默认不允许导出，只能由HSM硬件内部使用。
- 审计日志：所有敏感操作（生成密钥、签名、加解密）必须写日志，且日志本身防篡改。
我在做某银行项目时，客户要求SDK在公共WiFi环境下也能安全调用HSM。这就涉及到传输安全。我们在模块化设计中把secure_channel独立出来，对应用层透明：用户调用hsm_sign()，底层自动协商TLS或国密TLCP，用户甚至不用知道。但安全层会把每次握手留证。
安全设计三要素（记住这个三角形）
- 机密性：密钥、会话密钥不在内存留下痕迹（使用完后立即清零）
- 完整性：消息验证码（MAC）或数字签名保证数据没被改过
- 可用性：安全策略不能影响核心业务，比如超时重试要有指数退避
说白了，安全就是冗余检查。我刚开始时觉得“每次签名都加一次HMAC验证太慢了”，结果有次中间人攻击模拟直接改写了我发送给HSM的指令……从那以后我再也不敢省这一步。
2.4 三个原则如何协同
你可能已经注意到了：这三个原则不是孤立的。举个例子，模块化把算法抽成独立模块，而可扩展性又允许你注册新的算法实现。安全层呢？它会在新算法注册时校验其签名和沙箱隔离——这本身就是一个扩展点。我用一句大白话总结：模块化是骨架，可扩展是关节，安全性是免疫系统。
在实际项目中，我建了一个principle_checklist，每次设计评审逐条过：
- 有没有哪个模块的职责超出了它的名字？
- 如果明天要新增一种密钥类型，改动范围会不会超过3个文件？
- 最关键的密钥路径上有没有任何明文拷贝？
小技巧：把这三个原则写进团队的《设计决策记录》模板里。我写过一次“我们决定把算法注册表放在安全层外面，因为……” 半年后新同事看文档就能直接理解，不用再问我了。
好了，这一章就讲这些。记住一个简单的检查方法：看你的SDK目录结构 —— 如果一眼找不出哪是接口、哪是协议、哪是硬件层，那模块化肯定没做好。