智能ic卡及智能密码钥匙密码应用接口规范_征求意见稿_20110408

智能 IC 卡及智能密码钥匙密码应用接口规范Smart Card and Smart TokenCryptography Application Interface Specification国 家 密 码 管 理 局2010 年 4 月I目 次前 言 IV1 范围 .12 规范性引用文件 .13 术语和定义 .14 缩略语 .25 结构模型 .25.1 层次关系 .25.2 设备的应用结构 .36 数据类型定义 .46.1 算法标识 .46.1.1 分组密码算法标识 46.1.2 非对称密码算法标识 56.1.3 密码杂凑算法标识 56.2 基本数据类型 .56.3 常量定义 .66.4 复合数据类型 .66.4.1 版本 66.4.2 设备信息 66.4.3 RSA 公钥数据结构 .76.4.4 RSA 私钥数据结构 .86.4.5 ECC 公钥数据结构 .86.4.6 ECC 私钥数据结构 .96.4.7 ECC 密文数据结构 .96.4.8 ECC 签名数据结构 .96.4.9 分组密码参数 .106.4.10 文件属性 .106.4.11 权限类型 116.4.12 设备状态 .117 接口函数 117.1 设备管理 117.1.1 概述 .117.1.2 等待设备插拔事件 .117.1.3 取消等待设备插拔事件 .127.1.4 枚举设备 .127.1.5 连接设备 .127.1.6 断开连接 .127.1.7 获取设备状态 .127.1.8 设置设备标签 .127.1.9 获取设备信息 .137.1.10 锁定设备 .137.1.11 解锁设备 137.1.12 设备命令传输 .137.2 访问控制 137.2.1 概述 .13II7.2.2 修改设备认证密钥 .147.2.3 设备认证 .147.2.4 修改 PIN .147.2.5 获取 PIN 信息 .147.2.6 校验 PIN .157.2.7 解锁 PIN .157.2.8 清除应用安全状态 .157.3 应用管理 157.3.1 概述 .157.3.2 创建应用 .157.3.3 枚举应用 .167.3.4 删除应用 .167.3.5 打开应用 .167.3.6 关闭应用 .167.4 文件管理 177.4.1 概述 .177.4.2 创建文件 .177.4.3 删除文件 .177.4.4 枚举文件 .177.4.5 获取文件属性 .187.4.6 读文件 .187.4.7 写文件 .187.5 容器管理 187.5.1 概述 .187.5.2 创建容器 .197.5.3 删除容器 .197.5.4 打开容器 .197.5.5 关闭容器 .197.5.6 枚举容器 .197.6 密码服务 207.6.1 概述 .207.6.2 生成随机数 .217.6.3 生成外部 RSA 密钥对 .217.6.4 生成 RSA 签名密钥对 .217.6.5 导入 RSA 加密密钥对 .217.6.6 RSA 签名 227.6.7 RSA 验签 227.6.8 RSA 生成并导出会话密钥 227.6.9 RSA 外来公钥运算 237.6.10 RSA 外来私钥运算 237.6.11 生成 ECC 签名密钥对 237.6.12 导入 ECC 加密密钥对 .247.6.13 ECC 签名 247.6.14 ECC 验签 247.6.15 ECC 生成并导出会话密钥 247.6.16 ECC 外来公钥加密 25III7.6.17 ECC 外来私钥解密 257.6.18 ECC 外来私钥签名 257.6.19 ECC 外来公钥验签 257.6.20 ECC 生成密钥协商参数并输出 267.6.21 ECC 产生协商数据并计算会话密钥 267.6.22 ECC 计算会话密钥 267.6.23 导出公钥 .277.6.24 导入会话密钥 .277.6.25 明文导入会话密钥 .277.6.26 加密初始化 .287.6.27 单组数据加密 .287.6.28 多组数据加密 .287.6.29 结束加密 .287.6.30 解密初始化 .297.6.31 单组数据解密 .297.6.32 多组数据解密 .297.6.33 结束解密 .307.6.34 密码杂凑初始化 .307.6.35 单组数据密码杂凑 .307.6.36 多组数据密码杂凑 .307.6.37 结束密码杂凑 .317.6.38 消息鉴别码运算初始化 .317.6.39 单组数据消息鉴别码运算 .317.6.40 多组数据消息鉴别码运算 .327.6.41 结束消息鉴别码运算 .327.6.42 关闭密码对象句柄 .328 设备的安全要求 328.1 设备使用阶段 328.2 权限管理 328.2.1 权限分类 .328.2.2 权限使用 .328.2.3 设备认证 .338.2.4 PIN 码安全要求 338.3 密钥安全要求 338.4 设备抗攻击要求 33附录 A （规范性附录） 错误代码定义和说明 34IV前 言本规范涉及的密码算法按照国家密码管理部门的要求使用。本规范的附录 A 为规范性附录。本规范由国家密码管理局提出并归口。本规范起草单位：北京海泰方圆科技有限公司、北京握奇智能科技有限公司、北京大明五洲科技有限公司、恒宝股份有限公司、深圳市明华澳汉科技股份有限公司、武汉天喻信息产业股份有限公司、北京飞天诚信科技有限公司、华翔腾数码科技有限公司。本规范主要起草人：石玉平、柳增寿、胡俊义、管延军、项莉、雷继业、胡鹏、赵再兴、段晓毅、刘玉峰、刘伟丰、陈吉、何永福、李高锋、黄东杰、王建承、汪雪林、赵李明。本规范责任专家：刘平、郭宝安。1智能 IC 卡及智能密码钥匙密码应用接口规范1 范围本规范规定了基于 PKI 密码体制的智能 IC 卡及智能密码钥匙密码应用接口，描述了密码应用接口的函数、数据类型、参数的定义和设备的安全要求。本规范适用于智能 IC 卡及智能密码钥匙产品的研制、使用和检测。2 规范性引用文件下列文件中的条款通过本规范的引用而成为本规范的条款。凡是注日期的引用文件，其随后所有的修改单（不包括勘误的内容）或修订版均不适用于本规范，然而，鼓励根据本规范达成协议的各方研究是否可使用这些的最新版本。凡是不注日期的引用文件，其最新版本适用于本规范。GM/T AAAAA SM2 密码使用规范GM/T BBBBB 标识规范3 术语和定义以下术语和定义适用于本规范。3.1应用 application包括容器、设备认证密钥和文件的一种结构，具备独立的权限管理。3.2容器 container特指密钥容器，是一个用于存放非对称密钥对和会话密钥的逻辑对象。3.3设备 device智能 IC 卡及智能密码钥匙的统称。3.4设备认证 device authentication智能 IC 卡或智能密码钥匙对应用程序的认证。3.5设备认证密钥 device authentication key用于设备认证的密钥。3.6设备标签 label设备的别名，可以由用户进行设定并存储于设备内部。3.7消息鉴别码 message authentication code (MAC)消息鉴别算法的输出。3.8管理员 PIN Administrator PIN管理员的密码，为ASCII字符串。3.9用户 PIN User PIN用户的个人密码，为 ASCII 字符串。3.10智能 IC 卡 smart card2含 CPU 的 IC 卡，这里指能完成密码功能的 IC 卡。3.11智能密码钥匙 smart token能完成密码功能和安全存储的终端密码产品，一般采用 USB 接口。3.12SM1 算法 SM1 algorithm一种国家商用密码分组加密算法，分组长度为128比特，密钥长度为128比特。3.13SM2 算法 SM2 algorithm一种国家商用密码非对称密码算法，密钥长度为256比特。3.14SM3 算法 SM3 algorithm一种国家商用密码密码杂凑算法，输出长度为256比特。3.15SMS4 算法 SMS4 algorithm一种国家商用密码分组加密算法，分组长度为128比特，密钥长度为128比特。3.16SSF33 算法 SSF33 algorithm一种国家商用密码分组加密算法，分组长度为128比特，密钥长度为128比特。4 缩略语下列缩略语适用于本规范：API 应用编程接口（Application Programming Interface）PKI 公钥基础设施（Public Key Infrastructure)PKCS#1 公钥密码使用标准系列规范中的第1部分，定义RSA公开密钥算法加密和签名机制(the Public-Key Cryptography Standard Part 1)PKCS#5 公钥密码使用标准系列规范中的第5部分，描述一种利用从口令派生出来的安全密钥加密字符串的方法(the Public-Key Cryptography Standard Part 5)PIN 个人身份识别码（Personal Identification Number)MAC 消息鉴别码（Message Authentication Code）ECC 椭圆曲线密码算法（Elliptic Curve Cryptography）5 结构模型5.1 层次关系智能 IC 卡及智能密码钥匙密码应用接口位于智能 IC 卡及智能密码钥匙应用程序与设备之间，如图 1 所示。3智能 I C 卡及智能密码钥匙应用程序智能 I C 卡及智能密码钥匙密码应用接口智能 I C 卡及智能密码钥匙设备驱动 设备 1 设备 2 设备 n 图 1 接口在应用层次关系中的位置5.2 设备的应用结构一个设备中存在设备认证密钥和多个应用，应用之间相互独立。设备的逻辑结构如图 2 所示。设备认证密钥应 用 1应 用 n图 2 设备逻辑结构应用由管理员 PIN、用户 PIN、文件和容器组成，可以存在多个文件和多个容器。每个应用维护各自的与管理员 PIN 和用户 PIN 相关的权限状态。应用的逻辑结构如图 3 所示。4管理员 P I N用户 P I N文件 1文件 n加密公钥加密私钥签名公钥签名私钥会话密钥 1会话密钥 n容器 1应用结构加密数字证书签名数字证书加密公钥加密私钥签名公钥签名私钥会话密钥 1会话密钥 n容器 n加密数字证书签名数字证书图 3 应用逻辑结构图容器中存放加密密钥对、签名密钥对和会话密钥。其中加密密钥对用于保护会话密钥，签名密钥对用于数字签名和验证，会话密钥用于数据加解密和 MAC 运算。容器中也可以存放与加密密钥对对应的加密数字证书和与签名密钥对对应的签名数字证书。其中，签名密钥对由内部产生，加密密钥对由外部产生并安全导入，会话密钥可由内部产生或者由外部产生并安全导入。6 数据类型定义6.1 算法标识本规范中使用的算法其标识定义参见 GM/T标识规范 。6.2 基本数据类型本规范中的字节数组均为高位字节在前（Big-Endian）方式存储和交换。基本数据类型定义如表 1 所示：表 1 基本数据类型类型名称 描述 定义INT8 有符号 8 位整数INT16 有符号 16 位整数INT32 有符号 32 位整数UINT8 无符号 8 位整数UINT16 无符号 16 位整数5UINT32 无符号 32 位整数BOOL 布尔类型，取值为 TRUE 或FALSEBYTE 字节类型，无符号 8 位整数 typedef UINT8 BYTECHAR 字符类型，无符号 8 位整数 typedef UINT8 CHARSHORT 短整数，有符号 16 位 typedef INT16 SHORTUSHORT 无符号 16 位整数 typedef UINT16 USHORTLONG 长整数，有符号 32 位整数 typedef INT32 LONGULONG 长整数，无符号 32 位整数 typedef UINT32 ULONGUINT 无符号 32 位整数 typedef UINT32 UINTWORD 字类型，无符号 16 位整数 typedef UINT16 WORDDWORD 双字类型，无符号 32 位整数typedef UINT32 DWORDFLAGS 标志类型，无符号 32 位整数typedef UINT32 FLAGSLPSTR 8 位字符串指针，按照 UTF8格式存储及交换typedef CHAR * LPSTRHANDLE 句柄，指向任意数据对象的起始地址typedef void * HANDLEDEVHANDLE 设备句柄 typedef HANDLE DEVHANDLEHAPPLICATION 应用句柄 typedef HANDLE HAPPLICATIONHCONTAINER 容器句柄 typedef HANDLE HCONTAINER6.3 常量定义数据常量标识定义了在规范中用到的常量的取值。数据常量标识的定义如表 2 所示。表 2 常量定义常量名 取值 描述TRUE 0x00000001 布尔值为真FALSE 0x00000000 布尔值为假DEVAPI _stdcall _stdcall 函数调用方式ADMIN_TYPE 0 管理员 PIN 类型USER_TYPE 1 用户 PIN 类型6.4 复合数据类型6.4.1版本（1）类型定义typedef struct Struct_VersionBYTE major;BYTE minor;VERSION;（2）数据项描述参见表 3：表 3 版本定义数据项 类型 意义 备注major BYTE 主版本号minor BYTE 次版本号主版本号和次版本号以“.”分隔，例如 Version 1.0，主版本号为 1，次版本号为 0；Version 2.10，主版本号为 2，次版本号为 10。66.4.2设备信息（1）类型定义typedef struct Struct_DEVINFOVERSION Version;CHAR Manufacturer64;CHAR Issuer64;CHAR Label32;CHAR SerialNumber32;VERSION HWVersion;VERSION FirmwareVersion;ULONG AlgSymCap;ULONG AlgAsymCap;ULONG AlgHashCap;ULONG DevAuthAlgId;ULONG TotalSpace;ULONG FreeSpace;ULONG MaxECCBufferSize;ULONG MaxBufferSize;BYTE Reserved64;DEVINFO,*PDEVINFO;（2）数据项描述参见表 4：表 4 设备信息描述数据项 类型 意义 备注Version VERSION 版本号 数据结构版本号，本结构的版本号为 1.0Manufacturer CHAR 数组 设备厂商信息 以 0为结束符的 ASCII 字符串Issuer CHAR 数组 发行厂商信息 以 0为结束符的 ASCII 字符串Label CHAR 数组 设备标签 以 0为结束符的 ASCII 字符串SerialNumber CHAR 数组 序列号 以 0为结束符的 ASCII 字符串HWVersion VERSION 设备硬件版本 FirmwareVersion VERSION 设备本身固件版本AlgSymCap ULONG 分组密码算法标识AlgAsymCap ULONG 非对称密码算法标识AlgHashCap ULONG 密码杂凑算法标识DevAuthAlgId ULONG 设备认证使用的分组密码算法标识TotalSpace ULONG 设备总空间大小FreeSpace ULONG 用户可用空间大小MaxECCBufferSize ULONG 能够处理的 ECC 加密数据大小7MaxBufferSize 能够处理的分组运算和杂凑运算的数据大小Reserved BYTE 保留扩展6.4.3RSA 公钥数据结构（1）类型定义typedef struct Struct_RSAPUBLICKEYBLOBULONG AlgID;ULONG BitLen;BYTE ModulusMAX_RSA_MODULUS_LEN;BYTE PublicExponentMAX_RSA_EXPONENT_LEN;RSAPUBLICKEYBLOB, *PRSAPUBLICKEYBLOB;MAX_RSA_MODULUS_LEN 为算法模数的最大长度；MAX_RSA_EXPONENT_LEN 为算法指数的最大长度。（2）数据项描述参见表 5：表 5 RSA 公钥数据结构数据项 类型 意义 备注AlgID ULONG 算法标识号BitLen ULONG 模数的实际位长度 必须是 8 的倍数Modulus BYTE 数组 模数 n = p * q 实际长度为 BitLen/8 字节#define MAX_RSA_MODULUS_LEN 256#define MAX_RSA_EXPONENT_LEN 4PublicExponent BYTE 数组 公开密钥 e 一般为 000100016.4.4RSA 私钥数据结构（1）类型定义typedef struct Struct_RSAPRIVATEKEYBLOBULONG AlgID;ULONG BitLen;BYTE ModulusMAX_RSA_MODULUS_LEN;BYTE PublicExponentMAX_RSA_EXPONENT_LEN;BYTE PrivateExponentMAX_RSA_MODULUS_LEN;BYTE Prime1MAX_RSA_MODULUS_LEN/2;BYTE Prime2MAX_RSA_MODULUS_LEN/2;BYTE Prime1ExponentMAX_RSA_MODULUS_LEN/2;BYTE Prime2ExponentMAX_RSA_MODULUS_LEN/2;BYTE CoefficientMAX_RSA_MODULUS_LEN/2;RSAPRIVATEKEYBLOB, *PRSAPRIVATEKEYBLOB;MAX_RSA_MODULUS_LEN 为 RSA 算法模数的最大长度；（2）数据项描述参见表 6：表 6 RSA 私钥数据结构数据项 类型 意义 备注AlgID ULONG 算法标识号BitLen ULONG 模数的实际位长度 必须是 8 的倍数Modulus BYTE 数组 模数 n = p * q 实际长度为 BitLen/8 字节PublicExponent BYTE 数组 公开密钥 e 一般为 000100018PrivateExponent BYTE 数组 私有密钥 d 实际长度为 BitLen/8 字节Prime1 BYTE 数组 素数 p 实际长度为 BitLen/16 字节Prime2 BYTE 数组 素数 q 实际长度为 BitLen/16 字节Prime1Exponent BYTE 数组 d mod (p-1)的值 实际长度为 BitLen/16 字节Prime2Exponent BYTE 数组 d mod (q -1)的值 实际长度为 BitLen/16 字节Coefficient BYTE 数组 q 模 p 的乘法逆元 实际长度为 BitLen/16 字节6.4.5ECC 公钥数据结构（1）类型定义typedef struct Struct_ECCPUBLICKEYBLOBULONG BitLen;BYTE XCoordinateECC_MAX_XCOORDINATE_BITS_LEN/8;BYTE YCoordinateECC_MAX_YCOORDINATE_BITS_LEN/8;ECCPUBLICKEYBLOB, *PECCPUBLICKEYBLOB;ECC_MAX_XCOORDINATE_LEN 为 ECC 算法 X 坐标的最大长度；ECC_MAX_YCOORDINATE_LEN 为 ECC 算法 Y 坐标的最大长度。（2）数据项描述参见表 7：表 7 ECC 公钥数据结构数据项 类型 意义 备注BitLen ULONG 模数的实际位长度必须是 8 的倍数XCoordinate BYTE 数组 曲线上点的X 坐标有限域上的整数#define ECC_MAX_XCOORDINATE_BITS_LEN 512YCoordinate BYTE 数组 曲线上点的Y 坐标有限域上的整数#define ECC_MAX_YCOORDINATE_BITS_LEN 5126.4.6ECC 私钥数据结构（1）类型定义typedef struct Struct_ECCPRIVATEKEYBLOBULONG BitLen;BYTE PrivateKeyECC_MAX_MODULUS_BITS_LEN/8;ECCPRIVATEKEYBLOB, *PECCPRIVATEKEYBLOB;ECC_MAX_MODULUS_BITS_LEN 为 ECC 算法模数的最大长度。（2）数据项描述参见表 8：表 8 ECC 私钥数据结构数据项 类型 意义 备注BitLen ULONG 模数的实际位长度 必须是 8 的倍数PrivateKey BYTE 数组 私有密钥 有限域上的整数#define ECC_MAX_MODULUS_BITS_LEN 5126.4.7ECC 密文数据结构（1） 类型定义typedef struct Struct_ECCCIPHERBLOBBYTE XCoordinateECC_MAX_XCOORDINATE_BITS_LEN/8; BYTE YCoordinateECC_MAX_XCOORDINATE_BITS_LEN/8; BYTE HASH32; 9ULONG CipherLen;BYTE Cipher1; ECCCIPHERBLOB, *PECCCIPHERBLOB;（2）数据项描述参见表 9：表 9 ECC 密文数据结构数据项 类型 意义 备注XCoordinate BYTE 数组 与 y 组成椭圆曲线上的点（x，y）YCoordinate BYTE 数组 与 x 组成椭圆曲线上的点（x，y）HASH BYTE 数组 明文的杂凑值CipherLen ULONG 密文数据长度Cipher BYTE 数组 密文数据 实际长度为CipherLen6.4.8ECC 签名数据结构（1）类型定义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 算法模数的最大长度；（2）数据项描述参见表 10：表 10 ECC 签名数据结构数据项 类型 意义 备注r BYTE 数组 签名结果的 r 部分s BYTE 数组 签名结果的 s 部分6.4.9分组密码参数（1）类型定义typedef struct Struct_BLOCKCIPHERPARAMBYTE IVMAX_IV_LEN;ULONG IVLen;ULONG PaddingType;ULONG FeedBitLen; BLOCKCIPHERPARAM, *PBLOCKCIPHERPARAM;（2）数据项描述参见表 11：表 11 分组密码参数数据项 类型 意义 备注IV BYTE 数组 初始向量，MAX_IV_LEN 为初始化向量的最大长度#define MAX_IV_LEN 32IVLen ULONG 初始向量实际长度（按字节计算）PaddingType ULONG 填充方式，0 表示不填充，1 表示按照PKCS#5 方式进行填充FeedBitLen ULONG 反馈值的位长度（按位计算） 只针对 OFB、CFB 模式6.4.10 ECC 加密密钥对保护结构10（1）类型定义typedef struct SKF_ENVELOPEDKEYBLOBULONG Version; / 当前版本为 1ULONG ulSymmAlgID; / 对称算法标识，限定 ECB 模式ULONG ulBits; / 加密密钥对的密钥位长度BYTE cbEncryptedPriKey64; / 加密密钥对私钥的密文ECCPUBLICKEYBLOB PubKey; / 加密密钥对的公钥ECCCIPHERBLOB ECCCipherBlob; / 用保护公钥加密的对称密钥密文。ENVELOPEDKEYBLOB, *PENVELOPEDKEYBLOB;（2）数据项描述参见表 12：表 12 加密密钥对保护结构参数数据项 类型 意义 备注Version ULONG 版本号，本版本为 1ulSymmAlgID ULONG 对称算法标识 必须为 ECB 模式ulBits ULONG 加密密钥对的密钥位长cbEncryptedPrivKeyBYTE 数组 对称算法加密的加密私钥,加密私钥的原文为ECCPRIVATEKEYBLOB 结构中的 PrivateKey。其有效长度为原文的（ulBits + 7）/8PubKey ECCPUBLICKEYBLOB 加密密钥对的公钥ECCCipherBlob ECCCIPHERBLOB 用保护公钥加密过的对称密钥密文6.4.11 文件属性（1）类型定义typedef struct Struct_FILEATTRIBUTECHAR FileName32;ULONG FileSize;ULONG ReadRights;ULONG WriteRights; FILEATTRIBUTE, *PFILEATTRIBUTE;（2）数据项描述参见表 16：表 13 文件属性数据项 类型 意义 备注FileName CHAR 数组 文件名 以0结束的 ASCII 字符串，最大长度为 32FileSize ULONG 文件大小 创建文件时定义的文件大小ReadRights ULONG 读取权限 读取文件需要的权限WriteRights ULONG 写入权限 写入文件需要的权限6.4.12 权限类型权限类型的定义参见表 17：表 14 权限类型权限类型 值 说明11SECURE_NEVER_ACCOUNT 0x00000000 不允许SECURE_ADM_ACCOUNT 0x00000001 管理员权限SECURE_USER_ACCOUNT 0x00000010 用户权限SECURE_ANYONE_ACCOUNT 0x000000FF 任何人6.4.13 设备状态设备状态的定义参见表 18：表 15 设备状态设备状态 值 说明DEV_ABSENT_STATE 0x00000000 设备不存在DEV_PRESENT_STATE 0x00000001 设备存在DEV_UNKNOW_STATE 0x00000002 设备状态未知7 接口函数7.1 设备管理7.1.1概述设备管理主要完成设备的插拔事件处理、枚举设备、连接设备、断开连接、获取设备状态、设置设备标签、获取设备信息、锁定设备、解锁设备和设备命令传输等操作。设备管理系列函数如表19 所示：表 16 设备管理系列函数函数名称 功能SKF_WaitForDevEvent 等待设备插拔事件SKF_CancelWaitForDevEvent 取消等待设备插拔事件SKF_EnumDev 枚举设备SKF_ConnectDev 连接设备SKF_DisconnectDev 断开连接SKF_GetDevState 获取设备状态SKF_SetLabel 设置设备标签SKF_GetDevInfo 获取设备信息SKF_LockDev 锁定设备SKF_UnlockDev 解锁设备SKF_Transmit 设备命令传输7.1.2等待设备插拔事件函数原型 ULONG DEVAPI SKF_WaitForDevEvent(LPSTR szDevName,ULONG *pulDevNameLen, ULONG *pulEvent)功能描述 该函数等待设备插入或者拔除事件。szDevName 返回发生事件的设备名称。szDevName OUT 发生事件的设备名称。pulDevNameLen IN/OUT 输入/输出参数，当输入时表示缓冲区长度，输出时表示设备名称的有效长度,长度包含字符串结束符。参数pulEvent OUT事件类型。1 表示插入，2 表示拔出。返回值 SAR_OK： 成功。其他： 错误码。备注 本函数为阻塞函数。7.1.3取消等待设备插拔事件函数原型 ULONG DEVAPI SKF_CancelWaitForDevEvent()12功能描述 该函数取消等待设备插入或者拔除事件。参数返回值 SAR_OK： 成功。其他： 错误码。备注 使本进程正在执行的 SKF_WaitForDevEvent 函数立即返回。7.1.4枚举设备函数原型 ULONG DEVAPI SKF_EnumDev(BOOL bPresent, LPSTR szNameList, ULONG *pulSize)功能描述 获得当前系统中的设备列表。bPresent IN 为 TRUE 表示取当前设备状态为存在的设备列表。为 FALSE表示取当前驱动支持的设备列表。szNameList OUT 设备名称列表。如果该参数为 NULL，将由 pulSize 返回所需要的内存空间大小。每个设备的名称以单个0结束，以双0表示列表的结束。参数pulSize IN，OUT 输入时表示设备名称列表的缓冲区长度，输出时表示szNameList 所占用的空间大小。返回值 SAR_OK： 成功。其他： 错误码。7.1.5连接设备函数原型 ULONG DEVAPI SKF_ConnectDev (LPSTR szName, DEVHANDLE *phDev)功能描述 通过设备名称连接设备，返回设备的句柄。szName IN 设备名称。参数phDev OUT 返回设备操作句柄。返回值 SAR_OK： 成功。其他： 错误码。7.1.6断开连接函数原型 ULONG DEVAPI SKF_DisConnectDev (DEVHANDLE hDev)功能描述 断开一个已经连接的设备，并释放句柄。参数 hDev IN 连接设备时返回的设备句柄。返回值 SAR_OK： 成功。其他： 错误码。备注 如果该设备已被锁定，函数应首先解锁该设备。断开连接操作并不影响设备的权限状态。7.1.7获取设备状态函数原型 ULONG DEVAPI SKF_GetDevState(LPSTR szDevName, ULONG *pulDevState)功能描述 获取设备是否存在的状态。szDevName IN 设备名称。参数pulDevState OUT 返回设备状态。返回值 SAR_OK： 成功。其他： 错误码。7.1.8设置设备标签函数原型 ULONG DEVAPI SKF_SetLabel (DEVHANDLE hDev, LPSTR szLabel)功能描述 设置设备标签。hDev IN 连接设备时返回的设备句柄。参数szLabel IN 设备标签字符串。该字符串应小于 32 字节。返回值 SAR_OK： 成功。13其他： 错误码。7.1.9获取设备信息函数原型 ULONG DEVAPI SKF_GetDevInfo (DEVHANDLE hDev, DEVINFO *pDevInfo)功能描述 获取设备的一些特征信息，包括设备标签、厂商信息、支持的算法等。hDev IN 连接设备时返回的设备句柄。参数pDevInfo OUT 返回设备信息。返回值 SAR_OK： 成功。其他： 错误码。7.1.10 锁定设备函数原型 ULONG DEVAPI SKF_LockDev (DEVHANDLE hDev, ULONG ulTimeOut)功能描述 获得设备的独占使用权。hDev IN 连接设备时返回的设备句柄。参数ulTimeOut IN 超时时间，单位为毫秒。如果为 0xFFFFFFFF 表示无限等待。返回值 SAR_OK： 成功。其他： 错误码。7.1.11 解锁设备函数原型 ULONG DEVAPI SKF_UnlockDev (DEVHANDLE hDev)功能描述 释放对设备的独占使用权。参数 hDev IN 连接设备时返回的设备句柄。返回值 SAR_OK： 成功。其他： 错误码。7.1.12 设备命令传输函数原型 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： 成功。其他： 错误码。备注 本函数仅用于设备检测。7.2 访问控制7.2.1概述访问控制主要完成设备认证、PIN 码管理和安全状态管理等操作。访问控制系列函数如表 20所示：表 17 访问控制系列函数 函数名称 功能SKF_ChangeDevAuthKey 修改设备认证密钥SKF_DevAuth 设备认证SKF_ChangePIN 修改 PINSKF_GetPINInfo 获得 PIN 码信息SKF_VerifyPIN 校验 PINSKF_UnblockPIN 解锁 PIN14SKF_ClearSecueState 清除应用安全状态7.2.2修改设备认证密钥函数原型 ULONG DEVAPI SKF_ChangeDevAuthKey (DEVHANDLE hDev, BYTE *pbKeyValue， ULONG ulKeyLen)功能描述 更改设备认证密钥。hDev IN 连接时返回的设备句柄。pbKeyValue IN 密钥值。参数ulKeyLen IN 密钥长度。返回值 SAR_OK： 成功。其他： 错误码。备注 权限要求：设备认证成功后才能使用。7.2.3设备认证函数原型 ULONG DEVAPI SKF_DevAuth (DEVHANDLE hDev, BYTE *pbAuthData，ULONG ulLen)功能描述 设备认证是设备对应用程序的认证。认证过程参见 8.2.3。hDev IN 连接时返回的设备句柄。pbAuthData IN 认证数据。参数ulLen IN 认证数据的长度。返回值 SAR_OK： 成功。其他： 错误码。7.2.4修改 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： 成功。其他： 错误码。7.2.5获取 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： 成功。其他： 错误码。7.2.6校验 PIN 15函数原型 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： 成功。其他： 错误码。7.2.7解锁 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.2.8清除应用安全状态函数原型 ULONG DEVAPI SKF_ClearSecureState (HAPPLICATION hApplication)功能描述 清除应用当前的安全状态。参数 hApplication IN 应用句柄。返回值 SAR_OK： 成功。其他： 错误码。7.3 应用管理7.3.1概述应用管理主要完成应用的创建、枚举、删除、打开、关闭等操作。应用管理系列函数如表 21所示：表 18 应用管理系列函数函数名称 功能SKF_CreateApplication 创建应用SKF_EnumApplication 枚举应用SKF_DeleteApplication 删除应用SKF_OpenApplication 打开应用SKF_CloseApplication 关闭应用7.3.2创建应用函数原型 ULONG DEVAPI SKF_CreateApplication(DEVHANDLE hDev, LPSTR szAppName, LPSTR szAdminPin, DWORD dwAdminPinRetryCount,LPSTR szUserPin, DWORD dwUserPinRetryCount,DWORD dwCreateFileRights, HAPPLICATION *phApplication)功能描述 创建一个应用。 参数 hDev IN 连接设备时返回的设备句柄。16szAppName IN 应用名称。szAdminPin IN 管理员 PIN。dwAdminPinRetryCount IN 管理员 PIN 最大重试次数。szUserPin IN 用户 PIN。dwUserPinRetryCount IN 用户 PIN 最大重试次数。dwCreateFileRights IN 在该应用下创建文件和容器的权限，参见 6.4.12 权限类型。为各种权限的或值。phApplication OUT 应用的句柄。返回值 SAR_OK： 成功。其他： 错误码。备注 权限要求：需要设备权限。7.3.3枚举应用函数原型 ULONG DEVAPI SKF_EnumApplication(DEVHANDLE hDev, LPSTR szAppName,ULONG *pulSize)功能描述 枚举设备中存在的所有应用。hDev IN 连接设备时返回的设备句柄。szAppName OUT 返回应用名称列表, 如果该参数为空，将由 pulSize返回所需要的内存空间大小。每个应用的名称以单个0结束，以双0表示列表的结束。参数pulSize IN，OUT 输入时表示应用名称的缓冲区长度，输出时返回szAppName 所占用的空间大小。返回值 SAR_OK： 成功。其他： 错误码。7.3.4删除应用函数原型 ULONG DEVAPI SKF_DeleteApplication(DEVHANDLE hDev, LPSTR szAppName)功能描述 删除指定的应用。hDev IN 连接设备时返回的设备句柄。参数szAppName IN 应用名称。返回值 SAR_OK： 成功。其他： 错误码。备注 权限要求：需要设备权限。7.3.5打开应用函数原型 ULONG DEVAPI SKF_OpenApplication(DEVHANDLE hDev, LPSTR szAppName, HAPPLICATION *phApplication)功能描述 打开指定的应用。hDev IN 连接设备时返回的设备句柄。szAppName IN 应用名称。参数phApplication OUT 应用的句柄。返回值 SAR_OK： 成功。其他： 错误码。7.3.6关闭应用函数原型 ULONG DEVAPI SKF_CloseApplication(HAPPLICATIO