📚 课程目录第3章基础概念

3. 基础概念：槽、令牌、会话、用户类型

说实话，槽、令牌、会话、用户类型这四个概念，是PKCS#11里最基础，但也最容易让人迷糊的地方。我最早接触时也绕了不少弯路。今天咱们聊聊我的理解，以及实际开发中这些概念是怎么玩的。

3.1 槽（Slot）——设备插槽

槽的概念很简单，你可以把它想象成电脑主板上的USB口。物理上它是存在的，代表一个可以插入令牌的位置。

我曾在项目里同时管理三个USB密钥，每个密钥对应一个槽。槽通过ID来标识，你可以通过C_GetSlotList()来枚举当前系统上的所有槽。系统启动时，槽一定是存在的，但未必有令牌插入。

槽的核心特点：

槽是逻辑概念，由PKCS#11库管理
每个槽可以绑定0或1个令牌
槽ID通常是固定的，但令牌可以热插拔

// 枚举槽的常见代码片段
CK_SLOT_ID slotList[10];
CK_ULONG slotCount;
CK_RV rv;

rv = C_GetSlotList(CK_TRUE, NULL_PTR, &slotCount);  // 先拿个数
rv = C_GetSlotList(CK_TRUE, slotList, &slotCount);   // 再拿列表

for (CK_ULONG i = 0; i < slotCount; i++) {
    printf("Slot ID: %lu\n", (unsigned long)slotList[i]);
}

我的经验：有时你用C_GetSlotList返回的槽ID并不是连续整数。比如我们有3个槽，ID可能是0、2、5。千万别硬编码假设它们是0、1、2。

3.2 令牌（）——安全世界

如果说槽是门框，令牌就是门里那个安全小世界。

令牌到底是什么？它里面装着密钥、证书、PIN码这些敏感数据。令牌可以是硬件设备（比如USB Key），也可以是软件实现的虚拟令牌。

我以前遇到过一个问题：同一个槽上，令牌拔掉后，再插回来可能就不是同一个令牌了。因为有些令牌有唯一的序列号。你最好通过序列号来判断令牌是否被换过。

属性	说明
`CK__INFO.serialNumber`	令牌唯一序列号，16字节字符串
`CK__INFO.flags`	标识位，比如`CKF__INITIALIZED`表示已初始化
`CK__INFO.ulMaxPinLen/ulMinPinLen`	PIN码长度范围

避坑指南：我曾经遇到一个情况，令牌被拔了但库没通知上层，导致后续操作全部返回CKR_SESSION_HANDLE_INVALID。后来我强制每次操作前都检查C_GetTokenInfo()是否成功，才彻底解决问题。

3.3 会话（Session）——操作通道

会话就是你跟令牌之间的操作通道。你打开会话，才能执行加解密、签名、查找对象这些操作。

会话分两种：

只读会话（R/O）：只能查，不能改
读写会话（R/W）：可以创建、修改、删除对象

// 打开一个只读会话
CK_SESSION_HANDLE hSession;
CK_RV rv = C_OpenSession(
    slotID,               // 目标槽
    CKF_SERIAL_SESSION,   // 必须设为这个
    NULL,                 // 应用回调参数
    NULL,                 // 回调函数
    &hSession             // 输出会话句柄
);

打开会话后，你会拿到一个CK_SESSION_HANDLE。这个句柄就像文件描述符一样，后续操作都需要它。

会话管理要点：

用完一定要C_CloseSession()，不然会泄漏
多线程环境下，大多数库要求每个线程用自己的会话
不要跨线程共享同一个会话句柄

3.4 用户类型——谁在使用令牌

PKCS#11定义了四种用户，但平时常用的就两种：

用户类型	常量	权限	何时用
安全官（SO）	`CKU_SO`	最高权限，管理用户PIN	初始化令牌时用一次
普通用户	`CKU_USER`	使用密钥、执行加解密	日常操作唯一身份

为什么要有SO？你想想看，如果一个设备丢了，只要PIN没泄露就够了？不一定。SO可以设置新的用户PIN，把旧用户锁在外面。SO的存在就是为了让你能管理用户。

我做的第一个PKCS#11项目里，让SO登录后去创建一个密钥对，结果一直失败。后来查文档才发现，SO只能管理用户PIN，不能创建密钥。这个坑，我替你们踩过了。

登录流程：先C_Login(hSession, CKU_USER, pin, pinLen)，用完C_Logout(hSession)。

3.5 从概念到实践的层次关系

把这些概念串起来，大概是这么个结构。我画了一张图，帮你理清它们之间的层次关系。

你看这张图就清楚了。从下到上依次是：槽里面插着令牌，然后你通过会话跟令牌交互，最后必须用某个用户身份登录才能操作。

一句话总结：C_GetSlotList ➜ C_OpenSession ➜ C_Login(CKU_USER) ➜ 干正事 ➜ C_Logout ➜ C_CloseSession。

3.6 实际开发中的“坑”我替你踩了

嗯，这里要说三个最常见的坑：

会话没关就退出了——有些安全库会在进程退出时自动清理，但有些不会。如果你不做C_CloseAllSessions()，下次打开时可能拿到的是上次的脏句柄。我个人习惯在程序退出前加一个清理函数，全部关一遍。
SO和USER登录冲突——我见过有人先用SO登录创建令牌，但退出时忘了登出。结果后面用USER登录时报CKR_USER_ALREADY_LOGGED_IN。实际使用中，SO和USER不能同时登录。要么SO登出，要么用户登出，才可以用另一种身份登。
令牌未初始化——新令牌、或者被重置过的令牌，必须先用C_InitToken初始化，再设SO PIN，最后设用户PIN。流程不能乱。我曾经拿到一个厂家的样品令牌，以为直接拿来就能用，结果C_Login老是返回CKR__NOT_INITIALIZED。查了半天才明白需要先手动初始化一次。

警告：C_InitToken 会清空令牌上所有对象！用之前确保没有重要数据，或者你已经备份了。

好了，这一章的核心就是这些。四个概念：槽是插口，令牌是保险柜，会话是操作手柄，用户是权限身份。记住它们，你在PKCS#11的世界里就不会迷路。