📚 课程目录第2章核心概念解析

2. 核心概念解析：令牌、槽位、会话、对象、属性的定义与关系

做 PKCS#11 开发，我遇到的第一个坎儿，就是这几个概念绕来绕去。很多新手把槽位和令牌搞混，把会话当连接，结果调接口的时候死活过不了。今天咱们把这几个东西彻底理清楚。

2.1 从物理到逻辑：四层模型

PKCS#11 的架构其实不复杂。说白了，它把安全硬件抽象成四层：槽位 → 令牌 → 会话 → 对象。每一层都是下一层的容器或上下文。

槽位（Slot）：读卡器接口，可以插入令牌。一个物理设备可能对应多个槽位（比如双插槽读卡器）。
令牌（）：插在槽位里的真实安全硬件，比如 USB Key、HSM 的密钥载体。每个槽位最多插一个令牌。
会话（Session）：应用和令牌之间的逻辑连接。说白了，就是你“握住”令牌的一个句柄。
对象（Object）：令牌里存储的数据单元，比如密钥、证书、数据 blob。每个对象有一堆属性来描述它。

为了让你看得更明白，我画了张图。你盯着看一分钟，这四层的关系就印在脑子里了。

2.2 槽位与令牌：一对欢喜冤家

我个人习惯把槽位比作电源插座，令牌就是插头。插座管供电，插头管干活。但 PKCS#11 里槽位和令牌的绑定关系比插座更灵活——一个槽位可以没有令牌（空槽），也可以拔插更换令牌。

有一次我在项目里调试一个 HSM，明明插了硬件，C_GetSlotList 也能枚举出槽位，但打开令牌时一直报错 CKR__NOT_PRESENT。排查了半天——原来是物理接触不良，令牌没被系统识别。记住：槽位存在 ≠ 令牌可用。你得先调 C_GetTokenInfo 确认状态。

关键函数对照：

操作	函数	返回内容
枚举所有槽位	C_GetSlotList	槽位 ID 数组
获取槽位信息	C_GetSlotInfo	槽位描述、制造商、硬件版本等
获取令牌信息	C_GetTokenInfo	令牌标签、序列号、容量、会话数限制等
初始化令牌	C_InitToken	设置 PIN、擦除令牌上所有对象

你想想看，如果一个槽位对应多个令牌（比如分区的虚拟令牌），那 C_GetSlotList 返回的还是同一个物理槽位 ID。这时候需要用C_GetTokenInfo 里返回的序列号来区分是哪个令牌。

2.3 会话：你的操作手柄

会话（Session）是最容易让人误解的概念。我曾听人问：“一个令牌只能开一个会话吗？”当然不是。实际上你一个应用可以开多个会话，只要不超过令牌的 CK__INFO.ulMaxSessionCount 限制。

会话分成两种：只读会话（R/W Session = CKF_SERIAL_SESSION）和读写会话。只在需要修改令牌状态时（比如生成密钥、写入证书）才用读写会话。如果只是验签、加解密，用只读会话就够了——而且只读会话可以并发开很多个。

📌 我的经验：如果你需要高并发签名，别在单个会话里串行调 C_Sign。开多个只读会话，每个会话一路独立签，吞吐量能翻好几倍。但注意：不同会话不能共享同一个操作上下文（比如正在进行中的签名操作），这是 PKCS#11 规范明确禁止的。

⚠️ 避坑指南：我曾经在产品里忘了调用 C_CloseSession，结果令牌的会话数一直涨，最后超过 ulMaxSessionCount 导致后续的 C_OpenSession 返回 CKR_SESSION_COUNT。解决方案：用 RAII 封装，或者至少保证异常路径能关闭会话。

2.4 对象与属性：令牌里的文件系统

对象（Object）就是令牌上存储的数据单元。PKCS#11 把对象分为几种：

密钥对象（CKO_SECRET_KEY / CKO_PUBLIC_KEY / CKO_PRIVATE_KEY）
证书对象（CKO_CERTIFICATE）
数据对象（CKO_DATA）—— 可以存任意数据，比如随机种子
域参数对象（CKO_DOMAIN_PARAMETERS）—— 用于 DSA 等算法的参数集合

每个对象都由一组属性（Attribute）来描述。属性就是 CK_ATTRIBUTE 结构体：

typedef struct CK_ATTRIBUTE {
    CK_ATTRIBUTE_TYPE type;   // 比如 CKA_CLASS
    CK_VOID_PTR       pValue; // 指向属性值的指针
    CK_ULONG          ulValueLen; // 属性值的长度（字节）
} CK_ATTRIBUTE;

创建对象时，你得构造一个 CK_ATTRIBUTE 数组，这叫模板（Template）。然后调 C_CreateObject 或 C_GenerateKeyPair 把对象写进令牌。

我举一个最简单的例子——生成一个 AES 128 位秘密密钥并存在令牌上：

CK_OBJECT_HANDLE hKey;
CK_ATTRIBUTE template[] = {
    {CKA_CLASS,     &class,     sizeof(class)},
    {CKA_KEY_TYPE,  &keyType,   sizeof(keyType)},
    {CKA_VALUE_LEN, &keyLen,    sizeof(keyLen)},
    {CKA_,     &ckTrue,    sizeof(ckTrue)},
    {CKA_PRIVATE,   &ckTrue,    sizeof(ckTrue)},
    {CKA_ENCRYPT,   &ckTrue,    sizeof(ckTrue)},
    {CKA_DECRYPT,   &ckTrue,    sizeof(ckTrue)},
};
C_GenerateKey(hSession, CKM_AES_KEY_GEN, NULL, template, 7, &hKey);

这里 CKA_ = CK_TRUE 表示密钥存储在令牌上，而不是会话临时对象。如果设成 CK_FALSE，密钥只存在于内存中，会话一关就没了——这叫会话对象。很多人不知道这个区别，导致重启应用后找不到密钥，急得跳脚。

2.5 四个概念的关系总结

咱们用一张表格收个尾，把关系说透：

概念	类比	生命周期	数量关系
槽位 (Slot)	USB 插口	随初始化库存在	1 个物理设备可能有多个槽位
令牌 ()	U 盘	插入槽位后才可用	1 个槽位最多 1 个令牌
会话 (Session)	文件句柄	Open～Close 期间	1 个令牌可开多个会话
对象 (Object)	文件	创建～删除，跨会话持久（令牌对象）	1 个会话可创建/访问多个对象
属性 (Attribute)	文件的属性（大小、权限）	绑定在对象上	每个对象有多个属性

嗯，这一节的内容就这些。核心记住两点：操作顺序是 Slot → → Session → Object；属性是对象的 DNA，用模板来操控。后面讲具体调优的时候，我会反复用到这几个概念。