1、最终版智能IC卡及智能密码钥匙密码应用接口规范国密封皮0223修订智能IC卡及智能密码钥匙密码应用接口规范Smart Card and Smart TokenCryptography Application Interface Specification国家密码管理局2010年4月目 次前 言 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 常
2、量定义 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 断开连
3、接 127.1.7 获取设备状态 127.1.8 设置设备标签 127.1.9 获取设备信息 137.1.10 锁定设备 137.1.11 解锁设备 137.1.12 设备命令传输 137.2 访问控制 137.2.1 概述 137.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
4、关闭应用 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签名 2
5、27.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外来公钥加密 257.6.17 ECC外来私钥解密 257.6.18 ECC外来私钥签名 257.6.19 ECC外来公钥验签 257.6.20 ECC生成密钥协商参数并输出 267.6.21 ECC产生协商数据并计算会话密钥 267.6.22 EC
6、C计算会话密钥 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 多组数
7、据消息鉴别码运算 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 （规范性附录） 错误代码定义和说明 34前 言本规范涉及的密码算法按照国家密码管理部门的要求使用。本规范的附录A为规范性附录。本规范由国家密码管理局提出并归口。本规范起草单位：北京海泰方圆科技有限公司、北京握奇智能科技有限公司、北京大明五洲科技有限公司、恒宝
8、股份有限公司、深圳市明华澳汉科技股份有限公司、武汉天喻信息产业股份有限公司、北京飞天诚信科技有限公司、华翔腾数码科技有限公司。本规范主要起草人：石玉平、柳增寿、胡俊义、管延军、项莉、雷继业、胡鹏、赵再兴、段晓毅、刘玉峰、刘伟丰、陈吉、何永福、李高锋、黄东杰、王建承、汪雪林、赵李明。本规范责任专家：刘平、郭宝安。智能IC卡及智能密码钥匙密码应用接口规范1 范围本规范规定了基于PKI密码体制的智能IC卡及智能密码钥匙密码应用接口，描述了密码应用接口的函数、数据类型、参数的定义和设备的安全要求。本规范适用于智能IC卡及智能密码钥匙产品的研制、使用和检测。2 规范性引用文件下列文件中的条款通过本规范的
9、引用而成为本规范的条款。凡是注日期的引用文件，其随后所有的修改单（不包括勘误的内容）或修订版均不适用于本规范，然而，鼓励根据本规范达成协议的各方研究是否可使用这些的最新版本。凡是不注日期的引用文件，其最新版本适用于本规范。GB/T AAAAA 公钥密码基础设施应用技术体系 SM2算法使用规范3 术语和定义以下术语和定义适用于本规范。3.1应用 application 包括容器、设备认证密钥和文件的一种结构，具备独立的权限管理。3.2容器 container特指密钥容器，是一个用于存放非对称密钥对和会话密钥的逻辑对象。3.3 设备 device 智能IC卡及智能密码钥匙的统称。3.4设备认证 d
10、evice 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 card含CPU的IC卡，这里指能完成密码功能的IC卡
11、。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
12、一种国家商用密码分组加密算法，分组长度为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 Cryptog
13、raphy Standard Part 5)PIN 个人身份识别码（Personal Identification Number)MAC 消息鉴别码（Message Authentication Code）ECC 椭圆曲线密码算法（Elliptic Curve Cryptography）5 结构模型5.1 层次关系智能IC卡及智能密码钥匙密码应用接口位于智能IC卡及智能密码钥匙应用程序与设备之间，如图1所示。图1接口在应用层次关系中的位置5.2 设备的应用结构一个设备中存在设备认证密钥和多个应用，应用之间相互独立。设备的逻辑结构如图2所示。图2 设备逻辑结构应用由管理员PIN、用户PIN、文件
14、和容器组成，可以存在多个文件和多个容器。每个应用维护各自的与管理员PIN和用户PIN相关的权限状态。应用的逻辑结构如图3所示。图3 应用逻辑结构图容器中存放加密密钥对、签名密钥对和会话密钥。其中加密密钥对用于保护会话密钥，签名密钥对用于数字签名和验证，会话密钥用于数据加解密和MAC运算。其中，签名密钥对由内部产生，加密密钥对由外部产生并安全导入，会话密钥可由内部产生或者由外部产生并安全导入。6 数据类型定义6.1 算法标识6.1.1 分组密码算法标识分组密码算法标识包含密码算法的类型和加密模式。分组密码算法标识的编码规则为：从低位到高位，第0位到第7位按位表示分组密码算法工作模式，第8位到第3
15、1位按位表示分组密码算法类型，分组密码算法的标识如表1所示。表 1 分组密码算法标识表标签标识符描述SGD_SM1_ECB0x00000101SM1算法ECB加密模式SGD_SM1_CBC0x00000102SM1算法CBC加密模式SGD_SM1_CFB0x00000104SM1算法CFB加密模式SGD_SM1_OFB0x00000108SM1算法OFB加密模式SGD_SM1_MAC0x00000110SM1算法MAC运算SGD_SSF33_ECB0x00000201SSF33算法ECB加密模式SGD_SSF33_CBC0x00000202SSF33算法CBC加密模式SGD_SSF33_CFB
16、0x00000204SSF33算法CFB加密模式SGD_SSF33_OFB0x00000208SSF33算法OFB加密模式SGD_SSF33_MAC0x00000210SSF33算法MAC运算SGD_SMS4_ECB0x00000401SMS4算法ECB加密模式SGD_SMS4_CBC0x00000402SMS4算法CBC加密模式SGD_SMS4_CFB0x00000404SMS4算法CFB加密模式SGD_SMS4_OFB0x00000408SMS4算法OFB加密模式SGD_SMS4_MAC0x00000410SMS4算法MAC运算6.1.2 非对称密码算法标识非对称密码算法标识仅定义了密码算
17、法的类型，在使用非对称算法进行数字签名运算时，可将非对称密码算法标识符与密码杂凑算法标识符进行“或”运算后使用，如“RSA with SHA1”可表示为SGD_RSA | SGD_SHA1，即0x00010002，“|”表示“或”运算。非对称密码算法标识的编码规则为：从低位到高位，第0位到第7位为0，第8位到第15位按位表示非对称密码算法的算法协议，如果所表示的非对称算法没有相应的算法协议则为0，第16位到第31位按位表示非对称密码算法类型，非对称密码算法的标识如表2所示。表 2 非对称密码算法标识表标签标识符描述SGD_RSA0x00010000RSA算法SGD_SM2_10x0002010
18、0椭圆曲线签名算法SGD_SM2_20x00020200椭圆曲线密钥交换协议SGD_SM2_30x00020400椭圆曲线加密算法6.1.3 密码杂凑算法标识密码杂凑算法标识符可以在进行密码杂凑运算或计算MAC时应用，也可以与非对称密码算法标识符进行“或”运算后使用，表示签名运算前对数据进行密码杂凑运算的算法类型。密码杂凑算法标识的编码规则为：从低位到高位，第0位到第7位表示密码杂凑算法，第8位到第31位为0，密码杂凑算法的标识如表3所示。表 3 密码杂凑算法标识表标签标识符描述SGD_SM30x00000001SM3密码杂凑算法SGD_SHA10x00000002SHA1密码杂凑算法SGD_
19、SHA2560x00000004SHA256密码杂凑算法6.2 基本数据类型本规范中的字节数组均为高位字节在前（Big-Endian）方式存储和交换。基本数据类型定义如表4所示：表 4 基本数据类型类型名称描述定义INT8有符号8位整数INT16有符号16位整数INT32有符号32位整数UINT8无符号8位整数UINT16无符号16位整数UINT32无符号32位整数BOOL布尔类型，取值为TRUE或FALSEBYTE字节类型，无符号8位整数typedef UINT8 BYTECHAR字符类型，无符号8位整数typedef UINT8 CHARSHORT短整数，有符号16位typedef INT
20、16 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 FLAGSLPSTR8位字符串指针，按照UTF8格式存储及交换typedef CHAR * LP
21、STRHANDLE 句柄，指向任意数据对象的起始地址typedef void * HANDLEDEVHANDLE设备句柄typedef HANDLE DEVHANDLEHAPPLICATION应用句柄typedef HANDLE HAPPLICATIONHCONTAINER容器句柄typedef HANDLE HCONTAINER6.3 常量定义数据常量标识定义了在规范中用到的常量的取值。数据常量标识的定义如表5所示。表 5 常量定义常量名取值描述TRUE0x00000001布尔值为真FALSE0x00000000布尔值为假DEVAPI_stdcall_stdcall函数调用方式ADMIN_T
22、YPE0管理员PIN类型USER_TYPE1用户PIN类型6.4 复合数据类型6.4.1 版本（1）类型定义typedef struct Struct_VersionBYTE major;BYTE minor;VERSION;（2）数据项描述参见表6：表 6 版本定义数据项类型意义备注majorBYTE主版本号主版本号和次版本号以“.”分隔，例如 Version 1.0，主版本号为1，次版本号为0；Version 2.10，主版本号为2，次版本号为10。minorBYTE次版本号6.4.2 设备信息（1）类型定义typedef struct Struct_DEVINFOVERSION Vers
23、ion;CHAR Manufacturer64;CHAR Issuer64;CHAR Label32;CHAR SerialNumber32;VERSION HWVersion;VERSION FirmwareVersion;ULONG AlgSymCap;ULONG AlgAsymCap;ULONG AlgHashCap;ULONG DevAuthAlgId;ULONG TotalSpace;ULONG FreeSpace;BYTE Reserved64;DEVINFO,*PDEVINFO;（2）数据项描述参见表7：表 7 设备信息描述数据项类型意义备注VersionVERSION版本号数据
24、结构版本号，本结构的版本号为1.0ManufacturerCHAR数组设备厂商信息以 0为结束符的ASCII字符串IssuerCHAR数组发行厂商信息以 0为结束符的ASCII字符串LabelCHAR数组设备标签以 0为结束符的ASCII字符串SerialNumberCHAR数组序列号以 0为结束符的ASCII字符串HWVersionVERSION设备硬件版本 FirmwareVersionVERSION设备本身固件版本AlgSymCapULONG分组密码算法标识AlgAsymCapULONG非对称密码算法标识AlgHashCapULONG密码杂凑算法标识DevAuthAlgIdULONG设备
25、认证使用的分组密码算法标识TotalSpaceULONG设备总空间大小FreeSpaceULONG用户可用空间大小ReservedBYTE保留扩展6.4.3 RSA公钥数据结构（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
26、_RSA_EXPONENT_LEN为算法指数的最大长度。（2）数据项描述参见表8：表 8 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.4 RSA私钥数据结构（1）类型定义typedef struct Struct_RSAPRIVATEKEYBLO
27、BULONG 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 Coefficie
28、ntMAX_RSA_MODULUS_LEN/2;RSAPRIVATEKEYBLOB, *PRSAPRIVATEKEYBLOB;MAX_RSA_MODULUS_LEN为RSA算法模数的最大长度；（2）数据项描述参见表9：表 9 RSA私钥数据结构数据项类型意义备注AlgIDULONG算法标识号BitLenULONG模数的实际位长度必须是8的倍数ModulusBYTE数组模数n = p * q实际长度为BitLen/8字节PublicExponentBYTE数组公开密钥e一般为00010001PrivateExponentBYTE数组私有密钥d实际长度为BitLen/8字节Prime1BYTE数组素数p实际长度为BitLen/16字节Prime2BYTE数组素数q实际长度为BitLen/16字节Prime1ExponentBYTE数组d mod (p-1)的值实际长度为BitLen/16字节Prime2ExponentBYTE数组d mod (q -1)的值实际长度为BitLen/16字节CoefficientBYTE数组q模p的乘法逆元实际长度为BitLen/16字节6.4.5 ECC公钥数据结构（1）类型定义typedef struct Struct_ECC
