PKCS#11 v3.1 密码模块接口规范：Cryptoki 架构与 HSM 通信协议深度解析

// 1. 初始化 Cryptoki
CK_C_INITIALIZE_ARGS init_args = {NULL, NULL, NULL, FALSE, 0, NULL};
C_Initialize(&init_args);

// 2. 获取可用槽位
CK_ULONG slotCount;
CK_SLOT_ID slots[16];
C_GetSlotList(CK_TRUE, slots, &slotCount);

// 3. 打开会话（必须先于登录）
CK_SESSION_HANDLE hSession;
C_OpenSession(slots[0], CKF_SERIAL_SESSION | CKF_RW_SESSION, 
              NULL, NULL, &hSession);

// 4. 登录会话
C_Login(hSession, CKU_USER, (CK_UTF8CHAR_PTR)userPin, ulPinLen);

┌─────────────────────────────────────┐
│  CKO_PUBLIC_KEY                     │  ← 公钥（可导出）
│  ├── CKK_RSA                         │
│  ├── CKK_EC                           │
│  └── CKK_DH                           │
├─────────────────────────────────────┤
│  CKO_SECRET_KEY                     │  ← 对称密钥
│  ├── CKK_GENERIC_SECRET              │
│  ├── CKK_DES / DES3                  │
│  └── CKK_AES                          │
├─────────────────────────────────────┤
│  CKO_PRIVATE_KEY                    │  ← 私钥（HSM 内存储）
│  ├── CKK_RSA (CKA_SENSITIVE=TRUE)   │
│  ├── CKK_EC (CKA_EXTRACTABLE=FALSE) │
│  └── CKK_DSA                          │
└─────────────────────────────────────┘

CK_KEY_TYPE keyType = CKK_EC;
CK_BBOOL ck_true = TRUE;
CK_BBOOL ck_false = FALSE;

CK_ATTRIBUTE template[] = {
    {CKA_LABEL, "My EC Key", 8},
    {CKA_KEY_TYPE, &keyType, sizeof(keyType)},
    {CKA_TOKEN, &ck_true, sizeof(ck_true)},   // 持久化到令牌
    {CKA_SENSITIVE, &ck_true, sizeof(ck_true)}, // 不可导出
    {CKA_EXTRACTABLE, &ck_false, sizeof(ck_false)},
    {CKA_SIGN, &ck_true, sizeof(ck_true)},
    {CKA_ALWAYS_AUTH, &ck_true, sizeof(ck_true)}, // 每次签名需认证
};

CK_OBJECT_HANDLE hPrivateKey;
C_CreateObject(hSession, template, 7, &hPrivateKey);

┌─────────────────────────────────────┐
│  Signature Mechanisms                │
├─────────────────────────────────────┤
│  CKM_RSA_PKCS                        │  ← v1.5 签名
│  CKM_RSA_PKCS_PSS                   │  ← PSS 填充
│  CKM_ECDSA                            │  ← EC 签名（NIST）
│  CKM_ECDSA_SHA224/256/384/512     │  ← 带哈希的 ECDSA
├─────────────────────────────────────┤
│  Key Agreement Mechanisms           │
├─────────────────────────────────────┤
│  CKM_DH_KEY_PAIR_GEN                 │
│  CKM_ECDH1_COFACTOR_KDF             │
│  CKM_ECDH1_DERIVE                    │
│  CKM_X25519                            │  ← v3.1 新增
│  CKM_X448                              │
├─────────────────────────────────────┤
│  Encryption Mechanisms               │
├─────────────────────────────────────┤
│  CKM_AES_CBC                          │
│  CKM_AES_GCM                          │  ← AEAD
│  CKM_AES_CTR                          │
│  CKM_RSA_PKCS_OAEP                   │  ← OAEP 填充
├─────────────────────────────────────┤
│  Hash Mechanisms                      │
├─────────────────────────────────────┤
│  CKM_SHA-1 / SHA-224 / SHA-256      │
│  CKM_SHA-384 / SHA-512               │
│  CKM_SHA3-256 / SHA3-512             │  ← v3.1 新增
└─────────────────────────────────────┘

// RSA-OAEP 加密机制参数
CK_RSA_PKCS_OAEP_PARAMS oaep_params = {
    CKM_SHA_256,                      // hashAlg
    CKG_MGF1_SHA_256,                 // mgf
    CKZ_DATA_ENCODING,                // source
    NULL_PTR,                         // pSourceData
    0                                 // ulSourceDataLen
};

CK_MECHANISM mechanism = {
    CKM_RSA_PKCS_OAEP,
    &oaep_params,
    sizeof(oaep_params)
};

C_EncryptInit(hSession, &mechanism, hPublicKey);
C_Encrypt(hSession, plaintext, plaintextLen, ciphertext, &ciphertextLen);

// 不推荐：大量对象时使用 FindObjects
CK_OBJECT_HANDLE hFound[10];
CK_ULONG ulCount;
C_FindObjectsInit(hSession, template, 3);
C_FindObjects(hSession, hFound, 10, &ulCount);
C_FindObjectsFinal(hSession);

// 推荐：使用 CKA_ID 直接获取
CK_ATTRIBUTE idTemplate[] = {
    {CKA_ID, targetId, idLen}
};
CK_OBJECT_HANDLE hKey;
C_GetObjectAttributeValue(hSession, hKey, idTemplate, 1);