接口文档
所有函数返回 ULONG（即 unsigned long），成功返回 SAR_OK (0)，失败返回对应错误码。句柄类型均为 void*（HANDLE）。
0016-skf-mock 不附带
skf.h 头文件。C 调用方可通过 dlopen/dlsym 动态加载，或参考 GM/T 0016-2012 规范自行声明函数原型。Rust 调用方可直接引用 skf_mock::ffi 模块。
设备管理
ULONG SKF_EnumDev(BOOL bPresent, LPSTR szNameList, ULONG *pulSize)
枚举当前连接的所有设备名称（两阶段查询模式）。
ULONG SKF_ConnectDev(LPSTR szName, HANDLE *phDev)
连接指定设备，返回设备句柄。Mock 实现中会加载 mock_keys.toml 配置。
| 参数 | 方向 | 说明 |
|---|---|---|
szName | 输入 | 设备名称字符串（必须与配置中一致） |
phDev | 输出 | 设备句柄 |
ULONG SKF_DisConnectDev(HANDLE hDev)
断开设备连接，释放所有关联资源。
ULONG SKF_GetDevInfo(HANDLE hDev, DEVINFO *pDevInfo)
获取设备信息（厂商、型号、序列号、算法支持等）。
ULONG SKF_GetDevState(LPSTR szDevName, ULONG *pulDevState)
查询设备状态（存在/不存在）。
应用与 PIN 管理
ULONG SKF_EnumApplication(HANDLE hDev, LPSTR szAppName, ULONG *pulSize)
枚举设备中所有应用名称（两阶段查询模式）。
ULONG SKF_OpenApplication(HANDLE hDev, LPSTR szAppName, HANDLE *phApp)
打开指定应用，返回应用句柄（基址 0x1001）。
ULONG SKF_CloseApplication(HANDLE hApp)
关闭应用。
ULONG SKF_VerifyPIN(HANDLE hApp, ULONG ulPINType, LPSTR szPIN, ULONG *pulRetryCount)
验证 PIN 码。成功后获得对容器和密钥的访问权限。
| 参数 | 方向 | 说明 |
|---|---|---|
ulPINType | 输入 | 0=管理员 PIN，1=用户 PIN |
szPIN | 输入 | PIN 字符串 |
pulRetryCount | 输出 | 剩余重试次数（PIN 错误时） |
ULONG SKF_ChangePIN(HANDLE hApp, ULONG ulPINType, LPSTR szOldPin, LPSTR szNewPin, ULONG *pulRetryCount)
修改 PIN 码。
ULONG SKF_GetPINInfo(HANDLE hApp, ULONG ulPINType, ULONG *pulMaxRetryCount, ULONG *pulRemainRetryCount, BOOL *pbDefaultPin)
查询 PIN 配置信息。
容器管理
ULONG SKF_EnumContainer(HANDLE hApp, LPSTR szContainerName, ULONG *pulSize)
枚举应用下的所有容器（两阶段查询模式）。
ULONG SKF_OpenContainer(HANDLE hApp, LPSTR szContainerName, HANDLE *phContainer)
打开容器，返回容器句柄（基址 0x2001）。容器内存储签名密钥对、加密密钥对和对应证书。
ULONG SKF_CloseContainer(HANDLE hContainer)
关闭容器。
SM2 非对称运算
ULONG SKF_GenECCKeyPair(HANDLE hContainer, ULONG ulAlgId, ECCPUBLICKEYBLOB *pBlob)
在容器内生成 SM2 密钥对。算法标识：SGD_SM2_1（签名）/ SGD_SM2_3（加密）。
ULONG SKF_ECCSignData(HANDLE hContainer, BYTE *pbData, ULONG ulDataLen, ECCSIGNATUREBLOB *pSignature)
使用容器内签名私钥对数据进行 SM2 签名。输入已是哈希后的 32 字节，或按规范传入 Z||M 的哈希。
ULONG SKF_ECCVerify(HANDLE hDev, ECCPUBLICKEYBLOB *pECCPubKeyBlob, BYTE *pbData, ULONG ulDataLen, ECCSIGNATUREBLOB *pSignature)
使用外部公钥验证 SM2 签名。
ULONG SKF_ExtECCEncrypt(HANDLE hDev, ECCPUBLICKEYBLOB *pECCPubKeyBlob, BYTE *pbPlainText, ULONG ulPlainTextLen, ECCCIPHERBLOB *pCipherText)
使用外部公钥进行 SM2 加密。
ULONG SKF_ExtECCDecrypt(HANDLE hContainer, ECCCIPHERBLOB *pCipher, BYTE *pbPlain, ULONG *pulPlainLen)
使用容器内加密私钥进行 SM2 解密。
ULONG SKF_ExportPublicKey(HANDLE hContainer, BOOL bSignFlag, BYTE *pbBlob, ULONG *pulBlobLen)
导出容器内签名公钥或加密公钥（ECCPUBLICKEYBLOB 格式）。
SM4 对称运算
ULONG SKF_SetSymmKey(HANDLE hDev, BYTE *pbKey, ULONG ulAlgID, HANDLE *phKey)
导入对称密钥，返回密钥句柄（基址 0x3001）。
ULONG SKF_EncryptInit(HANDLE hKey, BLOCKCIPHERPARAM EncryptParam)
初始化加密运算。BLOCKCIPHERPARAM.PaddingType = 1 启用 PKCS7 填充。
ULONG SKF_Encrypt(HANDLE hKey, BYTE *pbData, ULONG ulDataLen, BYTE *pbEncryptedData, ULONG *pulEncryptedLen)
单组 SM4 加密（ECB/CBC）。
ULONG SKF_DecryptInit(HANDLE hKey, BLOCKCIPHERPARAM DecryptParam)
初始化解密运算。
ULONG SKF_Decrypt(HANDLE hKey, BYTE *pbEncryptedData, ULONG ulEncryptedLen, BYTE *pbData, ULONG *pulDataLen)
单组 SM4 解密。
SM3 哈希运算
ULONG SKF_DigestInit(HANDLE hDev, ULONG ulAlgID, ECCPUBLICKEYBLOB *pPubKey, BYTE *pucID, ULONG ulIDLen, HANDLE *phHash)
初始化哈希运算，返回哈希句柄（基址 0x4001）。若传入公钥，会自动计算 Z = SM3(entlen||uid||curve_params||pubkey) 并写入缓冲头部（用于 SM2 签名前的预哈希）。
ULONG SKF_Digest(HANDLE hHash, BYTE *pbData, ULONG ulDataLen, BYTE *pbHashData, ULONG *pulHashLen)
单组哈希：一次性完成 Update + Final。
ULONG SKF_DigestUpdate(HANDLE hHash, BYTE *pbData, ULONG ulDataLen)
追加哈希数据。
ULONG SKF_DigestFinal(HANDLE hHash, BYTE *pHashData, ULONG *pulHashLen)
完成哈希计算，输出 32 字节 SM3 摘要。
证书管理
ULONG SKF_ImportCertificate(HANDLE hContainer, BOOL bSignFlag, BYTE *pbCert, ULONG ulCertLen)
向容器导入证书（DER 格式）。
ULONG SKF_ExportCertificate(HANDLE hContainer, BOOL bSignFlag, BYTE *pbCert, ULONG *pulCertLen)
从容器导出证书。
错误码列表
| 常量 | 值 | 含义 |
|---|---|---|
SAR_OK | 0x00000000 | 成功 |
SAR_FAIL | 0x0A000001 | 一般失败（含设备未连接） |
SAR_UNKNOWNERR | 0x0A000002 | 未知错误 |
SAR_NOTSUPPORTYETERR | 0x0A000003 | 不支持（RSA/MAC 等 Stub） |
SAR_FILEERR | 0x0A000004 | 文件错误 |
SAR_INVALIDHANDLEERR | 0x0A000005 | 句柄无效 |
SAR_INVALIDPARAMERR | 0x0A000006 | 参数无效（空指针等） |
SAR_READFILEERR | 0x0A000007 | 读文件错误 |
SAR_WRITEFILEERR | 0x0A000008 | 写文件错误 |
SAR_NOTINITIALIZEERR | 0x0A00000C | 未调用 EncryptInit/DecryptInit |
SAR_INDATALENERR | 0x0A000011 | 输出缓冲太小（两阶段查询模式） |
SAR_PIN_INCORRECT | 0x0A000029 | PIN 错误 |
SAR_PIN_LOCKED | 0x0A00002A | PIN 锁定 |
SAR_KEYNOTFOUNDERR | 0x0A00001B | 容器内无对应密钥对 |