信息安全技术智能密码钥匙应用接口规范(GB-T 35291-2017).pdf

《信息安全技术智能密码钥匙应用接口规范(GB-T 35291-2017).pdf》由会员分享，可在线阅读，更多相关《信息安全技术智能密码钥匙应用接口规范(GB-T 35291-2017).pdf（50页珍藏版）》请在得力文库 - 分享文档赚钱的网站上搜索。

1、ICS35.040.L 80GB/T XXXXXXXX信息安全技术 智能密码钥匙应用接口规范Information security technology-cryptography token application interfacespecification（报批稿）本稿完成日期：2016 年 12 月XXXX-XX-XX 发布XXXX-XX-XX 实施中中 华华 人人 民民 共共 和和 国国 国国 家家 标标 准准GB/T XXXX-XXXXI目次前言.II引言.III1 范围.12 规范性引用文件.13 术语和定义.14 缩略语.25 结构模型.25.1 层次关系.25.2 设备的应用

2、结构.26 数据类型定义.36.1 算法标识.36.2 基本数据类型.36.3 常量定义.46.4 复合数据类型.47 接口函数.107.1 设备管理.107.2 访问控制.137.3 应用管理.157.4 文件管理.167.5 容器管理.187.6 密码服务.218 设备的安全要求.418.1 设备使用阶段.418.2 权限管理.418.3 密钥安全要求.418.4 设备抗攻击要求.42附录 A（规范性附录）错误代码定义和说明.43GB/T XXXX-XXXXII前言本标准依据 GB/T1.1-2009 给出的规则起草。请注意本标准的某些内容可能涉及专利。本标准的发布机构不承担识别这些专利的

3、责任。本标准由国家密码管理局提出。本标准由全国信息安全标准化委员会（SAC/TC260）归口。本标准起草单位：北京海泰方圆科技股份有限公司、北京握奇智能科技有限公司、北京大明五洲科技有限公司、恒宝股份有限公司、深圳市明华澳汉科技股份有限公司、武汉天喻信息产业股份有限公司、北京飞天诚信科技股份有限公司、华翔腾数码科技有限公司。本标准起草人：刘平、郭宝安、石玉平、柳增寿、胡俊义、管延军、项莉、雷继业、胡鹏、赵再兴、段晓毅、刘玉峰、刘伟丰、陈吉、何永福、李高锋、黄东杰、王建承、汪雪林、赵李明、蒋红宇、王烨。本标准凡涉及密码算法相关内容，按照国家有关法规实施。GB/T XXXX-XXXXIII引言本标

4、准的目标是为公钥密码基础设施应用体系框架下的智能密码钥匙设备制定统一的应用接口标准，通过该接口调用智能密码钥匙，向上层提供基础密码服务。为该类密码设备的开发、使用及检测提供标准依据和指导，有利于提高该类密码设备的产品化、标准化和系列化水平。本标准未包含标识算法 SM9 相关的应用接口。GB/T XXXX-XXXX1信息安全技术 智能密码钥匙应用接口规范1范围本标准规定了基于 PKI 密码体制的智能密码钥匙应用接口，描述了密码相关应用接口的函数、数据类型、参数的定义和设备的安全要求。本标准适用于智能密码钥匙产品的研制、使用和检测。2规范性引用文件下列文件对于本标准的应用是必不可少的。凡是注日期的

5、引用文件，仅所注日期的版本适用于本文件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。GB/T AAAASM2 密码算法使用规范GB/T BBBB密码应用标识规范GM/T 0022IPSec VPN 技术规范GM/T 0024SSL VPN 技术规范3术语和定义以下术语和定义适用于本文件。3.1容器 container密码设备中用于保存密钥所划分的唯一性存储空间。3.2终端设备 terminal device本标准中将智能密码钥匙统称为终端设备。3.3设备认证 device authentication智能密码钥匙对应用程序的认证。3.4设备认证密钥 device aut

