📚 课程目录第4章密码算法层

第4章：密码算法层：对称/非对称/哈希算法封装

密码算法层，说白了就是整个HSM SDK的“心脏”。

上层应用调用签名、加密，最终都得落到这一层。它不负责业务逻辑，核心任务就一个：把硬件密码模块的能力，包装成上层能调用的统一接口。

我个人习惯把这一层叫做“算法适配器”。它要屏蔽不同硬件厂商的差异，还要保证接口的通用性。我早期参与过一个项目，芯片换了一代，结果上层所有加密代码都得重写。那种痛苦，经历过一次就够了。

核心目标：提供统一的密码算法调用接口，屏蔽硬件差异，保证接口的向前和向后兼容。

4.1 对称算法封装：不只是AES

很多人一提到对称算法，脑子里只有AES。但实际项目中，你还要处理SM4、DES（虽然我强烈建议你别再用了），以及各种模式：ECB、CBC、GCM、CCM。

怎么封装？我建议采用“算法-模式”分离的策略。

算法标识：比如ALG_AES、ALG_SM4、ALG_DES。
模式标识：比如MODE_ECB、MODE_CBC、MODE_GCM。
组合使用：将两者结合，形成完整的算法ID，比如ALG_AES_GCM。

为什么要这么做？你想想看，如果每一个“算法+模式”都是一个独立的函数，那代码量会爆炸。而且，你很难扩展。

举个例子，HAL层可能只提供一个通用的HAL_Cipher_Init()，参数里指定算法和模式。你的SDK封装就该这么做：

typedef struct {
    uint32_t algorithm;  // ALG_AES / ALG_SM4
    uint32_t mode;       // MODE_CBC / MODE_GCM
    uint8_t *key;
    uint32_t key_len;
    uint8_t *iv;
    uint32_t iv_len;
} hsm_cipher_params_t;

hsm_status_t hsm_cipher_encrypt(hsm_cipher_params_t *params,
                                 uint8_t *input,
                                 uint32_t input_len,
                                 uint8_t *output,
                                 uint32_t *output_len);

这种结构，上层只需要填充params结构体，调用的函数永远是一个。维护成本大大降低。

我的经验：GCM模式需要额外处理AAD（附加认证数据）。如果你要封装，记得在params里加上aad和aad_len字段。我曾见过一个SDK，忘了支持AAD，结果用户不得不在上层自己拼包，效率极低。

4.2 非对称算法：密钥对象是核心

非对称算法，如RSA、ECC、SM2，和对称算法的封装思路完全不同。

为什么？因为非对称算法的核心是密钥对。RSA有公钥和私钥，ECC有曲线参数、公钥点、私钥标量。这些数据结构很复杂，你不能简单地把它们当字符串传。

我的做法是，封装一个密钥对象句柄。

密钥导入： 通过hsm_key_import()，将原始密钥材料（PEM/DER格式）导入HSM，获得一个hsm_key_handle_t。
密钥使用： 签名、验签、加密、解密，都基于这个句柄操作。
密钥销毁： 调用hsm_key_destroy()，清除硬件中的密钥。

你可能会问：为什么不直接传密钥数据？

答案很简单：安全。HSM的核心价值就是密钥不出硬件。如果你在应用层还能拿到明文密钥，那还要HSM干嘛？

// 导入一个RSA公钥
hsm_key_handle_t key_handle;
hsm_status_t status = hsm_key_import(&key_handle,
                                     KEY_TYPE_RSA_PUBLIC,
                                     rsa_pub_key_data,
                                     rsa_pub_key_len);

// 使用该密钥进行验签
status = hsm_verify(&key_handle,
                    ALG_SHA256_RSA,
                    message,
                    message_len,
                    signature,
                    signature_len);

这个思路，不仅仅适用于签名验签。ECC的密钥协商（ECDH）也一样，你只需要导入对方公钥和自己的私钥句柄，调用hsm_ecdh_compute()即可。

避坑指南：我以前给某个支付SDK做封装，ECC密钥的曲线参数（如secp256r1）必须在导入时就明确指定。有团队直接丢了公钥点坐标，忘记指定曲线，结果协商时双方用错曲线，握手永远失败。别犯这种低级错误。

4.3 哈希算法：最简单，也最容易忽略细节

哈希算法，如SHA-256、SM3，看起来简单：输入数据，输出摘要。但细节藏在“上下文”里。

很多开发者只提供hsm_hash_compute()一个函数，一次性计算完。这在大多数场景下够用。但如果你要做流式计算（比如大文件分块读取），就得支持Init-Update-Final三段式。

函数	作用	示例
`hsm_hash_init()`	初始化哈希上下文，指定算法	`hsm_hash_init(&ctx, ALG_SHA256)`
`hsm_hash_update()`	输入数据块，可多次调用	`hsm_hash_update(&ctx, chunk, chunk_len)`
`hsm_hash_final()`	完成计算，输出最终摘要	`hsm_hash_final(&ctx, digest, &digest_len)`
`hsm_hash_compute()`	一站式计算（内部封装了上面三步）	`hsm_hash_compute(ALG_SM3, data, len, digest)`

我的建议是：两种形式都提供。对于简单的内存数据，直接调用hsm_hash_compute()；对于大文件或流式数据，用三段式。一个好的SDK，要考虑到用户的使用场景，而不是强迫用户去适配你的接口。

4.4 安全编程规范：血泪史总结

这一节没什么高大上的理论，全是实战中踩过的坑。

内存清零： 在hsm_cipher_params_t、密钥结构体等临时变量使用完后，记得调用memset_s()或SecureZeroMemory()清零。不要用memset()，编译器可能会优化掉。
返回值检查： 每一个HSM接口调用后，必须检查返回值。我曾经见过有人直接忽略返回状态，结果密钥导入失败，后面签名全用了空密钥。
固定缓冲区大小： 输出缓冲区不要用动态分配，尽量用栈上固定大数组或预分配的内存池。比如，RSA 4096位的签名长度是512字节，缓冲区就固定512字节。
不要透露密钥信息： 错误日志里不要打印密钥内容。只打印句柄值或错误码。如果有人把密钥明文写进日志，那就是一场灾难。

一句话：密码算法层的封装，核心不只是“能用”，更是“安全地用”、“方便地用”、“不出错地用”。

4.5 本章知识体系

下面这张图，展示了密码算法层在整个SDK中的位置，以及它内部的核心模块。理解这张图，你就把握了这一章的精髓。

好了，这一章的内容就到这里。算法层的封装，核心就是“统一”和“安全”。把这两点做好，你的SDK就稳了。