第4章 槽位与令牌枚举：C_GetSlotList与C_GetTokenInfo

好，咱们继续往前走。上一章我们聊了怎么加载、初始化一个PKCS#11库，算是把“大门”给打开了。但门开了之后呢？你总得看看里面有几个“插槽”（Slot），每个插槽上插了什么“令牌”（）吧？这就引出了我们这章的核心内容——枚举槽位，以及获取令牌的详细信息。

说白了，槽位就是物理或逻辑上的读卡器接口，而令牌就是插在里面的那个硬件设备（比如U盾、智能卡）。你得先知道有几个槽位，每个槽位的令牌是什么型号、序列号多少，才能决定接下来操作哪个设备。

4.1 为什么需要枚举槽位？

你可能觉得，我的机器上就插了一个U盾，直接操作不就行了？嗯，我在刚开始做项目时也这么想，结果被现实狠狠打脸。有一次，客户现场有个HSM（硬件安全模块）插在服务器上，同时还有个测试用的软令牌模拟器也在运行。如果不枚举，你根本不知道C_Initialize之后，该跟哪个屁股对话。

你想想看，C_GetSlotList的作用就是帮你拿到所有可用槽位的ID列表。拿到这个列表，你才能逐个去查每个槽位上的令牌信息。这个过程就像：

1. 问系统：“嘿，你有几个插口？”
2. 拿着插口列表：“哦，有3个，分别是Slot 0， Slot 1, Slot 2。”
3. 逐个问：“插口1上面的令牌长什么样？叫什么名字？序列号多少？”

没有枚举这一步，你就是两眼一抹黑。所以，不要偷懒，每次都老老实实枚举一遍。我个人习惯在程序启动后的初始化流程里，固定调用一次C_GetSlotList，然后把结果缓存起来。为什么？因为中途拔插设备，槽位列表可能会变，但你得有个基准快照。

4.2 C_GetSlotList 详解

先看它的函数原型。这东西不长，但参数里有小陷阱：

// PKCS#11 v2.40 标准定义
CK_RV C_GetSlotList(
  CK_BBOOL       tokenPresent,   // 是否只返回插了令牌的槽位？
  CK_SLOT_ID_PTR pSlotList,      // 接收槽位ID列表的缓冲区
  CK_ULONG_PTR   pulCount        // 输入时是缓冲区大小，输出时是实际槽位数量
);

这里有个经典套路，我称之为“两趟法”：

• 第一趟：把pSlotList设为NULL，先调用一次，获取实际需要的槽位数。
• 第二趟：根据返回的数量动态分配内存，再调用一次，把数据填进去。

为什么要这么折腾？因为PKCS#11的设计者很“贴心”，为了避免你分配的内存不够用，让你先问问到底需要多大屋子。我见过有人图省事，直接分配一个固定大小的数组，比如CK_SLOT_ID slotList[50]。平时没问题，但万一系统槽位数超过50，你的程序就崩了。嗯，这种事我在一个金融项目中亲眼目睹过，当时那个HSM一下子注册了60多个逻辑槽位，写得死死的程序当场崩溃。从那以后，我再也不敢假设槽位数量了。

下面是一个完整的调用示例，我平时都这么写：

CK_SLOT_ID_PTR slotList = NULL_PTR;
CK_ULONG slotCount = 0;

// 第一趟：获取数量
CK_RV rv = C_GetSlotList(CK_TRUE, NULL_PTR, &slotCount);
if (rv != CKR_OK) {
    // 处理错误……
    return;
}

// 分配内存
slotList = (CK_SLOT_ID_PTR)malloc(sizeof(CK_SLOT_ID) * slotCount);
if (slotList == NULL) {
    // 内存不足……
    return;
}

// 第二趟：获取真实数据
rv = C_GetSlotList(CK_TRUE, slotList, &slotCount);
if (rv != CKR_OK) {
    free(slotList);
    // 处理错误……
    return;
}

// 现在就可以用slotList[0] 到 slotList[slotCount-1]了
for (CK_ULONG i = 0; i < slotCount; i++) {
    printf("Slot %lu 的ID为: %lu\n", i, slotList[i]);
}

// 记得释放内存
free(slotList);

你看，tokenPresent参数我传的是CK_TRUE。为什么？因为一般情况下我们只关心插了令牌的槽位。如果你传CK_FALSE，会把那些空着的槽位也列出来。但空槽位除了让你多循环一次之外，并没有卵用，因为真正的操作（比如登录、签名）都需要令牌在位。所以我建议你一律传CK_TRUE，除非你有特殊的诊断需求。

4.3 C_GetTokenInfo 详解

拿到Slot ID后，下一步就是调用C_GetTokenInfo来问这个槽位上的令牌到底是个什么货色。函数原型如下：

CK_RV C_GetTokenInfo(
  CK_SLOT_ID    slotID,       // 你刚拿到的槽位ID
  CK__INFO_PTR pInfo     // 输出参数，令牌信息结构体
);

CK__INFO是一个非常大的结构体，里面包含了令牌的标签（label）、制造商ID、型号、序列号、可用空间、是否受保护等等。我最关心的通常是这些字段：

