5.1 hsm-lite项目概述：教学级PKCS#11实现
项目定位
hsm-lite是一个教学级的PKCS#11实现：
hsm-lite定位：
教学导向：
├── 约600行核心C代码
├── 简洁清晰，突出核心流程
├── 可编译运行，真实测试
└── 不追求功能完备
实现范围：
├── 初始化：C_Initialize, C_Finalize
├── Slot管理：C_GetSlotList
├── Session管理：C_OpenSession, C_CloseSession
├── Object管理：C_CreateObject, C_DestroyObject, C_GetAttributeValue
├── 密钥生成：C_GenerateKey（AES）
├── 加密解密：C_Encrypt/C_Decrypt（AES-ECB/CBC）
└── 随机数：C_GenerateRandom
不实现：
├── RSA算法
├── 签名验证
├── 登录认证（C_Login）
├── 真实AES（使用XOR模拟）
└── 多线程安全
文件结构
实际文件结构（精简版）：
hsm-lite/
├── hsm_lite.h PKCS#11函数声明（约210行）
├── hsm_types.h 类型定义（约450行）
├── hsm_common.h 公共定义
├── hsm_lite.c 核心实现（约615行）
├── hsm_test.c 测试程序（约230行）
├── Makefile 多架构编译
└── README.md 项目文档
单文件架构：
hsm-lite采用单文件实现，所有逻辑在hsm_lite.c中：
/* hsm_lite.c 内部结构 */
// 数据结构定义
typedef struct hsm_key_t { ... }; // AES密钥对象
typedef struct hsm_session_t { ... }; // Session对象
static struct { ... } g_ctx; // 全局上下文
// 内部辅助函数
static hsm_session_t* find_session();
static hsm_key_t* find_key();
static CK_RV get_random_bytes();
static CK_RV aes_encrypt_ecb(); // 简化AES（XOR）
static CK_RV aes_encrypt_cbc();
// PKCS#11函数实现
CK_RV C_Initialize();
CK_RV C_Finalize();
CK_RV C_GetSlotList();
CK_RV C_OpenSession();
CK_RV C_CloseSession();
CK_RV C_GenerateKey();
CK_RV C_EncryptInit();
CK_RV C_Encrypt();
CK_RV C_DecryptInit();
CK_RV C_Decrypt();
CK_RV C_CreateObject();
CK_RV C_DestroyObject();
CK_RV C_GetAttributeValue();
CK_RV C_GenerateRandom();
核心数据结构
密钥对象：
/* AES密钥对象（简化版） */
typedef struct {
CK_OBJECT_HANDLE handle; // 对象句柄
CK_BYTE key[32]; // AES-256密钥值
CK_ULONG key_len; // 密钥长度
CK_BBOOL in_use; // 是否正在使用
} hsm_key_t;
Session对象：
/* Session对象（简化版） */
typedef struct {
CK_SESSION_HANDLE handle; // Session句柄
CK_SLOT_ID slot_id; // Slot ID
CK_BBOOL in_use; // 是否正在使用
CK_BBOOL is_rw; // 是否读写Session
/* 当前操作状态 */
CK_MECHANISM_TYPE active_mech; // 当前机制
CK_OBJECT_HANDLE active_key; // 当前密钥
CK_BBOOL encrypt_init;// 加密已初始化
CK_BBOOL decrypt_init;// 解密已初始化
} hsm_session_t;
全局上下文：
/* 全局上下文 */
static struct {
CK_BBOOL initialized; // 是否已初始化
hsm_session_t sessions[HSM_MAX_SESSIONS]; // Session数组
hsm_key_t keys[HSM_MAX_OBJECTS]; // 密钥数组
CK_ULONG session_count; // Session计数
CK_ULONG key_count; // 密钥计数
CK_SESSION_HANDLE next_session_handle; // 下一个Session句柄
CK_OBJECT_HANDLE next_key_handle; // 下一个密钥句柄
} g_ctx;
简化AES实现
hsm-lite使用XOR模拟AES加密（教学目的）：
/* AES加密（简化：XOR模拟） */
static CK_RV aes_encrypt_ecb(CK_BYTE_PTR key, CK_BYTE_PTR data,
CK_ULONG len, CK_BYTE_PTR out)
{
/* 教学简化：直接异或（非真实AES） */
for (CK_ULONG i = 0; i < len; i++) {
out[i] = data[i] ^ key[i % HSM_AES_KEY_SIZE];
}
return CKR_OK;
}
static CK_RV aes_decrypt_ecb(CK_BYTE_PTR key, CK_BYTE_PTR data,
CK_ULONG len, CK_BYTE_PTR out)
{
/* XOR加密和解密相同 */
for (CK_ULONG i = 0; i < len; i++) {
out[i] = data[i] ^ key[i % HSM_AES_KEY_SIZE];
}
return CKR_OK;
}
CBC模式实现：
/* CBC模式（简化版） */
static CK_RV aes_encrypt_cbc(CK_BYTE_PTR key, CK_BYTE_PTR iv,
CK_BYTE_PTR data, CK_ULONG len,
CK_BYTE_PTR out)
{
CK_BYTE block[16];
CK_BYTE *prev = iv;
for (CK_ULONG i = 0; i < len; i += 16) {
// 先与前一块异或
for (CK_ULONG j = 0; j < 16 && i + j < len; j++) {
block[j] = data[i + j] ^ prev[j];
}
// 再加密（XOR）
aes_encrypt_ecb(key, block, 16, out + i);
prev = out + i; // 更新前一块指针
}
return CKR_OK;
}
为什么不实现真实AES？
简化设计原因：
教学目的：
├── 展示PKCS#11接口流程
├── 不需要真实密码算法
├── XOR足以演示加密概念
└── 真实AES需要大量代码
如需真实AES：
├── 可链接OpenSSL或Botan
├── 或使用Mbed TLS
└── 教学版保持简单
PKCS#11类型定义
hsm_lite.h定义的简化类型：
/* 基础类型 */
typedef unsigned long CK_ULONG;
typedef unsigned char CK_BYTE;
typedef unsigned char CK_BBOOL;
typedef CK_ULONG CK_FLAGS;
#define CK_TRUE 1
#define CK_FALSE 0
/* Handle类型 */
typedef CK_ULONG CK_SLOT_ID;
typedef CK_ULONG CK_SESSION_HANDLE;
typedef CK_ULONG CK_OBJECT_HANDLE;
/* 返回值 */
typedef CK_ULONG CK_RV;
#define CKR_OK 0
#define CKR_SLOT_ID_INVALID 3
#define CKR_SESSION_HANDLE_INVALID 48
#define CKR_OBJECT_HANDLE_INVALID 66
#define CKR_MECHANISM_INVALID 112
#define CKR_FUNCTION_NOT_INITIALIZED 13
/* 对象类型 */
#define CKO_SECRET_KEY 4
#define CKK_AES 31
/* 机制类型 */
#define CKM_AES_KEY_GEN 0x00001080
#define CKM_AES_ECB 0x00001081
#define CKM_AES_CBC 0x00001082
/* 属性类型 */
#define CKA_CLASS 0
#define CKA_KEY_TYPE 256
#define CKA_VALUE_LEN 277
#define CKA_VALUE 17
/* 结构定义 */
typedef struct CK_MECHANISM {
CK_ULONG mechanism;
void *pParameter;
CK_ULONG ulParameterLen;
} CK_MECHANISM;
typedef struct CK_ATTRIBUTE {
CK_ULONG type;
void *pValue;
CK_ULONG ulValueLen;
} CK_ATTRIBUTE;
支持的函数列表
hsm-lite实现的14个PKCS#11函数：
PKCS#11函数列表：
初始化管理：
├── C_Initialize 初始化PKCS#11库
└── C_Finalize 清理PKCS#11库
Slot管理：
└── C_GetSlotList 获取Slot列表（单Slot）
Session管理：
├── C_OpenSession 打开Session
└── C_CloseSession 关闭Session
Object管理：
├── C_CreateObject 创建对象
├── C_DestroyObject 销毁对象
└── C_GetAttributeValue 获取属性值
密钥操作：
└── C_GenerateKey 生成密钥（AES）
加密解密：
├── C_EncryptInit 初始化加密
├── C_Encrypt 执行加密
├── C_DecryptInit 初始化解密
└── C_Decrypt 执行解密
随机数：
└── C_GenerateRandom 生成随机数
一个类比：教学模型车
教学模型车类比：
hsm-lite（模型车）
│
├── 特点
│ ├── 简化：不是真实汽车
│ ├── 教学：展示汽车原理
│ ├── 可动：可以实际运行
│ └── 精简：去掉复杂部件
│
├── 保留部分
│ ├── 发动机（核心逻辑）
│ ├── 方向盘（接口层）
│ ├── 轮子（基础功能）
│ └── 车架（数据结构）
│
├── 简化部分
│ ├── 发动机→电池（XOR代替AES）
│ ├── 无变速箱（无多线程）
│ ├── 无刹车系统（无错误恢复）
│ └── 无安全气囊（无认证）
│
├── 学习价值
│ ├── 理解汽车架构
│ ├── 理解各部件作用
│ ├── 可以扩展改进
│ └── 为真实设计打基础
│
└── 不适合
├── 真实上路（生产环境）
├── 高速行驶（高性能）
└── 长途旅行（长时间运行）
本篇小结
hsm-lite是一个教学级PKCS#11实现：
定位：
- 教学导向，约600行代码
- 单文件实现，简洁清晰
- 可编译运行，真实测试
文件结构：
hsm_lite.h：函数声明hsm_lite.c：核心实现hsm_test.c：测试程序
实现范围：
- 初始化/Slot/Session管理
- AES密钥生成/加密解密
- Object创建/销毁/属性
- 随机数生成
简化设计：
- XOR模拟AES（教学目的）
- 单Slot设计
- 无认证机制
- 无多线程安全
下一节，我们将详细解析每个函数的实现。
【下集预告】
C_Initialize如何实现？
Session如何管理？
AES加密流程？
测试程序如何运行？
下一节，核心接口实现。