1、智能 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
2、.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
3、.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 创建应用 .1
4、57.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.
5、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 外
6、来私钥解密 .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 结
7、束解密 .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.
8、4 设备抗攻击要求 .33附录 A （规范性附录） 错误代码定义和说明 .34IV前 言本规范涉及的密码算法按照国家密码管理部门的要求使用。本规范的附录 A 为规范性附录。本规范由国家密码管理局提出并归口。本规范起草单位：北京海泰方圆科技有限公司、北京握奇智能科技有限公司、北京大明五洲科技有限公司、恒宝股份有限公司、深圳市明华澳汉科技股份有限公司、武汉天喻信息产业股份有限公司、北京飞天诚信科技有限公司、华翔腾数码科技有限公司。本规范主要起草人：石玉平、柳增寿、胡俊义、管延军、项莉、雷继业、胡鹏、赵再兴、段晓毅、刘玉峰、刘伟丰、陈吉、何永福、李高锋、黄东杰、王建承、汪雪林、赵李明。本规范责任专家
9、：刘平、郭宝安。1智能 IC 卡及智能密码钥匙密码应用接口规范1 范围本规范规定了基于 PKI 密码体制的智能 IC 卡及智能密码钥匙密码应用接口，描述了密码应用接口的函数、数据类型、参数的定义和设备的安全要求。本规范适用于智能 IC 卡及智能密码钥匙产品的研制、使用和检测。2 规范性引用文件下列文件中的条款通过本规范的引用而成为本规范的条款。凡是注日期的引用文件，其随后所有的修改单（不包括勘误的内容）或修订版均不适用于本规范，然而，鼓励根据本规范达成协议的各方研究是否可使用这些的最新版本。凡是不注日期的引用文件，其最新版本适用于本规范。GM/T AAAAA SM2 密码使用规范GM/T BB
10、BBB 标识规范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消息鉴别码 messa
11、ge 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 算法
12、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 Ke
13、y 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 椭圆曲线密码算法（Ell
14、iptic 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、文件和容器组成，可以存在多个文件
15、和多个容器。每个应用维护各自的与管理员 PIN 和用户 PIN 相关的权限状态。应用的逻辑结构如图 3 所示。4管理员 P I N用户 P I N文件 1文件 n加密公钥加密私钥签名公钥签名私钥会话密钥 1会话密钥 n容器 1应用结构加密数字证书签名数字证书加密公钥加密私钥签名公钥签名私钥会话密钥 1会话密钥 n容器 n加密数字证书签名数字证书图 3 应用逻辑结构图容器中存放加密密钥对、签名密钥对和会话密钥。其中加密密钥对用于保护会话密钥，签名密钥对用于数字签名和验证，会话密钥用于数据加解密和 MAC 运算。容器中也可以存放与加密密钥对对应的加密数字证书和与签名密钥对对应的签名数字证书。其中，
16、签名密钥对由内部产生，加密密钥对由外部产生并安全导入，会话密钥可由内部产生或者由外部产生并安全导入。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 或FALSEBYT
17、E 字节类型，无符号 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 W
18、ORDDWORD 双字类型，无符号 32 位整数typedef UINT32 DWORDFLAGS 标志类型，无符号 32 位整数typedef UINT32 FLAGSLPSTR 8 位字符串指针，按照 UTF8格式存储及交换typedef CHAR * LPSTRHANDLE 句柄，指向任意数据对象的起始地址typedef void * HANDLEDEVHANDLE 设备句柄 typedef HANDLE DEVHANDLEHAPPLICATION 应用句柄 typedef HANDLE HAPPLICATIONHCONTAINER 容器句柄 typedef HANDLE HCONTAI
19、NER6.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。
