GBXX/T ××××-2009 PrivateKey BYTE数组 私有密钥 有限域上的整数 #define ECC_MAX_MODULUS_BITS_LEN 512 6.4.7 分组密码参数 （1）类型定义
typedef struct Struct_BLOCKCIPHERPARAM{
BYTE IV[MAX_IV_LEN]; ULONG IVLen;
ULONG PaddingType; ULONG FeedBitLen;
} BLOCKCIPHERPARAM, *PBLOCKCIPHERPARAM; （2）数据项描述参见表12：
表12
数据项 IV 类型 意义 备注 BYTE数组 初始向量，MAX_IV_LEN为初始化向量的最大长度 #define MAX_IV_LEN 32 ULONG 初始向量实际长度（按字节计算） 填充方式，0表示不填充，1表示按照PKCS#5方式进行填充 反馈值的位长度（按位计算） IVLen 只针对OFB、CFB模式 PaddingType ULONG FeedBitLen 6.4.8 文件属性 （1）类型定义
ULONG typedef struct Struct_FILEATTRIBUTE{
CHAR FileName[32]; ULONG FileSize; ULONG ReadRights; ULONG WriteRights;
} FILEATTRIBUTE, *PFILEATTRIBUTE; （2）数据项描述参见表13：
表13
数据项 FileName FileSize ReadRights WriteRights 类型 CHAR数组 ULONG ULONG ULONG 意义 文件名 文件大小 读取权限 写入权限 备注 ASCIIZ字符串，最大长度为32 创建文件时定义的文件大小 读取文件需要的权限 写入文件需要的权限
6.4.9 权限类型
权限类型的定义参见表14：
表14
权限类型 SECURE_NEVER_ACCOUNT
值 0x00000000 不允许 15
说明 GBXX/T ××××-2009 SECURE_ADM_ACCOUNT SECURE_USER_ACCOUNT SECURE_ANYONE_ACCOUNT 0x00000001 管理员权限 0x00000010 用户权限 0x000000FF 任何人 6.4.10 设备状态 设备状态的定义参见表15：
表15
常量 设备不存在 设备存在 7
接口函数
常量标识 DEV_ABSENT_STATE 值 0x00000000 描述 DEV_PRESENT_STATE 0x00000001 7.1 设备管理
设备管理主要完成设备的等待、设备插拔、枚举、连接、断开、设置设备标签、获取设备信息、锁定设备、解锁设备操作。设备管理系列函数如表16所示：
表16 函数名称 SKF_WaitForDevEvent SKF_EnumDev SKF_ConnectDev SKF_DisconnectDev SKF_GetDevState SKF_SetLabel SKF_GetDevInfo SKF_LockDev SKF_UnlockDev 功能 等待设备插拔事件 枚举设备 连接设备 断开设备 获取设备状态 设置设备标签 获取设备信息 锁定设备 解锁设备 备注 枚举支持的设备 共享模式打开返回设备句柄 断开设备连接 获取设备是否存在的状态 获取设备信息 锁定设备 解锁设备 7.1.1 等待设备插拔事件
函数原型 ULONG DEVAPI SKF_WaitForDevEvent(LPSTR szDevName,ULONG *pulDevNameLen, ULONG
*pulEvent)
功能描述 等待设备插拔事件：
该函数等待设备插入或者拔除事件。szDevName返回发生事件的设备名称。 参数
szDevName pulDevNameLen
[OUT] 发生事件的设备名称
[IN/OUT] 输入/输出参数，当输入时表示缓冲区长度，输出时表示设备名称的有效长度,长度包含字符串结束符。
pulEvent [OUT]事件类型。1表示插入，2表示拔出。
返回值 SAR_OK表示成功，其它表示失败。
可能的错误值：
SAR_UNKNOWNERR发生未知错误。 SAR_MEMORYERR发生内存错误。 SAR_TIMEOUTERR等待超时。
SAR_NOT_EVENTERR 无事件错误。 SAR_INVALIDPARAMERR 参数无效。
7.1.2 枚举设备
函数原型 ULONG DEVAPI SKF_EnumDev(BOOL bPresent, LPSTR szNameList, ULONG *pulSize) 功能描述 获得当前系统中的设备列表。 16
GBXX/T ××××-2009
参数 bPresent [IN] 为TRUE表示取当前设备状态为存在的设备列表。为FALSE
表示取当前驱动支持的设备列表。
szNameList [OUT] 设备名称列表。如果该参数为NULL，将由pulSize返回所
需要的内存空间大小。每个设备的名称以单个’\\0’结束，以双’\\0’表示列表的结束。
pulSize [IN, OUT] 输入参数，输入设备名称列表的缓冲区长度，输出参
数，返回szNameList所需要的空间大小。
返回值 SAR_OK表示成功，其它表示失败。
可能的错误值：
SAR_UNKNOWNERR发生未知错误； SAR_MEMORYERR发生内存错误； SAR_BUFFER_TOO_SMALL 缓存不够。
7.1.3 连接设备
函数原型 ULONG DEVAPI SKF_ConnectDev (LPSTR szName, DEVHANDLE *phDev) 功能描述 通过设备名称连接设备，返回设备的句柄。 参数 szName [IN] 设备名称
phDev [OUT] 返回设备操作句柄
返回值 SAR_OK表示成功，其它表示失败。
可能的错误值：
SAR_NOTEXIST设备不存在； SAR_UNKNOWNERR发生未知错误； SAR_MEMORYERR发生内存错误。
7.1.4 断开连接
函数原型 ULONG DEVAPI SKF_DisConnectDev (DEVHANDLE hDev) 功能描述 断开一个已经连接的设备，并释放句柄。 参数 hDev [IN] 连接设备时返回的设备句柄 返回值 SAR_OK表示成功，其它表示失败。
可能的错误值：
SAR_UNKNOWNERR发生未知错误； SAR_MEMORYERR发生内存错误； SAR_DEVICE_REMOVED 设备已移除。
备注 如果该设备已被锁定，函数应首先解锁该设备。断开连接操作并不影响设备的权限
状态。
7.1.5 获取设备状态
函数原型 ULONG DEVAPI SKF_GetDevState(LPSTR szDevName, ULONG *pulDevState) 功能描述 获取设备是否存在的状态。 参数 szDevName [IN] 设备名称
pulDevState [OUT] 返回设备状态
返回值 SAR_OK表示成功，其它表示失败。
可能的错误值：
SAR_UNKNOWNERR发生未知错误； SAR_MEMORYERR发生内存错误。
7.1.6 设置设备标签
函数原型 ULONG DEVAPI SKF_SetLabel (DEVHANDLE hDev, LPSTR szLabel) 功能描述 设置设备标签。 参数 hDev [IN] 连接设备时返回的设备句柄
17
GBXX/T ××××-2009
szLabel [IN] 设备标签字符串。该字符串应小于32字节。
返回值 SAR_OK表示成功，其它表示失败。
可能的错误值：
SAR_UNKNOWNERR发生未知错误； SAR_INVALIDPARAMETER参数错误； SAR_DEVICE_REMOVED 设备已移除。
7.1.7 获取设备信息
函数原型 ULONG DEVAPI SKF_GetDevInfo (DEVHANDLE hDev, DEVINFO *pDevInfo) 功能描述 获取设备的一些特征信息，包括设备标签、厂商信息、支持的算法等。 参数 hDev [IN] 连接设备时返回的设备句柄
pDevInfo [OUT] 返回设备信息
返回值 SAR_OK表示成功，其它表示失败。
可能的错误值：
SAR_UNKNOWNERR发生未知错误； SAR_MEMORYERR发生内存错误； SAR_DEVICE_REMOVED 设备已移除。
7.1.8 锁定设备
函数原型 ULONG DEVAPI SKF_LockDev (DEVHANDLE hDev, ULONG ulTimeOut) 功能描述 获得设备的独占使用权。 参数 hDev [IN] 连接设备时返回的设备句柄
ulTimeOut [IN] 超时时间，单位为毫秒。如果为0xFFFFFFFF表示无限等待。
返回值 SAR_OK表示成功，其它表示失败。
返回其他错误码：
SAR_UNKNOWNERR发生未知错误； SAR_DEVICE_REMOVED 设备已移除； SAR_TIMEOUT 超时返回。
7.1.9 解锁设备
函数原型 ULONG DEVAPI SKF_UnlockDev (DEVHANDLE hDev) 功能描述 释放对设备的独占使用权。 参数 hDev [IN] 连接设备时返回的设备句柄 返回值 SAR_OK表示成功，其它表示失败。
返回其他错误码：
SAR_UNKNOWNERR发生未知错误； SAR_INVALIDHANDLEERR 句柄无效。
7.2 访问控制
本规范提供的访问控制主要完成设备认证，修改设备认证密钥、校验PIN、修改PIN、解锁PIN和清除安全状态操作。访问控制系列函数如表17所示：
表17 函数名称 SKF_ChangeDevAuthKey SKF_DevAuth SKF_ChangePIN SKF_GetPINInfo SKF_VerifyPIN SKF_UnblockPIN SKF_ClearSecueState 18
功能 修改设备认证密钥 设备认证 修改PIN 获得PIN码信息 校验PIN 解锁PIN 清除应用安全状态 备注 GBXX/T ××××-2009
7.2.1 修改设备认证密钥
函数原型 ULONG DEVAPI SKF_ChangeDevAuthKey (DEVHANDLE hDev, BYTE *pbKeyValue， ULONG
ulKeyLen)
功能描述 更改设备认证密钥。 参数 hDev [IN] 连接时返回的设备句柄
pbKeyValue [IN] 密钥值 ulKeyLen [IN] 密钥长度
返回值 SAR_OK表示成功，其它表示失败。
可能的错误值：
SAR_MEMORYERR 发生内存错误； SAR_UNKNOWNERR 发生未知错误； SAR_INVALIDPARAMETER 参数错误； SAR_INVALIDHANDLE句柄无效。
备注 权限要求：设备认证成功后才能使用。 7.2.2 设备认证
函数原型 ULONG DEVAPI SKF_DevAuth (DEVHANDLE hDev, BYTE *pbAuthData，ULONG ulLen) 功能描述 设备认证是设备对应用程序的认证。认证过程参见8.2.3。 参数 hDev [IN] 连接时返回的设备句柄
pbAuthData [IN] 认证数据 ulLen [IN] 认证数据的长度
返回值 SAR_OK表示成功，其它表示失败。
可能的错误值：
SAR_MEMORYERR 发生内存错误； SAR_UNKNOWNERR 发生未知错误； SAR_MEMORYERR 发生内存错误；
SAR_NOTINITIALIZEERR 设备未初始化。
7.2.3 修改PIN
函数原型 ULONG DEVAPI SKF_ChangePIN (HAPPLICATION hApplication, ULONG ulPINType,
LPSTR szOldPin, LPSTR szNewPin, ULONG *pulRetryCount)
功能描述 调用该函数可以修改Administrator PIN和User PIN的值。
如果原PIN码错误导致验证失败，该函数会返回相应PIN码的剩余重试次数，当剩余次数为0时，表示PIN已经被锁死。
参数 hApplication [IN] 应用句柄
ulPINType [IN] PIN类型，可为ADMIN_TYPE或USER_TYPE。 szOldPin [IN] 原PIN值 szNewPin [IN] 新PIN值
pulRetryCount [OUT] 出错后重试次数
返回值 SAR_OK表示成功，其它表示失败。
可能的错误值：
SAR_MEMORYERR 发生内存错误； SAR_UNKNOWNERR 发生未知错误； SAR_PIN_INCORRECT PIN错误； SAR_PIN_INVALID PIN无效；
SAR_PIN_LEN_RANGE PIN长度错误； SAR_PIN_LOCKED PIN锁死；
SAR_INVALIDHANDLEERR 句柄无效。
19