6、hentication key用于设备认证的密钥。3.5设备标签 label设备的别名，可以由用户进行设定并存储于设备内部。GB/T XXXX-XXXX24缩略语下列缩略语适用于本文件。API应用编程接口（Application Programming Interface）PKI公钥基础设施（Public Key Infrastructure)PKCS#1公钥密码使用标准系列规范中的第 1 部分，定义 RSA 公开密钥算法加密和签名机制(the Public-Key Cryptography Standard Part 1)PKCS#5公钥密码使用标准系列规范中的第 5 部分，描述一种利用从口

7、令派生出来的安全密钥加密字符串的方法(the Public-Key Cryptography Standard Part 5)PIN个人身份识别码（Personal Identification Number)MAC消息鉴别码（Message Authentication Code）5结构模型5.1层次关系智能密码钥匙应用接口位于智能密码钥匙应用程序与设备驱动程序之间，如图 1 所示。智能密码钥匙应用程序智能密码钥匙应用接口智能密码钥匙设备驱动程序设备 1设备 2设备 m图 1 接口在应用层次关系中的位置5.2设备的应用结构一个设备中存在设备认证密钥和多个应用，应用之间相互独立。设备的逻辑结构

8、如图 2 所示。设备认证密钥应用 1应用 2应用 n图 2 设备逻辑结构应用由管理员 PIN、用户 PIN、文件和容器组成，可以存在多个文件和多个容器。每个应用维护各自的与管理员 PIN 和用户 PIN 相关的权限状态。一个应用的逻辑结构如图 3 所示。GB/T XXXX-XXXX3管理员 PIN用户 PIN文件 1文件 2文件 m容器 1加密公钥加密私钥签名公钥签名私钥会话密钥 1会话密钥 2会话密钥 k容器 n加密公钥加密私钥签名公钥签名私钥会话密钥 1会话密钥 2会话密钥 i图 3 应用逻辑结构图容器中存放加密密钥对、签名密钥对和会话密钥。其中加密密钥对用于保护会话密钥，签名密钥对用于数

9、字签名和验证，会话密钥用于数据加解密和 MAC 运算。容器中也可以存放与加密密钥对对应的加密数字证书和与签名密钥对对应的签名数字证书。其中，签名密钥对由内部产生，加密密钥对由外部产生并安全导入，会话密钥可由内部产生或者由外部产生并安全导入。6数据类型定义6.1算法标识本标准中使用的算法其标识定义参见 GB/T BBBB。6.2基本数据类型本标准中的字节数组均为高位字节在前（Big-Endian）方式存储和交换。基本数据类型定义如表 1 所示：表 1 基本数据类型类型名称描述定义INT8有符号 8 位整数INT16有符号 16 位整数INT32有符号 32 位整数UINT8无符号 8 位整数UI

10、NT16无符号 16 位整数UINT32无符号 32 位整数BOOL布尔类型，取值为 TRUE 或 FALSEBYTE字节类型，无符号 8 位整数typedef UINT8 BYTECHAR字符类型，无符号 8 位整数typedef UINT8 CHARSHORT短整数，有符号 16 位typedef INT16 SHORTUSHORT无符号 16 位整数typedef UINT16 USHORTGB/T XXXX-XXXX4LONG长整数，有符号 32 位整数typedef INT32 LONGULONG长整数，无符号 32 位整数typedef UINT32 ULONGUINT无符号 32

11、 位整数typedef UINT32 UINTWORD字类型，无符号 16 位整数typedef UINT16 WORDDWORD双字类型，无符号 32 位整数typedef UINT32 DWORDFLAGS标志类型，无符号 32 位整数typedef UINT32 FLAGSLPSTR8 位字符串指针，按照 UTF8 格式存储及交换typedef CHAR*LPSTRHANDLE句柄，指向任意数据对象的起始地址typedefvoid*HANDLEDEVHANDLE设备句柄typedef HANDLE DEVHANDLEHAPPLICATION应用句柄typedef HANDLE HAPPL

12、ICATIONHCONTAINER容器句柄typedef HANDLE HCONTAINER6.3常量定义数据常量标识定义了在规范中用到的常量的取值。数据常量标识的定义如表 2 所示。表 2 常量定义常量名取值描述TRUE0 x00000001布尔值为真FALSE0 x00000000布尔值为假DEVAPI_stdcall_stdcall 函数调用方式ADMIN_TYPE0管理员 PIN 类型USER_TYPE1用户 PIN 类型6.4复合数据类型6.4.1版本a)类型定义typedef struct Struct_VersionBYTE major;BYTE minor;VERSION;b)

