[PDF] GM/T 0016-2023 - 英文版

标准搜索结果: 'GM/T 0016-2023'
标准号码美元购买PDF工期标准名称(英文版)
GM/T 0016-2023 1785 GM/T 0016-2023 9秒内 智能密码钥匙密码应用接口规范
   
基本信息
标准编号 GM/T 0016-2023 (GM/T0016-2023)
中文名称 智能密码钥匙密码应用接口规范
英文名称 Smart token cryptography application interface specification
行业 Chinese Industry Standard (推荐)
中标分类 L80
字数估计 81,895
发布日期 2023-12-04
实施日期 2024-06-01
发布机构 国家密码管理局

GM/T 0016-2023: 智能密码钥匙密码应用接口规范 中华人民共和国密码行业标准 ICS 35.030CCS L 80 智能密码钥匙密码应用接口规范 2023⁃12⁃04 发布 2024⁃06⁃01 实施 国家密码管理局 发 布 代替 GM/T 0016-2012 目次 前言·····Ⅲ 引言·····Ⅳ 1　范围·····1 2　规范性引用文件····1 3　术语和定义·····1 4　缩略语·····2 5　结构模型····2 5.1　层次关系····2 5.2　设备的应用结构····3 6　数据类型定义·····4 6.1　算法标识····4 6.2　基本数据类型····4 6.3　常量定义····4 6.4　复合数据类型····5 7　接口函数····12 7.1　设备管理·····12 7.2　访问控制·····15 7.3　应用管理·····18 7.4　文件管理·····20 7.5　容器管理·····22 7.6　密码服务·····25 7.7　验证调试·····40 8　接口使用要求·····43 8.1　设备使用阶段····43 8.2　权限管理·····44 8.3　其他安全要求····44 附录 A （规范性）　错误代码定义····45 附录 B （规范性）　SM9 应用接口····47 附录 C （规范性）　VPN 相关接口····62 附录 D （资料性）　SM9 编程范例····71 参考文献·····75 前言 本文件按照 GB/T 1.1-2020《标准化工作导则　第 1 部分：标准化文件的结构和起草规则》的规 定起草。 本文件代替 GM/T 0016-2012《智能密码钥匙密码应用接口规范》，与 GM/T 0016-2012 相比， 除结构调整和编辑性改动外，主要技术变化如下： a） 删除了“填充方式”（见表 11，2012 年版的表 11）； b） 更改了“修改设备认证密钥”函数（见 7.2.2，2012 年版的 7.2.2）； c） 更改了“获得容器类型”（见 7.5.7，2012 年版的 7.5.7）； d） 更改了“导出公钥”（见 7.6.18，2012 年版的 7.6.17）； e） 更改了“导入会话密钥”（见 7.6.19，2012 年版的 7.6.18）； f） 更改了“安全要求”（见第 8 章，2012 年版的第 8 章）； g） 增加了 HMAC 相关接口（见 7.6.36、7.6.37、7.6.38、7.6.39）； h） 增加了验证调试类接口（见 7.7）； i） 增加了 SM9 应用接口（见附录 B）； j） 增加了 VPN 相关接口（见附录 C）； k） 增加了 SM9 编程范例（见附录 D）。 请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。 本文件由密码行业标准化技术委员会提出并归口。 本文件起草单位：北京海泰方圆科技股份有限公司、北京握奇智能科技有限公司、格尔软件股份有 限公司、无锡江南信息安全工程技术中心、北京数字认证股份有限公司、兴唐通信科技有限公司、山东 得安信息技术有限公司、北京三未信安科技发展有限公司、山东大学、北京大明五洲科技有限公司、恒 宝股份有限公司、深圳市明华澳汉科技股份有限公司、武汉天喻信息产业股份有限公司、北京飞天诚信 科技股份有限公司、华翔腾数码科技有限公司、北京鼎九信息工程研究院有限公司、北京百旺信安科技 有限公司、中电科网络安全科技股份有限公司、北京国脉信安科技有限公司、北京小雷科技有限公司。 本文件主要起草人：刘平、蒋红宇、柳增寿、张立廷、罗俊、袁峰、封维端、靳京、张渊、陈国、李勃、 郑强、李述胜、孔凡玉、王妮娜、马洪富、高志权、徐明翼、李增欣、于学东、郭宝安、石玉平、胡俊义、 管延军、项莉、雷继业、胡鹏、赵再兴、段晓毅、刘玉峰、刘伟丰、陈吉、何永福、李高锋、黄东杰、王建承、 汪雪林、赵李明、王烨。 本文件及其所代替文件的历次版本发布情况为： --2012 年首次发布版为 GM/T 0016-2012； --本次为第一次修订。 引 言 本文件的目标是为公钥密码基础设施应用体系框架下的智能密码钥匙设备制定统一的应用接口 标准。通过该接口调用智能密码钥匙，向上层提供基础密码服务。为该类密码设备的开发、使用及检 测提供标准依据和指导，有利于提高该类密码设备的产品化、标准化和系列化水平。 智能密码钥匙密码应用接口规范 1　范围 本文件规定了公钥密码体制下的智能密码钥匙应用接口标准、密码相关应用接口的函数、数据类 型、参数的定义和设备的安全要求。 本文件适用于智能密码钥匙产品的研制、使用和检测。 2　规范性引用文件 下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文 件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于 本文件。 GM/T 0006-2023　密码应用标识规范 GM/T 0017-2023　智能密码钥匙密码应用接口数据格式规范 GM/T 0027-2014　智能密码钥匙技术规范 GM/T 0028-2014　密码模块安全要求 GM/Z 4001　密码术语 PKCS#1　RSA 密码规范版本 2.1（RSA Cryptography specification version 2.1） 3　术语和定义 GM/Z 4001 界定的以及下列术语和定义适用于本文件。 3.1 容器　container 密码设备中用于保存密钥所划分的唯一性存储空间。 3.2 终端设备　terminal device 智能密码钥匙的统称。 3.3 设备认证　device authentication 智能密码钥匙对应用程序的认证。 3.4 设备认证密钥　device authentication key 用于设备认证的密钥。 3.5 设备标签　device label 终端设备的别名，可由用户进行设定并存储于设备内部。 3.6 管理员 PIN　administrator PIN 管理员的口令，为 ASCII 字符串。 3.7 用户 PIN　user PIN 用户的个人口令，为 ASCII 字符串。 3.8 应用　application 包括容器和文件的一种结构，具备独立的管理权限。 4　缩略语 下列缩略语适用于本文件。 API：应用编程接口（Application Programming Interface） ASCII：美国信息交换标准码（American Standard Code for Information Interchange） MAC：消息鉴别码（Message Authentication Code） PKI：公钥基础设施（Public Key Infrastructure） PIN：个人身份识别码（Personal Identification Number） 5　结构模型 5.1　层次关系 智能密码钥匙应用接口位于智能密码钥匙应用程序与智能密码钥匙应用接口数据格式之间，如 图 1 所示。智能密码钥匙硬件接口应符合 GM/T 0027-2014 中 6.1 的规定。 图 1　接口在应用层次关系中的位置 5.2　设备的应用结构 终端设备应具有一个设备认证密钥。终端设备应支持一个或多个应用。应用之间应相互独立。 设备的逻辑结构如图 2 所示。 图 2　设备逻辑结构 应用由管理员 PIN、用户 PIN、文件和容器组成，可存在多个文件和多个容器。应用应维护自身的 权限状态。管理员 PIN 和用户 PIN 的校验操作可改变应用权限状态。一个应用的逻辑结构如图 3 所示。 容器用于存放加密密钥对、签名密钥对和会话密钥。其中，加密密钥对用于保护会话密钥，签名密 钥对用于数字签名和验证，会话密钥用于数据加解密和 MAC 运算。容器中存放 SM2 算法的密钥对 时，与其对应的数字证书也应存放在该容器中，且签名密钥对应由内部产生，加密密钥对应由外部安全 导入；容器中存放 SM9 算法的密钥对时，其公钥由标识表示；会话密钥可由内部产生，也可由外部产生 并安全导入。 图 3　应用逻辑结构图 6　数据类型定义 6.1　算法标识 密码算法标识应符合 GM/T 0006-2023 中第 6 章的规定。 6.2　基本数据类型 字节数组应使用高位字节在前（Big⁃Endian）的方式存储和交换。基本数据类型定义见表 1。 表 1　基本数据类型 类型名称 INT8 INT16 INT32 UINT8 BOOL BYTE CHAR LONG UINT WORD FLAGS LPSTR DEVHANDLE 描述 有符号 8位整数 有符号 16位整数 有符号 32位整数 无符号 8位整数 无符号 16位整数 无符号 32位整数 布尔类型，取值为TRUE或 FALSE 字节类型，无符号 8位整数 字符类型，无符号 8位整数 长整数，有符号 32位整数 长整数，无符号 32位整数 无符号 32位整数 字类型，无符号 16位整数 双字类型，无符号 32位整数 标志类型，无符号 32位整数 8位字符串指针，按照UTF8格式存储及交换 句柄，指向任意数据对象的起始地址 设备句柄 应用句柄 容器句柄 备注 例如：typedef char INT8 例如，typedef short INT16 例如，typedef int INT32 例如，typedef unsigned char UINT8 例如，typedef unsigned short UINT16 例如，typedef unsigned int UINT32 typedef UINT8 BYTE typedef UINT8 CHAR typedef INT32 LONG typedef UINT32 ULONG typedef UINT32 UINT typedef UINT16 WORD typedef UINT32 DWORD typedef UINT32 FLAGS typedef CHAR * LPSTR typedef void * HANDLE typedef HANDLE DEVHANDLE typedef HANDLE HAPPLICATION typedef HANDLE HCONTAINER 6.3　常量定义 数据常量标识定义了在规范中用到的常量的取值。 数据常量标识的定义如表 2 所示。 表 2　常量定义 常量名 TRUE FALSE DEVAPI ADMIN_TYPE USER_TYPE 取值 0x00000001 0x00000000 _stdcall 描述 布尔值为真 布尔值为假 _stdcall函数调用方式 管理员 PIN类型 用户 PIN类型 6.4　复合数据类型 6.4.1　对齐方式 复合数据类型应采用单字节对齐方式。 6.4.2　版本 6.4.2.1　类型定义 typedef struct Struct_Version{ BYTE major; BYTE minor; }VERSION; 6.4.2.2　数据项 数据项应符合表 3 的规定。 表 3　版本定义 数据项 major minor 类型 BYTE BYTE 意义 主版本号 次版本号 备注 使用ASCII编码，取值范围为字符 0至字符 9 使用ASCII编码，取值范围为字符 0至字符 9 6.4.3　设备信息 6.4.3.1　类型定义 typedef struct Struct_DEVINFO{ VERSION Version; CHAR Manufacturer[64]; CHAR Issuer[64]; CHAR Label[32]; CHAR SerialNumber[32]; VERSION HWVersion; VERSION FirmwareVersion; ULONG AlgHashCap; ULONG DevAuthAlgId; ULONG TotalSpace; ULONG FreeSpace; ULONG MaxECCBufferSize; } DEVINFO_SKF，*PDEVINFO_SKF; 6.4.3.2　数据项 数据项应符合表 4 的规定。 表 4　设备信息描述 数据项 Version Manufacturer SerialNumber AlgAsymCap AlgHashCap FreeSpace Reserved 类型 VERSION CHAR数组 CHAR数组 CHAR数组 CHAR数组 VERSION VERSION ULONG ULONG ULONG ULONG ULONG BYTE 意义 版本号 设备厂商信息 发行厂商信息 设备标签 序列号 设备硬件版本 设备本身固件版本 分组密码算法标识 非对称密码算法标识 密码杂凑算法标识 设备认证使用的分组密码算法标识 设备总空间大小 用户可用空间大小 能够处理的 ECC加密数据大小 能够处理的分组运算和杂凑运算的 数据大小 保留扩展 备注 数据结构版本号，本结构的版本号为 2.0 以‘\0’为结束符的ASCII字符串 以‘\0’为结束符的ASCII字符串 以‘\0’为结束符的ASCII字符串 以‘\0’为结束符的ASCII字符串 6.4.4　RSA公钥数据结构 6.4.4.1　类型定义 typedef struct Struct_RSAPUBLICKEYBLOB{ BYTE Modulus[MAX_RSA_MODULUS_LEN]; BYTE PublicExponent[MAX_RSA_EXPONENT_LEN]; }RSAPUBLICKEYBLOB， *PRSAPUBLICKEYBLOB; 6.4.4.2　数据项 数据项应符合表 5 的规定。 表 5　RSA 公钥数据结构 数据项 AlgID BitLen Modulus 类型 ULONG ULONG BYTE数组 BYTE数组 意义 算法标识号 模数的实际位长度 模数 n = p * q 公开密钥 e 备注 应是 8的倍数 实际长度为 BitLen/8字节 #define MAX_RSA_MODULUS_LEN 512 #define MAX_RSA_EXPONENT_LEN 4 一般为 00010001 6.4.5　RSA私钥数据结构 6.4.5.1　类型定义 typedef struct Struct_RSAPRIVATEKEYBLOB{ BYTE Modulus[MAX_RSA_MODULUS_LEN]; BYTE PublicExponent[MAX_RSA_EXPONENT_LEN]; BYTE PrivateExponent[MAX_RSA_MODULUS_LEN]; BYTE Prime1[MAX_RSA_MODULUS_LEN/2]; BYTE Prime2[MAX_RSA_MODULUS_LEN/2]; BYTE Prime1Exponent[MAX_RSA_MODULUS_LEN/2]; BYTE Prime2Exponent[MAX_RSA_MODULUS_LEN/2]; BYTE Coefficient[MAX_RSA_MODULUS_LEN/2]; }RSAPRIVATEKEYBLOB， *PRSAPRIVATEKEYBLOB; 数据项应符合表 6 的规定。 表 6　RSA 私钥数据结构 数据项 AlgID BitLen Modulus Prime1 Prime1Exponent 类型 ULONG ULONG BYTE数组 BYTE数组 BYTE数组 BYTE数组 BYTE数组 BYTE数组 BYTE数组 BYTE数组 意义 算法标识号 模数的实际位长度 模数 n = p * q 公开密钥 e 私有密钥 d 素数 p 素数 q d mod （p-1）的值 d mod （q -1）的值 q模 p的乘法逆元 备注 应是 8的倍数 实际长度为 BitLen/8字节 一般为 00010001 实际长度为 BitLen/8字节 实际长度为 BitLen/16字节 实际长度为 BitLen/16字节 实际长度为 BitLen/16字节 实际长度为 BitLen/16字节 实际长度为 BitLen/16字节 6.4.6　ECC公钥数据结构 6.4.6.1　类型定义 typedef struct Struct_ECCPUBLICKEYBLOB{ BYTE YCoordinate[ECC_MAX_YCOORDINATE_BITS_LEN/8]； }ECCPUBLICKEYBLOB， *PECCPUBLICKEYBLOB； 6.4.6.2　数据项 数据项描述见表 7。 表 7　ECC 公钥数据结构 数据项 BitLen XCoordinate 类型 ULONG BYTE数组 BYTE数组 意义 模数的实际位长度 曲线上点的 X坐标 曲线上点的Y坐标 备注 应是 8的倍数 有限域上的整数 #define ECC_MAX_XCOORDINATE_BITS_LEN 512 有限域上的整数 #define ECC_MAX_YCOORDINATE_BITS_LEN 512 6.4.7　ECC私钥数据结构 6.4.7.1　类型定义 typedef struct Struct_ECCPRIVATEKEYBLOB{ }ECCPRIVATEKEYBLOB， *PECCPRIVATEKEYBLOB； 数据项描述见表 8。 表 8　ECC 私钥数据结构 数据项 BitLen PrivateKey 类型 ULONG BYTE数组 意义 模数的实际位长度 私有密钥 备注 应是 8的倍数 有限域上的整数 #define ECC_MAX_MODULUS_BITS_LEN 512 6.4.8　ECC密文数据结构 6.4.8.1　类型定义 typedef struct Struct_ECCCIPHERBLOB{ BYTE　 XCoordinate[ECC_MAX_XCOORDINATE_BITS_LEN/8]； BYTE　 YCoordinate[ECC_MAX_XCOORDINATE_BITS_LEN/8]； BYTE　 HASH[32]； ULONG CipherLen； BYTE　 Cipher[1]； } ECCCIPHERBLOB， *PECCCIPHERBLOB； 数据项描述见表 9。 表 9　ECC 密文数据结构 数据项 XCoordinate HASH Cipher 类型 BYTE数组 BYTE数组 BYTE数组 ULONG BYTE数组 意义 与 y组成椭圆曲线上的点（x，y） 与 x组成椭圆曲线上的点（x，y） 明文的杂凑值 密文数据长度 密文数据 备注 实际长度为 CipherLen 6.4.9　ECC签名数据结构 6.4.9.1　类型定义 typedef struct Struct_ECCSIGNATUREBLOB{ } ECCSIGNATUREBLOB， *PECCSIGNATUREBLOB; 数据项描述见表 10。 表 10　ECC 签名数据结构 数据项 类型 BYTE数组 BYTE数组 意义 签名结果的 r部分 签名结果的 s部分 备注 6.4.10　分组密码参数 6.4.10.1　类型定义 typedef struct Struct_BLOCKCIPHERPARAM{ ULONG FeedBitLen; } BLOCKCIPHERPARAM， *PBLOCKCIPHERPARAM; 数据项描述见表 11。 表 11　分组密码参数 数据项 IV IVLen FeedBitLen 类型 BYTE数组 ULONG ULONG 意义 初始向量，MAX_IV_LEN为初始化向量的最 大长度#define MAX_IV_LEN 32 初始向量实际长度（按字节计算） 反馈值的位长度（按位计算） 备注 只针对OFB、CFB模式 6.4.11　ECC加密密钥对保护结构 6.4.11.1　类型定义 typedef struct Struct_ENVELOPEDKEYBLOB{ ULONG ulBits; BYTE　 cbEncryptedPriKey[64]; ECCPUBLICKEYBLOB PubKey; ECCCIPHERBLOB ECCCipherBlob; }ENVELOPEDKEYBLOB， *PENVELOPEDKEYBLOB; 私钥密文数组中的有效密文分组应从 0 偏移量字节开始。顺序解密密文分组后将明文连接应得 到加密密钥对的私钥的明文。 6.4.11.2　数据项 数据项描述见表 12。 表 12　加密密钥对保护结构参数 数据项 Version ulSymmAlgID ECCCipherBlob 类型 ULONG ULONG ULONG BYTE数组 ECCPUBLICKEYB LOB 意义 版本号，本版本为 2 对称算法标识 加密密钥对的密钥位长 对称算法加密的加密私钥，加密私钥 的原文为 ECCPRIVATEKEYBLOB 结构中的 PrivateKey 加密密钥对的公钥 用保护公钥加密过的对称密钥密文 备注 应为 ECB模式 其有效长度为原文的（ulBits + 7）/8 6.4.12　文件属性 6.4.12.1　类型定义 typedef struct Struct_FILEATTRIBUTE{ CHAR 　FileName[32]; ULONG 　FileSize; ULONG 　ReadRights; ULONG 　WriteRights; } FILEATTRIBUTE， *PFILEATTRIBUTE; 数据项描述见表 13。 表 13　文件属性 数据项 FileName FileSize 类型 CHAR数组 ULONG ULONG ULONG 意义 文件名 文件大小 读取权限 写入权限 备注 以‘\0’结束的ASCII字符串，最大长度为 32 创建文件时定义的文件大小 读取文件应已取得的权限 写入文件应已取得的权限 6.4.13　权限类型 权限类型的定义见表 14。 表 14　权限类型 权限类型 SECURE_NEVER_ACCOUNT SECURE_ADM_ACCOUNT SECURE_USER_ACCOUNT SECURE_ANYONE_ACCOUNT 0x00000000 0x000000FF 说明 不准许 管理员权限 用户权限 任何人 6.4.14　设备状态 设备状态的定义见表 15。 表 15　设备状态 设备状态 DEV_ABSENT_STATE DEV_PRESENT_STATE DEV_UNKNOW_STATE 0x00000000 说明 设备不存在 设备存在 设备状态未知 6.4.15　错误代码 接口函数所返回的错误代码应符合附录 A 中的规定。 7　接口函数 7.1　设备管理 7.1.1　概述 设备管理主要完成设备的插拔事件处理、枚举设备、连接设备、断开连接、获取设备状态、设置设备 标签、获取设备信息、锁定设备、解锁设备的操作。设备管理系列函数见表 16。 表 16　设备管理系列函数 函数名称 SKF_WaitForDevEvent SKF_EnumDev SKF_ConnectDev SKF_DisconnectDev SKF_GetDevState SKF_SetLabel SKF_GetDevInfo SKF_LockDev SKF_UnlockDev 功能 等待设备插拔事件 取消等待设备插拔事件 枚举设备 连接设备 断开连接 获取设备状态 设置设备标签 获取设备信息 锁定设备 解锁设备 7.1.2　等待设备插拔事件 原型 功能描述 参数 返回值 注： 本函数为阻塞函数。 SAR_OK： 成功。 其他： 错误码。 ULONG DEVAPI SKF_WaitForDevEvent（LPSTR szDevName，ULONG *pulDev⁃ NameLen， ULONG *pulEvent） 该函数等待设备插入或者拔除事件。szDevName返回发生事件的设备名称。 szDevName pulEvent [OUT]　发生事件的设备名称。 [IN，OUT]　输入/输出参数，当输入时表示缓冲区长度，输出时表 示设备名称的有效长度，长度包含字符串结束符。 [OUT]　事件类型。1表示插入，2表示拔出。 7.1.3　取消等待设备插拔事件 原型 功能描述 参数 返回值 注： 使本进程正在执行的 SKF_WaitForDevEvent函数立即返回。 SAR_OK： 成功。 其他： 错误码。 该函数取消等待设备插入或者拔除事件。 7.1.4　枚举设备 原型 功能描述 ULONG DEVAPI SKF_EnumDev（BOOL bPresent， LPSTR szNameList， ULONG *pulSize） 获得当前系统中的设备列表。 参数 返回值 SAR_OK： 成功。 其他： 错误码。 bPresent szNameList [IN]　为TRUE表示取当前设备状态为存在的设备列表。为 FALSE 表示取当前驱动支持的设备列表。 [OUT]　设备名称列表。如果该参数为NULL，将由 pulSize返回该列 表的字节长度。每个设备的名称以单个‘\0’结束，以双‘\0’表示列表 的结束。 [IN，OUT]　输入时表示设备名称列表的缓冲区长度，输出时表示 sz⁃ NameList所占用的空间大小。 7.1.5　连接设备 原型 功能描述 参数 返回值 SAR_OK： 成功。 其他： 错误码。 ULONG DEVAPI SKF_ConnectDev （LPSTR szName， DEVHANDLE *phDev） 通过设备名称连接设备，返回设备的句柄。 szName phDev [IN]　设备名称。 [OUT]　返回设备操作句柄。 7.1.6　断开连接 原型 功能描述 参数 返回值 注： 如果该设备已被锁定，函数首先解锁该设备。断开连接操作并不影响设备的权限状态。 SAR_OK： 成功。 其他： 错误码。 ULONG DEVAPI SKF_DisConnectDev （DEVHANDLE hDev） 断开一个已经连接的设备，并释放句柄。 hDev [IN]　连接设备时返回的设备句柄。 7.1.7　获取设备状态 原型 功能描述 参数 返回值 SAR_OK： 成功。 其他： 错误码。 ULONG DEVAPI SKF_GetDevState（LPSTR szDevName， ULONG *pulDevState） 获取设备是否存在的状态。 szDevName pulDevState [IN]　设备名称。 [OUT]　返回设备状态。 7.1.8　设置设备标签 原型 功能描述 参数 ULONG DEVAPI SKF_SetLabel （DEVHANDLE hDev， LPSTR szLabel） 设置设备标签。 hDev szLabel [IN]　连接设备时返回的设备句柄。 [IN]　设备标签字符串。该字符串应小于 32字节。 返回值 SAR_OK： 成功。 其他： 错误码。 7.1.9　获取设备信息 原型 功能描述 参数 返回值 SAR_OK： 成功。 其他： 错误码。 ULONG DEVAPI SKF_GetDevInfo （DEVHANDLE hDev， DEVINFO *pDevInfo） 获取设备的一些特征信息，包括设备标签、厂商信息和支持的算法。 hDev pDevInfo [IN]　连接设备时返回的设备句柄。 [OUT]　返回设备信息。 7.1.10　锁定设备 原型 功能描述 参数 返回值 SAR_OK： 成功。 其他： 错误码。 ULONG DEVAPI SKF_LockDev （DEVHANDLE hDev， ULONG ulTimeOut） 获得设备的独占使用权。 hDev ulTimeOut [IN]　连接设备时返回的设备句柄。 [IN]　超时时间，单位为毫秒。如果为 0xFFFFFFFF表示无限等待。 7.1.11　解锁设备 原型 功能描述 参数 返回值 SAR_OK： 成功。 其他： 错误码。 ULONG DEVAPI SKF_UnlockDev （DEVHANDLE hDev） 释放对设备的独占使用权。 hDev [IN]　连接设备时返回的设备句柄。 7.2　访问控制 7.2.1　概述 访问控制主要完成设备认证、PIN 码管理和安全状态管理操作。安全状态表示设备认证、校验 PIN 之后用户所取得的资源访问能力。访问控制系列函数见表 17。 表 17　访问控制系列函数 函数名称 SKF_ChangeDevAuthKey SKF_DevAuth SKF_ChangePIN SKF_GetPINInfo SKF_VerifyPIN SKF_UnblockPIN SKF_ClearSecueState 功能 修改设备认证密钥 设备认证 修改 PIN 获得 PIN码信息 校验 PIN 解锁 PIN 清除应用安全状态 7.2.2　修改设备认证密钥 原型 功能描述 参数 返回值 SAR_OK： 成功。 其他： 错误码。 ULONG DEVAPI SKF_ChangeDevAuthKey （DEVHANDLE hDev， BYTE *pbKeyCi⁃ pher， ULONG ulKeyCipherLen，BYTE *pbKeyMac， ULONG ulKeyMacLen） 更改设备认证密钥。使用密文+MAC方式进行密钥更新。MAC用于保证只有原设备 认证密钥持有者才能完成本操作。 hDev pbKeyCipher ulKeyMacLen [IN]　连接时返回的设备句柄。 [IN]　新设备认证密钥的密文。该密文通过使用原设备认证密钥 对新设备认证密钥进行加密得到，计算过程应符合GM/T 0017- 2023中附录 B的规定。 [IN]　pbKeyCipher的长度。 [IN]　报文鉴别码，该报文鉴别码由原设备认证密钥对含有 pbKey⁃ Cipher的数据进行计算得到，计算过程应符合GM/T 0017-2023 中附录 B的规定。 [IN]　pbKeyMac的长度。 7.2.3　设备认证 原型 功能描述 参数 返回值 SAR_OK： 成功。 其他： 错误码。 ULONG DEVAPI SKF_DevAuth （DEVHANDLE hDev， BYTE *pbAuthData， ULONG ulLen） 设备认证是设备对应用程序的认证。认证过程应符合 8.2.3中的规定。 hDev pbAuthData ulLen [IN]　连接时返回的设备句柄。 [IN]　认证数据。 [IN]　认证数据的长度。 7.2.4　修改 PIN 原型 功能描述 参数 ULONG DEVAPI SKF_ChangePIN （HAPPLICATION hApplication， ULONG ulPIN⁃ Type， LPSTR szOldPin，LPSTR szNewPin，ULONG *pulRetryCount） 调用该函数可修改Administrator PIN和User PIN的值。 如果原 PIN码错误导致验证失败，该函数会返回相应 PIN码的剩余重试次数，当剩余次 数为 0时，表示 PIN已经被锁死。 hApplication ulPINType pulRetryCount [IN]　应用句柄。 [IN]　PIN类型，可为ADMIN_TYPE或USER_TYPE。 [IN]　原 PIN值。 [IN]　新 PIN值。 [OUT]　出错后重试次数。 返回值 SAR_OK： 成功。 其他： 错误码。 7.2.5　获取 PIN信息 原......

相关标准: GA/T 1389  GM/T 0009  GM/T 0010  GM/T 0006