国密SKF接口函数介绍之二：访问控制函数

概述

        访问控制主要完成设备认证、PIN码管理和安全状态管理等操作。访问控制系列函数如下表所示：

函数名称	功能
SKF_ChangeDevAuthKey	修改设备认证密钥
SKF_DevAuth	设备认证
SKF_ChangePIN	修改PIN
SKF_GetPINInfo	获得PIN码信息
SKF_VerifyPIN	校验PIN
SKF_UnblockPIN	解锁PIN
SKF_ClearSecueState	清除应用安全状态

1、修改设备认证密钥

函数原型：ULONG DEVAPI SKF_ChangeDevAuthKey (DEVHANDLE hDev, BYTE *pbKeyValue， ULONG ulKeyLen)
功能描述：更改设备认证密钥。
参        数：hDev：[IN] 连接时返回的设备句柄。
                    pbKeyValue：[IN] 密钥值。
                    ulKeyLen：[IN] 密钥长度。
返  回  值：SAR_OK：成功；其他：错误码。
备        注：权限要求：设备认证成功后才能使用。
2、设备认证
函数原型：ULONG DEVAPI SKF_DevAuth (DEVHANDLE hDev, BYTE *pbAuthData，ULONG ulLen)
功能描述：设备认证是设备对应用程序的认证。认证过程参见8.2.3。
参        数：hDev：[IN] 连接时返回的设备句柄。
                    pbAuthData：[IN] 认证数据。
                    ulLen：[IN] 认证数据的长度。
返  回  值：SAR_OK：成功；其他：错误码。
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：成功；其他：错误码。
4、获取PIN信息
函数原型：ULONG DEVAPI SKF_GetPINInfo(HAPPLICATION hApplication, ULONG  ulPINType, ULONG *pulMaxRetryCount, ULONG *pulRemainRetryCount, BOOL *pbDefaultPin)
功能描述：获取PIN码信息，包括最大重试次数、当前剩余重试次数，以及当前PIN码是否为出厂默认PIN码。
参        数：hApplication：[IN] 应用句柄。
                    ulPINType：[IN] PIN类型。
                    pulMaxRetryCount：[OUT] 最大重试次数。
                    pulRemainRetryCount：[OUT] 当前剩余重试次数，当为0时表示已锁死。
                    pbDefaultPin：[OUT] 是否为出厂默认PIN码。
返  回  值：SAR_OK：成功；其他：错误码。
5、校验PIN 
函数原型：ULONG DEVAPI SKF_VerifyPIN (HAPPLICATION hApplication, ULONG  ulPINType, LPSTR szPIN, ULONG *pulRetryCount)
功能描述：校验PIN码。校验成功后，会获得相应的权限，如果PIN码错误，会返回PIN码的重试次数，当重试次数为0时表示PIN码已经锁死。
参        数：hApplication：[IN] 应用句柄。
                    ulPINType：[IN] PIN类型。
                    szPIN：[IN] PIN值。
                    pulRetryCount：[OUT] 出错后返回的重试次数。
返  回  值：SAR_OK：成功；其他：错误码。
6、解锁PIN 
函数原型：ULONG DEVAPI SKF_UnblockPIN (HAPPLICATION hApplication, LPSTR szAdminPIN, LPSTR szNewUserPIN,  ULONG *pulRetryCount)
功能描述：当用户的PIN码锁死后，通过调用该函数来解锁用户PIN码。解锁后，用户PIN码被设置成新值，用户PIN码的重试次数也恢复到原值。
参        数：hApplication：[IN] 应用句柄。
                    szAdminPIN：[IN] 管理员PIN码。
                    szNewUserPIN：[IN] 新的用户PIN码。
                    pulRetryCount：[OUT] 管理员PIN码错误时，返回剩余重试次数。
返  回  值：SAR_OK：成功；其他：错误码。
备        注：验证完管理员PIN才能够解锁用户PIN码，如果输入的Administrator PIN不正确或者已经锁死，会调用失败，并返回Administrator PIN的重试次数。
7、清除应用安全状态
函数原型：ULONG DEVAPI SKF_ClearSecureState (HAPPLICATION hApplication)
功能描述：清除应用当前的安全状态。
参        数：hApplication：[IN] 应用句柄。
返  回  值：SAR_OK：成功；其他：错误码。