13、数据项描述参见表 3：表 3 版本定义数 据项类型意义备注majorBYTE主版本号主版本号和次版本号以“.”分隔，例如 Version 1.0，主版本号为 1，次版本号为 0；Version 2.10，主版本号为 2，次版本号为 10。minorBYTE次版本号6.4.2设备信息a)类型定义GB/T XXXX-XXXX5typedef struct Struct_DEVINFOVERSIONVersion;CHARManufacturer64;CHARIssuer64;CHARLabel32;CHARSerialNumber32;VERSIONHWVersion;VERSIONFirmwar

14、eVersion;ULONGAlgSymCap;ULONGAlgAsymCap;ULONGAlgHashCap;ULONGDevAuthAlgId;ULONGTotalSpace;ULONGFreeSpace;ULONGMaxECCBufferSize;ULONGMaxBufferSize;BYTEReserved64;DEVINFO_SKF,*PDEVINFO_SKF;b)数据项描述参见表 4：表 4 设备信息描述数据项类型意义备注VersionVERSION版本号数据结构版本号，本结构的版本号为 1.0ManufacturerCHAR 数组设备厂商信息以0为结束符的 ASCII 字符串Is

15、suerCHAR 数组发行厂商信息以0为结束符的 ASCII 字符串LabelCHAR 数组设备标签以0为结束符的 ASCII 字符串SerialNumberCHAR 数组序列号以0为结束符的 ASCII 字符串HWVersionVERSION设备硬件版本FirmwareVersionVERSION设备本身固件版本AlgSymCapULONG分组密码算法标识AlgAsymCapULONG非对称密码算法标识AlgHashCapULONG密码杂凑算法标识DevAuthAlgIdULONG设备认证使用的分组密码算法标识TotalSpaceULONG设备总空间大小FreeSpaceULONG用户可用空

16、间大小MaxECCBufferSizeULONG能够处理的 ECC 加密数据大小MaxBufferSizeULONG能够处理的分组运算和杂凑运算的数据大小ReservedBYTE保留扩展6.4.3RSA 公钥数据结构a)类型定义typedef struct Struct_RSAPUBLICKEYBLOBGB/T XXXX-XXXX6ULONG AlgID;ULONG BitLen;BYTEModulusMAX_RSA_MODULUS_LEN;BYTEPublicExponentMAX_RSA_EXPONENT_LEN;RSAPUBLICKEYBLOB,*PRSAPUBLICKEYBLOB;MA

17、X_RSA_MODULUS_LEN 为算法模数的最大长度；MAX_RSA_EXPONENT_LEN 为算法指数的最大长度。b)数据项描述参见表 5：表 5 RSA 公钥数据结构数据项类型意义备注AlgIDULONG算法标识号BitLenULONG模数的实际位长度必须是 8 的倍数ModulusBYTE 数组模数 n=p*q实际长度为 BitLen/8 字节#define MAX_RSA_MODULUS_LEN 256#define MAX_RSA_EXPONENT_LEN 4PublicExponentBYTE 数组公开密钥 e一般为 000100016.4.4RSA 私钥数据结构a)类型定义

18、typedef struct Struct_RSAPRIVATEKEYBLOBULONG AlgID;ULONG BitLen;BYTEModulusMAX_RSA_MODULUS_LEN;BYTEPublicExponentMAX_RSA_EXPONENT_LEN;BYTEPrivateExponentMAX_RSA_MODULUS_LEN;BYTEPrime1MAX_RSA_MODULUS_LEN/2;BYTEPrime2MAX_RSA_MODULUS_LEN/2;BYTEPrime1ExponentMAX_RSA_MODULUS_LEN/2;BYTEPrime2ExponentMAX_R

