GBXX/T ××××-2009
功能描述 对多个分组的消息进行杂凑计算。 参数 hHash [IN] 杂凑对象句柄
pbData [IN] 指向消息数据的缓冲区 ulDataLen [IN] 消息数据的长度
返回值 SAR_OK： 成功
其他： 错误
备注 调用SKF_DigestUpdate之前，必须调用SKF_DigestInit初始化杂凑计算操作；调
用SKF_DigestUpdate之后，必须调用SKF_DigestFinal结束杂凑计算操作。
7.6.36 结束杂凑
函数原型 ULONG DEVAPI SKF_DigestFinal (HANDLE hHash, BYTE *pHashData, ULONG
*pulHashLen)
功能描述 结束多个分组消息的杂凑计算操作，将杂凑保存到指定的缓冲区。 参数 hHash [IN] 杂凑对象句柄
pHashData [OUT] 返回的杂凑数据缓冲区指针，如果此参数NULL时，由
pulHashLen返回杂凑结果的长度
pulHashLen [IN，OUT] 调用时表示杂凑结果的长度，返回杂凑数据的长度
返回值 SAR_OK： 成功
其他： 错误
备注 SKF_DigestFinal必须用于SKF_DigestUpdate之后。 7.6.37 消息鉴别码运算初始化
函数原型 ULONG DEVAPI SKF_MacInit (HANDLE hKey, BLOCKCIPHERPARAM* pMacParam, HANDLE
*phMac)
功能描述 初始化消息鉴别码计算操作，设置计算消息鉴别码的密钥参数，并返回消息鉴别码
句柄。
参数 hKey [IN] 计算消息鉴别码的密钥句柄
pMacParam [IN] 消息认证计算相关参数，包括初始向量、初始向量长度、填充方
法等
phMac [OUT] 消息鉴别码对象句柄 返回值
SAR_OK： 成功 其他： 错误
备注 消息鉴别码计算采用分组加密算法的CBC模式，将加密结果的最后一块作为计算结
果。待计算数据的长度必须是分组加密算法块长的倍数，接口内部不作数据填充。
7.6.38 单组数据消息鉴别码运算
函数原型 ULONG DEVAPI SKF_Mac(HANDLE hMac, BYTE* pbData, ULONG ulDataLen, BYTE
*pbMacData, ULONG *pulMacLen)
功能描述 SKF_Mac计算单一分组数据的消息鉴别码。 参数 hMac [IN] 消息鉴别码句柄
pbData
ulDataLen pbMacData
[IN] 指向待计算数据的缓冲区 [IN] 待计算数据的长度
[OUT] 指向计算后的Mac结果，如果此参数为NULL时，由pulMacLen返回计算后Mac结果的长度
pulMacLen [IN，OUT] 调用时表示pbMacData缓冲区的长度，返回计算Mac结
果的长度
SAR_OK： 成功 其他： 错误
调用SKF_Mac之前，必须调用SKF_MacInit初始化消息鉴别码计算操作。SKF_Mac
返回值 备注 40
GBXX/T ××××-2009
等价于多次调用SKF_MacUpdate之后再调用SKF_MacFinal。
7.6.39 多组数据消息鉴别码运算
函数原型 ULONG DEVAPI SKF_MacUpdate(HANDLE hMac, BYTE * pbData, ULONG ulDataLen) 功能描述 计算多个分组数据的消息鉴别码。 参数 hMac [IN] 消息鉴别码句柄
pbData [IN] 指向待计算数据的缓冲区
plDataLen
返回值
[IN] 待计算数据的长度
SAR_OK： 成功 其他： 错误
备注 调用SKF_MacUpdate之前，必须调用SKF_MacInit初始化消息鉴别码计算操作；调
用SKF_MacUpdate之后，必须调用SKF_MacFinal结束多个分组数据的消息鉴别码计算操作。
7.6.40 结束消息鉴别码运算
函数原型 ULONG DEVAPI SKF_MacFinal (HANDLE hMac, BYTE *pbMacData, ULONG
*pulMacDataLen)
功能描述 结束多个分组数据的消息鉴别码计算操作。 参数 hMac [IN] 消息鉴别码句柄
pbMacData [OUT] 指向消息鉴别码的缓冲区，当此参数为NULL时，由
pulMacDataLen返回消息鉴别码返回的长度
pulMacDataLen [OUT] 调用时表示消息鉴别码缓冲区的最大长度，返回消息鉴别码
的长度
返回值 SAR_OK： 成功
其他： 错误
备注 SKF_MacFinal必须用于SKF_MacUpdate之后。 7.6.41 关闭密码对象句柄
函数原型 ULONG DEVAPI SKF_CloseHandle(HANDLE hHandle) 功能描述 关闭会话密钥、杂凑、消息鉴别码句柄。 参数 hHandle [IN] 要关闭的对象句柄 返回值 SAR_OK： 成功
其他： 错误
7.6.42 设备命令传输
函数原型 ULONG DEVAPI SKF_Transmit(DEVHANDLE hDev, BYTE* pbCommand, ULONG
ulCommandLen,BYTE* pbData, ULONG* pulDataLen)
功能描述 将命令直接发送给设备，并返回结果。 参数 hDev [IN] 设备句柄 pbCommand [IN] 设备命令 ulCommandLen [IN] 命令长度 pbData [OUT] 返回结果数据 pulDataLen [IN，OUT] 输入时表示结果数据缓冲区长度，输出时表示结果数据
实际长度。
返回值 SAR_OK： 成功
其他： 错误 8
设备的安全要求
8.1 设备使用阶段
设备的使用分成两个阶段：
41
GBXX/T ××××-2009 1）出厂阶段：设备出厂时，预置设备认证密钥，在此阶段除修改设备认证密钥及创建应用操作外，禁止其他操作。
2）应用阶段：已创建了应用的设备进入应用阶段。在此阶段，可进行所有操作。 8.2 权限管理 8.2.1 权限分类
权限分为设备权限，用户权限和管理员权限。 设备权限：通过设备认证后获得设备权限。
用户权限：用户PIN码验证通过后，获得用户权限，用户权限只作用于其所在的应用。
管理员权限：管理员PIN码验证通过后，获得管理员权限，管理员权限只作用于其所在的应用。 8.2.2 权限使用
权限的使用遵循以下要求：
1） 设备权限仅用于创建应用、删除应用和修改设备认证密钥； 2） 创建和删除容器需要用户权限； 3） 创建文件的权限在创建应用时指定； 4） 文件的读写权限在创建文件时指定； 5） 容器内私钥的使用需要用户权限；
6） 用户PIN码和管理员PIN码均具有最大重试次数，在创建应用时设定。当验证PIN码错误次数
达到最大重试次数后，PIN码即锁死； 7） 用户PIN码的解锁需要管理员权限；
8） 修改用户PIN码需要用户权限，修改管理员PIN码需要管理员权限。 8.2.3 设备认证
必须通过设备认证后才能在设备内创建和删除应用。
设备认证使用分组密码算法和设备认证密钥进行。认证的流程如下：
1)：被认证方调用SKF_GenRandom函数从设备获取8字节随机数RND，并用0x00将其填充至密码算法的分块长度，组成数据块D0；
2)：被认证方对D0加密，得到加密结果D1，并调用SKF_DevAuth()，将D1发送至设备； 3)：设备收到D1后，验证D1是否正确。正确则通过设备认证，否则设备认证失败。 8.2.4 PIN码安全要求
1） PIN码长度不少于6个字节；
2） PIN码在设备和本接口之间传输应防止重放攻击； 3） PIN码在设备中应安全存储，不可从设备中导出。 8.3 密钥安全要求
密钥应遵循以下安全要求：
1） 设备内产生的随机数应符合《随机性检测规范》的要求； 2） 设备内产生的会话密钥应使用随机数；
3） 设备内产生非对称密钥使用的素数应满足素性要求；
4） 设备内的密钥应具备有效的密钥保护机制防止解剖、探测和读取； 5） 设备内的密钥应按权限要求使用；
6） 除公钥外的密钥不能以明文形式出现在设备外； 7） 签名私钥必须在设备中产生；
8） 容器内的私钥不能以任何形式导出设备； 9） 删除容器时必须销毁该容器内所有的密钥。 8.4 设备抗攻击要求
设备应具备抗侧信道、电压、频率、紫外线等攻击的能力。
42
GBXX/T ××××-2009
附录A (规范性附录)
密码服务接口错误代码定义和说明
错误代码标识 宏描述 SAR_OK SAR_FAIL SAR_UNKNOWNERR SAR_NOTSUPPORTYETERR SAR_FILEERR SAR_INVALIDHANDLEERR SAR_INVALIDPARAMERR SAR_READFILEERR SAR_WRITEFILEERR SAR_NAMELENERR SAR_KEYUSAGEERR SAR_MODULUSLENERR SAR_NOTINITIALIZEERR SAR_OBJERR SAR_MEMORYERR SAR_TIMEOUTERR SAR_INDATALENERR SAR_INDATAERR SAR_GENRANDERR SAR_HASHOBJERR SAR_HASHERR SAR_GENRSAKEYERR SAR_RSAMODULUSLENERR SAR_CSPIMPRTPUBKEYERR SAR_RSAENCERR SAR_RSADECERR SAR_HASHNOTEQUALERR SAR_KEYNOTFOUNTERR SAR_CERTNOTFOUNTERR SAR_NOTEXPORTERR SAR_DECRYPTPADERR SAR_MACLENERR SAR_BUFFER_TOO_SMALL SAR_KEYINFOTYPEERR SAR_NOT_EVENTERR SAR_DEVICE_REMOVED SAR_PIN_INCORRECT SAR_PIN_LOCKED SAR_PIN_INVALID
预定义值 0X00000000 0X0A000001 0X0A000002 0X0A000003 0X0A000004 0X0A000005 0X0A000006 0X0A000007 0X0A000008 0X0A000009 0X0A00000A 0X0A00000B 0X0A00000C 0X0A00000D 0X0A00000E 0X0A00000F 0X0A000010 0X0A000011 0X0A000012 0X0A000013 0X0A000014 0X0A000015 0X0A000016 0X0A000017 0X0A000018 0X0A000019 0X0A00001A 0X0A00001B 0X0A00001C 0X0A00001D 0X0A00001E 0X0A00001F 0x0A000020 0X0A000021 0X0A000022 0X0A000023 0X0A000024 0X0A000025 0X0A000026 说明 成功 失败 异常错误 不支持的服务 文件操作错误 无效的句柄 无效的参数 读文件错误 写文件错误 名称长度错误 密钥用途错误 模的长度错误 未初始化 对象错误 内存错误 超时 输入数据长度错误 输入数据错误 生成随机数错误 HASH对象错 HASH运算错误 产生RSA密钥错 RSA密钥模长错误 CSP服务导入公钥错误 RSA加密错误 RSA解密错误 HASH值不相等 密钥未发现 证书未发现 对象未导出 解密时做补丁错误 MAC长度错误 缓冲区不足 密钥类型错误 无事件错误 设备已移除 PIN不正确 PIN被锁死 PIN无效 43
GBXX/T ××××-2009 SAR_PIN_LEN_RANGE SAR_USER_ALREADY_LOGGED_IN SAR_USER_PIN_NOT_INITIALIZED SAR_USER_TYPE_INVALID SAR_APPLICATION_NAME_INVALID SAR_APPLICATION_EXISTS SAR_USER_NOT_LOGGED_IN SAR_APPLICATION_NOT_EXISTS SAR_FILE_ALREADY_EXIST SAR_NO_ROOM SAR_FILE_NOT_EXIST
0X0A000027 0X0A000028 0X0A000029 0X0A00002A 0X0A00002B 0X0A00002C 0X0A00002D 0X0A00002E 0X0A00002F 0X0A000030 0X0A000031 PIN长度错误 用户已经登录 没有初始化用户口令 PIN类型错误 应用名称无效 应用已经存在 用户没有登录 应用不存在 文件已经存在 空间不足 文件不存在 44