接口文档
所有函数返回 int，成功返回 SDR_OK (0)，失败返回对应错误码。句柄类型均为 void*。
设备管理
int SDF_OpenDevice(void **phDeviceHandle)
打开密码设备，初始化 Mock 上下文。必须在所有其他操作之前调用。
| 参数 | 方向 | 说明 |
|---|---|---|
phDeviceHandle | 输出 | 设备句柄（Mock 固定输出 0x1） |
此函数会在可执行文件目录/当前目录搜索
config.toml，不存在则返回 SDR_CONFIGERR。int SDF_CloseDevice(void *hDeviceHandle)
关闭密码设备，释放全局设备上下文。
int SDF_OpenSession(void *hDeviceHandle, void **phSessionHandle)
在已打开的设备上创建一个新会话。每个会话拥有独立的密钥仓库和哈希上下文。
| 参数 | 方向 | 说明 |
|---|---|---|
phSessionHandle | 输出 | 会话句柄，后续所有操作的第一个参数 |
int SDF_CloseSession(void *hSessionHandle)
关闭会话，销毁该会话的所有会话密钥。
int SDF_GetDeviceInfo(void *hSessionHandle, DEVICEINFO *pstDeviceInfo)
获取设备信息，填充 DEVICEINFO 结构体。
| 字段 | 说明 |
|---|---|
| IssuerName[40] | 厂商名称（来自 mock_keys.toml manufacturer） |
| DeviceName[16] | 设备名称 |
| DeviceSerial[16] | 序列号 |
| DeviceVersion | 固定 0x00010000 |
| StandardVersion | 固定 0x00020000（GM/T 0018-2023） |
密钥管理
int SDF_GenerateRandom(void *hSessionHandle, unsigned int uiLength, unsigned char *pucRandom)
生成密码学安全随机数（基于操作系统 OsRng）。
| 参数 | 说明 |
|---|---|
uiLength | 随机数字节数（1 ~ 4096） |
pucRandom | 输出缓冲区（调用者分配，大小 ≥ uiLength） |
int SDF_GenerateKeyPair_ECC(void *hSessionHandle, unsigned int uiAlgID, unsigned int uiKeyBits, ECCrefPublicKey *pucPublicKey, ECCrefPrivateKey *pucPrivateKey)
生成临时 SM2 密钥对（存于会话内存，不持久化）。
| 参数 | 说明 |
|---|---|
uiAlgID | SGD_SM2_1（签名）或 SGD_SM2_3（加密） |
uiKeyBits | 256（SM2 固定） |
int SDF_GenerateKeyWithKEK(void *hSessionHandle, unsigned int uiLength, unsigned int uiAlgID, unsigned int uiKEKIndex, unsigned char *pucKey, unsigned int *puiKeyLength, void **phKeyHandle)
生成随机 SM4 会话密钥，并用指定 KEK（SM4-ECB）加密保护后��出密文。
需要
mock_keys.toml 中配置对应索引的 KEK。| 参数 | 说明 |
|---|---|
uiLength | 密钥长度（字节），当前仅支持 16（SM4 128位） |
uiKEKIndex | KEK 索引（从 1 开始） |
pucKey | 输出：KEK 加密后的密文（16字节） |
phKeyHandle | 输出：会话密钥句柄 |
int SDF_ImportKeyWithKEK(void *hSessionHandle, unsigned int uiAlgID, unsigned int uiKEKIndex, const unsigned char *pucKey, unsigned int uiKeyLength, void **phKeyHandle)
用 KEK 解密导入会话密钥。与 SDF_GenerateKeyWithKEK 配对使用。
int SDF_GenerateKeyWithIPK_ECC(void *hSessionHandle, unsigned int uiIPKIndex, unsigned int uiKeyBits, ECCCipher *pucKey, void **phKeyHandle)
生成随机 SM4 会话密钥，用内部 SM2 加密公钥（IPK）封装后输出密文结构。
int SDF_ImportKeyWithISK_ECC(void *hSessionHandle, unsigned int uiISKIndex, const ECCCipher *pucKey, void **phKeyHandle)
用内部 SM2 加密私钥（ISK）解密导入会话密钥。需先调用 SDF_GetPrivateKeyAccessRight 授权。
int SDF_DestroyKey(void *hSessionHandle, void *hKeyHandle)
销毁会话密钥，从内存中安全清除。句柄销毁后不可再使用。
非对称运算（SM2）
int SDF_ExternalSign_ECC(void *hSessionHandle, unsigned int uiAlgID, const ECCrefPrivateKey *pucPrivateKey, const unsigned char *pucData, unsigned int uiDataLength, ECCSignature *pucSignature)
使用外部私钥对 32字节预哈希数据（e 值）进行 SM2 签名。
输入必须是已哈希的 32 字节数据，不是原始消息。通常先调用
SDF_HashFinal 得到哈希值再传入。int SDF_ExternalVerify_ECC(void *hSessionHandle, unsigned int uiAlgID, const ECCrefPublicKey *pucPublicKey, const unsigned char *pucData, unsigned int uiDataLength, const ECCSignature *pucSignature)
使用外部公钥验证签名。输入同样须为 32 字节预哈希值。
int SDF_InternalSign_ECC(void *hSessionHandle, unsigned int uiISKIndex, const unsigned char *pucData, unsigned int uiDataLength, ECCSignature *pucSignature)
使用预置签名私钥对原始消息签名（内部自动计算 Z 值和哈希）。需先调用 SDF_GetPrivateKeyAccessRight。
int SDF_InternalVerify_ECC(void *hSessionHandle, unsigned int uiIPKIndex, const unsigned char *pucData, unsigned int uiDataLength, const ECCSignature *pucSignature)
使用预置签名公钥验签（内部自动计算 Z 值）。
int SDF_ExternalEncrypt_ECC(void *hSessionHandle, unsigned int uiAlgID, const ECCrefPublicKey *pucPublicKey, const unsigned char *pucData, unsigned int uiDataLength, ECCCipher *pucEncData)
SM2 公钥加密。明文最大 136 字节，输出 ECCCipher 结构。
int SDF_ExternalDecrypt_ECC(void *hSessionHandle, unsigned int uiAlgID, const ECCrefPrivateKey *pucPrivateKey, const ECCCipher *pucEncData, unsigned char *pucData, unsigned int *puiDataLength)
SM2 私钥解密。
对称运算（SM4）
int SDF_Encrypt(void *hSessionHandle, void *hKeyHandle, unsigned int uiAlgID, const unsigned char *pucIV, const unsigned char *pucData, unsigned int uiDataLength, unsigned char *pucEncData, unsigned int *puiEncDataLength)
SM4 加密。支持算法模式：
| 模式 | 标识 | IV | 数据长度 |
|---|---|---|---|
| ECB | SGD_SM4_ECB | 忽略 | 必须是 16 的倍数 |
| CBC | SGD_SM4_CBC | 必填 16B | 必须是 16 的倍数 |
| CFB/OFB/CTR | SGD_SM4_CFB/OFB/CTR | 必填 16B | 任意长度 |
int SDF_Decrypt(void *hSessionHandle, void *hKeyHandle, unsigned int uiAlgID, const unsigned char *pucIV, const unsigned char *pucEncData, unsigned int uiEncDataLength, unsigned char *pucData, unsigned int *puiDataLength)
SM4 解密，参数与 SDF_Encrypt 对称。
int SDF_CalculateMAC(void *hSessionHandle, void *hKeyHandle, unsigned int uiAlgID, const unsigned char *pucIV, const unsigned char *pucData, unsigned int uiDataLength, unsigned char *pucMAC, unsigned int *puiMACLength)
计算 SM4-CBC-MAC（取 CBC 最后一块密文，固定 16 字节）。数据长度必须是 16 的倍数。
哈希运算（SM3）
int SDF_HashInit(void *hSessionHandle, unsigned int uiAlgID, const ECCrefPublicKey *pucPublicKey, const unsigned char *pucID, unsigned int uiIDLength)
初始化 SM3 哈希上下文。
| 参数 | 说明 |
|---|---|
pucPublicKey | SM2 公钥（非 NULL 时自动计算 Z 值并预写入状态，用于 SM3withSM2 签名哈希） |
pucID | 用户 ID（NULL 时默认使用 "1234567812345678"） |
int SDF_HashUpdate(void *hSessionHandle, const unsigned char *pucData, unsigned int uiDataLength)
向哈希上下文追加数据，可多次调用。
int SDF_HashFinal(void *hSessionHandle, unsigned char *pucHash, unsigned int *puiHashLength)
完成哈希计算，输出 32 字节 SM3 摘要。
int SDF_HMACInit(void *hSessionHandle, void *hKeyHandle, unsigned int uiAlgID)
初始化 HMAC-SM3 上下文，hKeyHandle 指向的对称会话密钥作为 HMAC 密钥。
int SDF_HMACUpdate(void *hSessionHandle, const unsigned char *pucData, unsigned int uiDataLength)
向 HMAC 上下文追加数据。
int SDF_HMACFinal(void *hSessionHandle, unsigned char *pucMAC, unsigned int *puiMACLength)
完成 HMAC-SM3 计算，输出 32 字节 MAC 值。
错误码
| 常量 | 值 | 含义 |
|---|---|---|
SDR_OK | 0x00000000 | 操作成功 |
SDR_UNKNOWERR | 0x01000001 | 未知错误 |
SDR_OPENDEVICE | 0x01000005 | 设备未打开 |
SDR_OPENSESSION | 0x01000006 | 会话未打开 |
SDR_PARDENY | 0x01000007 | 权限拒绝 |
SDR_KEYNOTEXIST | 0x01000008 | 密钥不存在 |
SDR_ALGNOTSUPPORT | 0x01000009 | 算法不支持 |
SDR_SIGNERR | 0x0100000D | 签名失败 |
SDR_VERIFYERR | 0x0100000E | 验签/认证失败 |
SDR_SYMOPERR | 0x0100000F | 对称运算失败 |
SDR_KEYINDEX | 0x01000019 | 密钥索引越界 |
SDR_INVALIDHANDLE | 0x0100001A | 无效句柄 |
SDR_PARAMERR | 0x01000100 | 参数错误（空指针/非法长度） |
SDR_CONFIGERR | 0x01000101 | 配置文件错误/不存在 |