19、SA_MODULUS_LEN/2;BYTECoefficientMAX_RSA_MODULUS_LEN/2;RSAPRIVATEKEYBLOB,*PRSAPRIVATEKEYBLOB;MAX_RSA_MODULUS_LEN 为 RSA 算法模数的最大长度；b)数据项描述参见表 6：表 6 RSA 私钥数据结构数据项类型意义备注AlgIDULONG算法标识号BitLenULONG模数的实际位长度必须是 8 的倍数ModulusBYTE 数组模数 n=p*q实际长度为 BitLen/8 字节PublicExponentBYTE 数组公开密钥 e一般为 00010001PrivateExponent

20、BYTE 数组私有密钥 d实际长度为 BitLen/8 字节Prime1BYTE 数组素数 p实际长度为 BitLen/16 字节Prime2BYTE 数组素数 q实际长度为 BitLen/16 字节Prime1ExponentBYTE 数组d mod(p-1)的值实际长度为 BitLen/16 字节GB/T XXXX-XXXX7Prime2ExponentBYTE 数组d mod(q-1)的值实际长度为 BitLen/16 字节CoefficientBYTE 数组q 模 p 的乘法逆元实际长度为 BitLen/16 字节6.4.4ECC 公钥数据结构a)类型定义typedef struct

21、Struct_ECCPUBLICKEYBLOBULONG BitLen;BYTEXCoordinateECC_MAX_XCOORDINATE_BITS_LEN/8;BYTEYCoordinateECC_MAX_YCOORDINATE_BITS_LEN/8;ECCPUBLICKEYBLOB,*PECCPUBLICKEYBLOB;ECC_MAX_XCOORDINATE_LEN 为 ECC 算法 X 坐标的最大长度；ECC_MAX_YCOORDINATE_LEN 为 ECC 算法 Y 坐标的最大长度。b)数据项描述参见表 7：表 7 ECC 公钥数据结构数据项类型意义备注BitLenULONG模数的

22、实际位长度必须是 8 的倍数XCoordinateBYTE 数组曲线上点的 X坐标有限域上的整数#define ECC_MAX_XCOORDINATE_BITS_LEN 512YCoordinateBYTE 数组曲线上点的 Y坐标有限域上的整数#define ECC_MAX_YCOORDINATE_BITS_LEN 5126.4.5ECC 私钥数据结构a)类型定义typedef struct Struct_ECCPRIVATEKEYBLOBULONG BitLen;BYTEPrivateKeyECC_MAX_MODULUS_BITS_LEN/8;ECCPRIVATEKEYBLOB,*PECCP

23、RIVATEKEYBLOB;ECC_MAX_MODULUS_BITS_LEN 为 ECC 算法模数的最大长度。b)数据项描述参见表 8：表 8 ECC 私钥数据结构数据项类型意义备注BitLenULONG模数的实际位长度必须是 8 的倍数PrivateKeyBYTE 数组私有密钥有限域上的整数#define ECC_MAX_MODULUS_BITS_LEN 5126.4.6ECC 密文数据结构a)类型定义typedef struct Struct_ECCCIPHERBLOBBYTEXCoordinateECC_MAX_XCOORDINATE_BITS_LEN/8;BYTEYCoordinate

24、ECC_MAX_XCOORDINATE_BITS_LEN/8;BYTEHASH32;ULONG CipherLen;GB/T XXXX-XXXX8BYTECipher1;ECCCIPHERBLOB,*PECCCIPHERBLOB;b)数据项描述参见表 9：表 9 ECC 密文数据结构数据项类型意义备注XCoordinateBYTE 数组与 y 组成椭圆曲线上的点（x，y）YCoordinateBYTE 数组与 x 组成椭圆曲线上的点（x，y）HASHBYTE 数组明文的杂凑值CipherLenULONG密文数据长度CipherBYTE 数组密文数据实际长度为 CipherLen6.4.7ECC

25、 签名数据结构a)类型定义typedef struct Struct_ECCSIGNATUREBLOBBYTE rECC_MAX_XCOORDINATE_BITS_LEN/8;BYTE sECC_MAX_XCOORDINATE_BITS_LEN/8;ECCSIGNATUREBLOB,*PECCSIGNATUREBLOB;ECC_MAX_MODULUS_BITS_LEN 为 ECC 算法模数的最大长度；b)数据项描述参见表 10：表 10 ECC 签名数据结构数据项类型意义备注rBYTE 数组签名结果的 r 部分sBYTE 数组签名结果的 s 部分6.4.8分组密码参数a)类型定义typedef