字段名	类型	说明	我的使用场景
label	CK_UTF8CHAR[32]	用户定义的令牌标签	用来区分不同令牌（比如“办公U盾”、“个人测试卡”）
manufacturerID	CK_UTF8CHAR[32]	厂商名称	用来判断是不是指定厂商的HSM
serialNumber	CK_CHAR[16]	序列号，通常是字符串	唯一标识一个物理设备，用于日志审计
ulSessionCount	CK_ULONG	当前打开的会话数	判断令牌是否已被其他应用占用
ulTotalPublicMemory	CK_ULONG	令牌总公共内存（单位：字节）	判断令牌容量是否足够存放新证书
flags	CK_FLAGS	令牌能力标志位	比如是否支持CKF__INITIALIZED来检查令牌是否已初始化

注意，这些字符串字段是固定长度的，并不保证以\0结尾。所以你在打印或者比较时，必须用strncpy或者指定长度，不能直接用strcpy。我曾经因为这个踩过坑，打印出来的label后面跟着一堆乱码字符，害我排查了半天才知道是字符串终止符的问题。

4.3.1 综合枚举示例

我把C_GetSlotList和C_GetTokenInfo串起来，写一个完整的枚举函数。以后你拿来就能用：

void EnumerateTokens() {
    CK_SLOT_ID_PTR pSlotList = NULL_PTR;
    CK_ULONG ulSlotCount = 0;
    CK_RV rv;

    // 第一步：获取槽位数量
    rv = C_GetSlotList(CK_TRUE, NULL_PTR, &ulSlotCount);
    if (rv != CKR_OK) {
        printf("获取槽位数量失败，错误码: 0x%08lX\n", rv);
        return;
    }
    printf("发现 %lu 个已插令牌的槽位\n", ulSlotCount);

    // 第二步：分配内存并获取列表
    pSlotList = (CK_SLOT_ID_PTR)malloc(sizeof(CK_SLOT_ID) * ulSlotCount);
    rv = C_GetSlotList(CK_TRUE, pSlotList, &ulSlotCount);
    if (rv != CKR_OK) {
        free(pSlotList);
        printf("获取槽位列表失败，错误码: 0x%08lX\n", rv);
        return;
    }

    // 第三步：遍历每个槽位，获取令牌信息
    for (CK_ULONG i = 0; i < ulSlotCount; i++) {
        CK__INFO tokenInfo;
        rv = C_GetTokenInfo(pSlotList[i], &tokenInfo);
        if (rv != CKR_OK) {
            printf("槽位 %lu 获取令牌信息失败\n", pSlotList[i]);
            continue;
        }
        // 安全打印字符串，指定长度为32（非空终止时也安全）
        printf("--- 槽位 %lu 令牌信息 ---\n", pSlotList[i]);
        printf("标签: %.32s\n", tokenInfo.label);
        printf("厂商: %.32s\n", tokenInfo.manufacturerID);
        printf("型号: %.16s\n", tokenInfo.model);
        printf("序列号: %.16s\n", tokenInfo.serialNumber);
        printf("当前会话数: %lu\n", tokenInfo.ulSessionCount);
        // 继续打印其他你需要的信息……
    }

    free(pSlotList);
}

4.4 错误处理与避坑指南

枚举过程中常见的错误码就那么几个，我帮你列了一下：

• CKR_SLOT_ID_INVALID：你传的Slot ID是无效的。一般是因为你从一个旧的slot列表中拿了ID，但设备被拔了。我建议在每次操作前重新获取slot列表，不要缓存太长时间。
• CKR__NOT_PRESENT：当初你传了CK_TRUE，但令牌被拔走了。如果传CK_FALSE，则不会返回这个错误。
• CKR_FUNCTION_FAILED：底层驱动出现问题。我碰到过一次，是因为USB口供电不足导致U盾间歇性掉线。这种问题在代码层面无解，你顶多给用户弹个报错。
• CKR_BUFFER_TOO_SMALL：说明你分配的内存不够。虽然我们用两趟法基本不会遇到，但在多线程环境中，第一趟和第二趟之间如果有人插拔了设备，就可能出现。所以最好在第二趟之后做个断言assert(ulSlotCount > 0)。

我曾经在一个部署到银行机房的程序里，因为枚举时没处理CKR_DEVICE_REMOVED这个错误码，导致操作员在开机状态下换了HSM，程序直接死锁在那里。后来我加了一个重试机制：如果枚举时检测到设备变动，就循环重新枚举3次，每次间隔200毫秒。效果非常好，从那以后再也没有因为设备热插拔出过问题。

4.5 本章知识流程图

下面我把整章的调用关系和组织结构画在一张图上。你可以拿着这张图对照代码，一目了然：

嗯，这就是整个槽位枚举的核心流程。你可以把它当成一个标准模板，每次初始化PKCS#11库之后，照着这张图写一遍枚举代码，保证不会漏掉关键步骤。

最后再唠叨一句：令牌枚举不是一次性工作。在多线程或者支持热插拔的系统中，我建议你提供一个RefreshSlotList()函数，在每次需要操作令牌时都调用。别问我为什么知道——我曾经在服务器上跑了一个自动签名服务，结果运维半夜拔了HSM去别的机器做测试，我们的程序依然拿着旧slot ID操作，硬生生写了半个小时错误日志才挂掉。后来加上重枚举逻辑，就再也没出现类似问题了。