第3章 PKCS 11 安全基础：认证、加密、签名、哈希函数的 C_ 函数映射
3.1 密码原语在 PKCS 11 中的定位
PKCS 11 把底层密码能力抽象成一组 C_ 开头的接口。
说白了，你调用一个 C_Encrypt，后面可能是硬件加密机、TEE、或者软件库。这种屏蔽细节的设计，让上层应用不用关心密钥到底存在哪。
我个人习惯把这个映射关系画成一张图，心里才踏实。下面这张图就是我常用的 安全原语→C_函数 对照关系图：
3.2 认证机制：C_Login / C_Logout
PKCS 11 把使用者分成两种角色：User（普通用户）和 Security Officer（SO）。认证通过 C_Login 完成。
记得我在集成一款金融 HSM 时，厂商把 SO 的 PIN 设成和 User 一样。结果安全审计没过——SO 权限太大，User 能做的 SO 都能做，那还分啥角色？
标准调用序列：
CK_SESSION_HANDLE hSession;
CK_RV rv;
// 先用 C_OpenSession 打开会话
rv = C_Login(hSession, CKU_USER, (CK_UTF8CHAR_PTR)"123456", 6);
if (rv != CKR_OK) {
// 处理错误，常见 CKR_PIN_INCORRECT / CKR_SESSION_HANDLE_INVALID
}C_Login 必须在会话打开后调用。有些实现允许多次调用，但 C_Logout 会立即清空会话内的私钥句柄。
你想想看，如果忘记 C_Logout，多线程共享 session 时其他线程也能用你的密钥——相当危险。
3.3 加解密：C_EncryptInit → C_Encrypt / C_DecryptInit → C_Decrypt
加解密流程严格遵循 初始化 + 单步/多步操作 的模式。
这里我踩过一个坑：调用 C_EncryptInit 时没检查返回码 CKR_KEY_TYPE_INCONSISTENT，结果后面 C_Encrypt 一直报错。所以千万记得检查每个 C_ 函数的返回值。
| 机制 | CKK_ 密钥类型 | 初始化函数 | 操作函数 |
|---|---|---|---|
| CKM_AES_CBC | CKK_AES | C_EncryptInit | C_Encrypt |
| CKM_AES_GCM | CKK_AES | C_EncryptInit（需额外 GCM 参数） | C_Encrypt |
| CKM_RSA_PKCS | CKK_RSA | C_EncryptInit（公钥加密） | C_Encrypt |
C_EncryptUpdate + C_EncryptFinal，不要一次把所有明文塞进 C_Encrypt。大文件分段处理，能减少内存碎片。
3.4 签名与验签：C_SignInit / C_Sign → C_VerifyInit / C_Verify
签名操作在 PKCS 11 里分两派：直接签名（C_Sign）和 带哈希的签名（C_SignUpdate + C_SignFinal）。
为什么推荐先 Hash 再 Sign？因为 RSA 签名前必须对消息进行 ASN.1 编码的哈希。如果你直接用 C_Sign 传原始消息，很多 会帮你自动 hash，但你可能失去对哈希算法的控制。
我以前在做一个 eID 项目时，发现某些 的 C_Sign 不支持 SHA‑256，只支持 SHA‑1。于是只好手动算 SHA‑256，再用 C_SignUpdate 喂进去。那周的 code review 被怼得不轻……
// 示例：手动哈希后调用 C_Sign (假设密钥已找到)
CK_BYTE data[] = "hello";
CK_BYTE hash[SHA256_DIGEST_LENGTH];
sha256(data, sizeof(data)-1, hash);
rv = C_SignInit(hSession, &mechanism, hPrivateKey);
rv = C_Sign(hSession, hash, SHA256_DIGEST_LENGTH, signature, &sigLen);3.5 哈希计算：C_DigestInit → C_Digest / C_DigestUpdate + C_DigestFinal
哈希相对简单，但有个细节：C_Digest 是一次性接口，而 C_DigestUpdate 支持流式输入。
• 小数据（< 1 MB）用 C_Digest，代码简洁；
• 大文件或流式数据用 C_DigestUpdate + C_DigestFinal，避免内存暴涨。
| 哈希算法 | 机制常量 | 初始化 | 计算 |
|---|---|---|---|
| SHA-1 | CKM_SHA_1 | C_DigestInit | C_Digest / C_DigestUpdate+C_DigestFinal |
| SHA-256 | CKM_SHA256 | C_DigestInit | 同上 |
| SHA-384 | CKM_SHA384 | C_DigestInit | 同上 |
| SHA-512 | CKM_SHA512 | C_DigestInit | 同上 |
3.6 避坑指南（常见失败模式）
- 会话未登录就加密 → C_Encrypt 返回 CKR_USER_NOT_LOGGED_IN。我曾经因为这个被客户一线工程师打电话骂了一个小时……
- 密钥句柄重用前没重新初始化 → 比如你刚用 C_EncryptInit 设置了一个 AES 密钥，接着又用同一个 session 调用 C_SignInit，但忘记重新初始化，签名结果还是加密的上下文——毫无意义。
- GCM 的 IV 参数被吞掉 → 有些 的 C_EncryptInit 需要你设置 CK_GCM_PARAMS，如果传 NULL 则默认全零，极不安全。
最后一句：PKCS 11 的 C_ 函数映射并不复杂，但每个细节都可能影响安全。记住一个原则——每次调用前后都要检查返回值，并确保机制与密钥类型匹配。