26、 struct Struct_BLOCKCIPHERPARAMBYTEIVMAX_IV_LEN;ULONG IVLen;ULONG PaddingType;ULONG FeedBitLen;BLOCKCIPHERPARAM,*PBLOCKCIPHERPARAM;b)数据项描述参见表 11：表 11 分组密码参数数据项类型意义备注IVBYTE 数组初始向量，MAX_IV_LEN 为初始化向量的最大长度#define MAX_IV_LEN 32IVLenULONG初始向量实际长度（按字节计算）GB/T XXXX-XXXX9PaddingTypeULONG填充方式，0 表示不填充，1 表示按照 PK

27、CS#5方式进行填充FeedBitLenULONG反馈值的位长度（按位计算）只针对 OFB、CFB 模式6.4.9ECC 加密密钥对保护结构a)类型定义typedef struct SKF_ENVELOPEDKEYBLOBULONG Version;/当前版本为 1ULONG ulSymmAlgID;/对称算法标识，限定 ECB 模式ULONG ulBits;/加密密钥对的密钥位长度BYTEcbEncryptedPriKey64;/加密密钥对私钥的密文ECCPUBLICKEYBLOB PubKey;/加密密钥对的公钥ECCCIPHERBLOB ECCCipherBlob;/用保护公钥加密的对称

28、密钥密文。ENVELOPEDKEYBLOB,*PENVELOPEDKEYBLOB;私钥密文结构中 64 字节，有效密文分组从 0 偏移量字节开始，顺序解密密文分组后将明文连接得到加密密钥对的私钥的明文。数据项描述参见表 12：表 12 加密密钥对保护结构参数数据项类型意义备注VersionULONG版本号，本版本为 1ulSymmAlgIDULONG对称算法标识必须为 ECB 模式ulBitsULONG加密密钥对的密钥位长cbEncryptedPrivKeyBYTE 数组对称算法加密的加密私钥,加密私钥的原文为ECCPRIVATEKEYBLOB 结构中的PrivateKey。其 有 效 长 度

29、 为 原 文 的（ulBits+7）/8PubKeyECCPUBLICKEYBLOB加密密钥对的公钥ECCCipherBlobECCCIPHERBLOB用保护公钥加密过的对称密钥密文6.4.10文件属性a)类型定义typedef struct Struct_FILEATTRIBUTECHARFileName32;ULONG FileSize;ULONG ReadRights;ULONG WriteRights;FILEATTRIBUTE,*PFILEATTRIBUTE;b)数据项描述参见表 13：表 13 文件属性数据项类型意义备注GB/T XXXX-XXXX10FileNameCHAR 数组

30、文件名以0结束的 ASCII 字符串，最大长度为32FileSizeULONG文件大小创建文件时定义的文件大小ReadRightsULONG读取权限读取文件需要的权限WriteRightsULONG写入权限写入文件需要的权限6.4.11权限类型权限类型的定义参见表 14：表 14 权限类型权限类型值说明SECURE_NEVER_ACCOUNT0 x00000000不允许SECURE_ADM_ACCOUNT0 x00000001管理员权限SECURE_USER_ACCOUNT0 x00000010用户权限SECURE_ANYONE_ACCOUNT0 x000000FF任何人6.4.12设备状态设

31、备状态的定义参见表 15：表 15 设备状态设备状态值说明DEV_ABSENT_STATE0 x00000000设备不存在DEV_PRESENT_STATE0 x00000001设备存在DEV_UNKNOW_STATE0 x00000002设备状态未知7接口函数7.1设备管理7.1.1概述设备管理主要完成设备的插拔事件处理、枚举设备、连接设备、断开连接、获取设备状态、设置设备标签、获取设备信息、锁定设备、解锁设备和设备命令传输等操作。设备管理系列函数如表16 所示：表 16 设备管理系列函数函数名称功能SKF_WaitForDevEvent等待设备插拔事件SKF_CancelWaitForDe

32、vEvent取消等待设备插拔事件SKF_EnumDev枚举设备SKF_ConnectDev连接设备SKF_DisconnectDev断开连接SKF_GetDevState获取设备状态SKF_SetLabel设置设备标签SKF_GetDevInfo获取设备信息GB/T XXXX-XXXX11SKF_LockDev锁定设备SKF_UnlockDev解锁设备SKF_Transmit设备命令传输7.1.2等待设备插拔事件原型ULONG DEVAPI SKF_WaitForDevEvent(LPSTR szDevName,ULONG*pulDevNameLen,ULONG*pulEvent)功能描述该函

33、数等待设备插入或者拔除事件。szDevName 返回发生事件的设备名称。参数szDevNameOUT 发生事件的设备名称。pulDevNameLenIN/OUT 输入/输出参数，当输入时表示缓冲区长度，输出时表示设备名称的有效长度,长度包含字符串结束符。pulEventOUT事件类型。1 表示插入，2 表示拔出。返回值SAR_OK：成功。其他：错误码。备注本函数为阻塞函数。7.1.3取消等待设备插拔事件原型ULONG DEVAPI SKF_CancelWaitForDevEvent()功能描述该函数取消等待设备插入或者拔除事件。参数返回值SAR_OK：成功。其他：错误码。备注使本进程正在执行的

34、 SKF_WaitForDevEvent 函数立即返回。7.1.4枚举设备原型ULONG DEVAPI SKF_EnumDev(BOOL bPresent,LPSTR szNameList,ULONG*pulSize)功能描述获得当前系统中的设备列表。参数bPresentIN 为 TRUE 表示取当前设备状态为存在的设备列表。为 FALSE 表示取当前驱动支持的设备列表。szNameListOUT 设备名称列表。如果该参数为 NULL，将由 pulSize 返回所需要的内存空间大小。每个设备的名称以单个0结束，以双0表示列表的结束。pulSizeIN，OUT 输入时表示设备名称列表的缓冲区长度

35、，输出时表示szNameList 所占用的空间大小。返回值SAR_OK：成功。其他：错误码。7.1.5连接设备原型ULONG DEVAPI SKF_ConnectDev(LPSTR szName,DEVHANDLE*phDev)功能描述通过设备名称连接设备，返回设备的句柄。参数szNameIN 设备名称。phDevOUT 返回设备操作句柄。返回值SAR_OK：成功。其他：错误码。7.1.6断开连接GB/T XXXX-XXXX12原型ULONG DEVAPI SKF_DisConnectDev(DEVHANDLE hDev)功能描述断开一个已经连接的设备，并释放句柄。参数hDevIN 连接设备时

36、返回的设备句柄。返回值SAR_OK：成功。其他：错误码。备注如果该设备已被锁定，函数应首先解锁该设备。断开连接操作并不影响设备的权限状态。7.1.7获取设备状态原型ULONG DEVAPI SKF_GetDevState(LPSTR szDevName,ULONG*pulDevState)功能描述获取设备是否存在的状态。参数szDevNameIN 设备名称。pulDevStateOUT 返回设备状态。返回值SAR_OK：成功。其他：错误码。7.1.8设置设备标签原型ULONG DEVAPI SKF_SetLabel(DEVHANDLE hDev,LPSTR szLabel)功能描述设置设备标签

37、。参数hDevIN 连接设备时返回的设备句柄。szLabelIN 设备标签字符串。该字符串应小于 32 字节。返回值SAR_OK：成功。其他：错误码。7.1.9获取设备信息原型ULONG DEVAPI SKF_GetDevInfo(DEVHANDLE hDev,DEVINFO*pDevInfo)功能描述获取设备的一些特征信息，包括设备标签、厂商信息、支持的算法等。参数hDevIN 连接设备时返回的设备句柄。pDevInfoOUT 返回设备信息。返回值SAR_OK：成功。其他：错误码。7.1.10锁定设备原型ULONG DEVAPI SKF_LockDev(DEVHANDLE hDev,ULON

38、G ulTimeOut)功能描述获得设备的独占使用权。参数hDevIN 连接设备时返回的设备句柄。ulTimeOutIN 超时时间，单位为毫秒。如果为 0 xFFFFFFFF 表示无限等待。返回值SAR_OK：成功。其他：错误码。7.1.11解锁设备原型ULONG DEVAPI SKF_UnlockDev(DEVHANDLE hDev)功能描述释放对设备的独占使用权。参数hDevIN 连接设备时返回的设备句柄。返回值SAR_OK：成功。其他：错误码。7.1.12设备命令传输GB/T XXXX-XXXX13原型ULONGDEVAPISKF_Transmit(DEVHANDLEhDev,BYTE*

39、pbCommand,ULONGulCommandLen,BYTE*pbData,ULONG*pulDataLen)功能描述将命令直接发送给设备，并返回结果。参数hDevIN 设备句柄。pbCommandIN 设备命令。ulCommandLenIN 命令长度。pbDataOUT 返回结果数据。pulDataLenIN，OUT 输入时表示结果数据缓冲区长度，输出时表示结果数据实际长度。返回值SAR_OK：成功。其他：错误码。备注本函数仅用于设备检测。7.2访问控制7.2.1概述访问控制主要完成设备认证、PIN 码管理和安全状态管理等操作。访问控制系列函数如表所 17：表 17 访问控制系列函数函数

40、名称功能SKF_ChangeDevAuthKey修改设备认证密钥SKF_DevAuth设备认证SKF_ChangePIN修改 PINSKF_GetPINInfo获得 PIN 码信息SKF_VerifyPIN校验 PINSKF_UnblockPIN解锁 PINSKF_ClearSecueState清除应用安全状态7.2.2修改设备认证密钥原型ULONG DEVAPI SKF_ChangeDevAuthKey(DEVHANDLE hDev,BYTE*pbKeyValue，ULONGulKeyLen)功能描述更改设备认证密钥。参数hDevIN 连接时返回的设备句柄。pbKeyValueIN 密钥值。

41、ulKeyLenIN 密钥长度。返回值SAR_OK：成功。其他：错误码。备注权限要求：设备认证成功后才能使用。7.2.3设备认证原型ULONG DEVAPI SKF_DevAuth(DEVHANDLE hDev,BYTE*pbAuthData，ULONG ulLen)功能描述设备认证是设备对应用程序的认证。认证过程参见 8.2.3。参数hDevIN 连接时返回的设备句柄。pbAuthDataIN 认证数据。ulLenIN 认证数据的长度。返回值SAR_OK：成功。GB/T XXXX-XXXX14其他：错误码。7.2.4修改 PIN原型ULONG DEVAPI SKF_ChangePIN(HAP

42、PLICATION hApplication,ULONG ulPINType,LPSTRszOldPin,LPSTR szNewPin,ULONG*pulRetryCount)功能描述调用该函数可以修改 Administrator PIN 和 User PIN 的值。如果原 PIN 码错误导致验证失败，该函数会返回相应 PIN 码的剩余重试次数，当剩余次数为 0 时，表示 PIN 已经被锁死。参数hApplicationIN 应用句柄。ulPINTypeIN PIN 类型，可为 ADMIN_TYPE 或 USER_TYPE。szOldPinIN 原 PIN 值。szNewPinIN 新 PIN

43、 值。pulRetryCountOUT 出错后重试次数。返回值SAR_OK：成功。其他：错误码。7.2.5获取 PIN 信息原型ULONG DEVAPI SKF_GetPINInfo(HAPPLICATION hApplication,ULONGulPINType,ULONG*pulMaxRetryCount,ULONG*pulRemainRetryCount,BOOL*pbDefaultPin)功能描述获取 PIN 码信息，包括最大重试次数、当前剩余重试次数，以及当前 PIN 码是否为出厂默认 PIN 码。参数hApplicationIN 应用句柄。ulPINTypeIN PIN 类型。pu

44、lMaxRetryCountOUT 最大重试次数。pulRemainRetryCountOUT 当前剩余重试次数，当为 0 时表示已锁死。pbDefaultPinOUT 是否为出厂默认 PIN 码。返回值SAR_OK：成功。其他：错误码。7.2.6校验 PIN原型ULONG DEVAPI SKF_VerifyPIN(HAPPLICATION hApplication,ULONGulPINType,LPSTRszPIN,ULONG*pulRetryCount)功能描述校验 PIN 码。校验成功后，会获得相应的权限，如果 PIN 码错误，会返回 PIN 码的重试次数，当重试次数为 0 时表示 PI

45、N 码已经锁死。参数hApplicationIN 应用句柄。ulPINTypeIN PIN 类型。szPININ PIN 值。pulRetryCountOUT 出错后返回的重试次数。返回值SAR_OK：成功。其他：错误码。7.2.7解锁 PIN原型ULONG DEVAPI SKF_UnblockPIN(HAPPLICATION hApplication,LPSTR szAdminPIN,LPSTRszNewUserPIN,ULONG*pulRetryCount)功能描述当用户的 PIN 码锁死后，通过调用该函数来解锁用户 PIN 码。解锁后，用户 PIN 码被设置成新值，用户 PIN 码的重试

46、次数也恢复到原值。GB/T XXXX-XXXX15参数hApplicationIN 应用句柄。szAdminPININ 管理员 PIN 码。szNewUserPININ 新的用户 PIN 码。pulRetryCountOUT 管理员 PIN 码错误时，返回剩余重试次数。返回值SAR_OK：成功。其他：错误码。备注验证完管理员 PIN 才能够解锁用户 PIN 码，如果输入的 Administrator PIN 不正确或者已经锁死，会调用失败，并返回 Administrator PIN 的重试次数。7.2.8清除应用安全状态原型ULONG DEVAPI SKF_ClearSecureState(H

47、APPLICATION hApplication)功能描述清除应用当前的安全状态。参数hApplicationIN 应用句柄。返回值SAR_OK：成功。其他：错误码。7.3应用管理7.3.1概述应用管理主要完成应用的创建、枚举、删除、打开、关闭等操作。应用管理系列函数如表 18 所示：表 18 应用管理系列函数函数名称功能SKF_CreateApplication创建应用SKF_EnumApplication枚举应用SKF_DeleteApplication删除应用SKF_OpenApplication打开应用SKF_CloseApplication关闭应用7.3.2创建应用原型ULONG D

48、EVAPI SKF_CreateApplication(DEVHANDLE hDev,LPSTR szAppName,LPSTRszAdminPin,DWORDdwAdminPinRetryCount,LPSTRszUserPin,DWORDdwUserPinRetryCount,DWORD dwCreateFileRights,HAPPLICATION*phApplication)功能描述创建一个应用。参数hDevIN 连接设备时返回的设备句柄。szAppNameIN 应用名称。szAdminPinIN 管理员 PIN。dwAdminPinRetryCountIN 管理员 PIN 最大重试次

49、数。szUserPinIN 用户 PIN。dwUserPinRetryCountIN 用户 PIN 最大重试次数。dwCreateFileRightsIN 在该应用下创建文件和容器的权限，参见 6.4.9 权限类型。为各种权限的或值。phApplicationOUT 应用的句柄。返回值SAR_OK：成功。其他：错误码。GB/T XXXX-XXXX16备注权限要求：需要设备权限。7.3.3枚举应用原型ULONGDEVAPISKF_EnumApplication(DEVHANDLEhDev,LPSTRszAppName,ULONG*pulSize)功能描述枚举设备中存在的所有应用。参数hDevIN

50、 连接设备时返回的设备句柄。szAppNameOUT 返回应用名称列表,如果该参数为空，将由 pulSize 返回所需要的内存空间大小。每个应用的名称以单个0结束，以双0表示列表的结束。pulSizeIN，OUT 输入时表示应用名称的缓冲区长度，输出时返回szAppName 所占用的空间大小。返回值SAR_OK：成功。其他：错误码。7.3.4删除应用原型ULONG DEVAPI SKF_DeleteApplication(DEVHANDLE hDev,LPSTR szAppName)功能描述删除指定的应用。参数hDevIN 连接设备时返回的设备句柄。szAppNameIN 应用名称。返回值SA