最终版《智能ic卡及智能密码钥匙密码应用接口规范(国密

1、智能 IC 卡及智能密码钥匙 密码应用接口规范 Smart Card and Smart Token Cryptography Application Interface Specification 国家密码管理局 2010 年 4 月 I 目目 次次 前 言 .IV 1范围 .1 2规范性引用文件 .1 3术语和定义 .1 4缩略语 .2 5结构模型 .2 5.1层次关系 .2 5.2设备的应用结构 .3 6数据类型定义 .4 6.1算法标识 .4 6.1.1分组密码算法标识.4 6.1.2非对称密码算法标识.5 6.1.3密码杂凑算法标识.5 6.2基本数据类型 .5 6.3常量定义 .6

2、 6.4复合数据类型 .6 6.4.1版本.6 6.4.2设备信息.6 6.4.3RSA 公钥数据结构.7 6.4.4RSA 私钥数据结构.8 6.4.5ECC 公钥数据结构.8 6.4.6ECC 私钥数据结构.9 6.4.7ECC 密文数据结构.9 6.4.8ECC 签名数据结构.9 6.4.9分组密码参数.10 6.4.10文件属性 .10 6.4.11权限类型.11 6.4.12设备状态 .11 7接口函数 .11 7.1设备管理 .11 7.1.1概述.11 7.1.2等待设备插拔事件.11 7.1.3取消等待设备插拔事件.12 7.1.4枚举设备.12 7.1.5连接设备.12 7.

3、1.6断开连接.12 7.1.7获取设备状态.12 7.1.8设置设备标签.12 7.1.9获取设备信息.13 7.1.10锁定设备 .13 7.1.11解锁设备.13 7.1.12设备命令传输 .13 7.2访问控制 .13 7.2.1概述.13 II 7.2.2修改设备认证密钥.14 7.2.3设备认证.14 7.2.4修改 PIN .14 7.2.5获取 PIN 信息.14 7.2.6校验 PIN .15 7.2.7解锁 PIN .15 7.2.8清除应用安全状态.15 7.3应用管理 .15 7.3.1概述.15 7.3.2创建应用.15 7.3.3枚举应用.16 7.3.4删除应用.

4、16 7.3.5打开应用.16 7.3.6关闭应用.16 7.4文件管理 .17 7.4.1概述.17 7.4.2创建文件.17 7.4.3删除文件.17 7.4.4枚举文件.17 7.4.5获取文件属性.18 7.4.6读文件.18 7.4.7写文件.18 7.5容器管理 .18 7.5.1概述.18 7.5.2创建容器.19 7.5.3删除容器.19 7.5.4打开容器.19 7.5.5关闭容器.19 7.5.6枚举容器.19 7.6密码服务 .20 7.6.1概述.20 7.6.2生成随机数.21 7.6.3生成外部 RSA 密钥对.21 7.6.4生成 RSA 签名密钥对.21 7.6

5、.5导入 RSA 加密密钥对.21 7.6.6RSA 签名.22 7.6.7RSA 验签.22 7.6.8RSA 生成并导出会话密钥.22 7.6.9RSA 外来公钥运算.23 7.6.10RSA 外来私钥运算 .23 7.6.11生成 ECC 签名密钥对.23 7.6.12导入 ECC 加密密钥对 .24 7.6.13ECC 签名 .24 7.6.14ECC 验签 .24 7.6.15ECC 生成并导出会话密钥 .24 7.6.16ECC 外来公钥加密 .25 III 7.6.17ECC 外来私钥解密 .25 7.6.18ECC 外来私钥签名 .25 7.6.19ECC 外来公钥验签 .25

6、 7.6.20ECC 生成密钥协商参数并输出 .26 7.6.21ECC 产生协商数据并计算会话密钥 .26 7.6.22ECC 计算会话密钥 .26 7.6.23导出公钥 .27 7.6.24导入会话密钥 .27 7.6.25明文导入会话密钥 .27 7.6.26加密初始化 .28 7.6.27单组数据加密 .28 7.6.28多组数据加密 .28 7.6.29结束加密 .28 7.6.30解密初始化 .29 7.6.31单组数据解密 .29 7.6.32多组数据解密 .29 7.6.33结束解密 .30 7.6.34密码杂凑初始化 .30 7.6.35单组数据密码杂凑 .30 7.6.36

7、多组数据密码杂凑 .30 7.6.37结束密码杂凑 .31 7.6.38消息鉴别码运算初始化 .31 7.6.39单组数据消息鉴别码运算 .31 7.6.40多组数据消息鉴别码运算 .32 7.6.41结束消息鉴别码运算 .32 7.6.42关闭密码对象句柄 .32 8设备的安全要求 .32 8.1设备使用阶段 .32 8.2权限管理 .32 8.2.1权限分类.32 8.2.2权限使用.32 8.2.3设备认证.33 8.2.4PIN 码安全要求.33 8.3密钥安全要求 .33 8.4设备抗攻击要求 .33 附录 A （规范性附录） 错误代码定义和说明 .34 IV 前前 言言 本规范涉及

8、的密码算法按照国家密码管理部门的要求使用。 本规范的附录 A 为规范性附录。 本规范由国家密码管理局提出并归口。 本规范起草单位：北京海泰方圆科技有限公司、北京握奇智能科技有限公司、北京大明五洲科 技有限公司、恒宝股份有限公司、深圳市明华澳汉科技股份有限公司、武汉天喻信息产业股份有限 公司、北京飞天诚信科技有限公司、华翔腾数码科技有限公司。 本规范主要起草人：石玉平、柳增寿、胡俊义、管延军、项莉、雷继业、胡鹏、赵再兴、段晓 毅、刘玉峰、刘伟丰、陈吉、何永福、李高锋、黄东杰、王建承、汪雪林、赵李明。 本规范责任专家：刘平、郭宝安。 1 智能 IC 卡及智能密码钥匙密码应用接口规范 1 1范围范围

9、 本规范规定了基于 PKI 密码体制的智能 IC 卡及智能密码钥匙密码应用接口，描述了密码应用 接口的函数、数据类型、参数的定义和设备的安全要求。 本规范适用于智能 IC 卡及智能密码钥匙产品的研制、使用和检测。 2 2规范性引用文件规范性引用文件 下列文件中的条款通过本规范的引用而成为本规范的条款。凡是注日期的引用文件，其随后所 有的修改单（不包括勘误的内容）或修订版均不适用于本规范，然而，鼓励根据本规范达成协议的 各方研究是否可使用这些的最新版本。凡是不注日期的引用文件，其最新版本适用于本规范。 GB/T AAAAA公钥密码基础设施应用技术体系 SM2 算法使用规范 3 3术语术语和定义和

10、定义 以下术语和定义适用于本规范。 3.13.1 应用应用 applicationapplication 包括容器、设备认证密钥和文件的一种结构，具备独立的权限管理。 3.23.2 容器容器 containercontainer 特指密钥容器，是一个用于存放非对称密钥对和会话密钥的逻辑对象。 3.33.3 设备设备 devicedevice 智能 IC 卡及智能密码钥匙的统称。 3.43.4 设备认证设备认证 devicedevice authenticationauthentication 智能 IC 卡或智能密码钥匙对应用程序的认证。 3.53.5 设备认证密钥设备认证密钥 deviced

11、evice authenticationauthentication keykey 用于设备认证的密钥。 3.63.6 设备标签设备标签 labellabel 设备的别名，可以由用户进行设定并存储于设备内部。 3.73.7 消息鉴别码消息鉴别码 messagemessage authenticationauthentication codecode (MAC)(MAC) 消息鉴别算法的输出。 3.83.8 管理员管理员 PINPIN AdministratorAdministrator PINPIN 管理员的密码，为ASCII字符串。 3.93.9 用户用户 PINPIN UserUser P

12、INPIN 用户的个人密码，为 ASCII 字符串。 3.103.10 智能智能 ICIC 卡卡 smartsmart cardcard 含 CPU 的 IC 卡，这里指能完成密码功能的 IC 卡。 2 3.113.11 智能密码钥匙智能密码钥匙 smartsmart tokentoken 能完成密码功能和安全存储的终端密码产品，一般采用 USB 接口。 3.123.12 SM1SM1 算法算法 SM1SM1 algorithmalgorithm 一种国家商用密码分组加密算法，分组长度为128比特，密钥长度为128比特。 3.133.13 SM2SM2 算法算法 SM2SM2 algorith

13、malgorithm 一种国家商用密码非对称密码算法，密钥长度为256比特。 3.143.14 SM3SM3 算法算法 SM3SM3 algorithmalgorithm 一种国家商用密码密码杂凑算法，输出长度为256比特。 3.153.15 SMS4SMS4 算法算法 SMS4SMS4 algorithmalgorithm 一种国家商用密码分组加密算法，分组长度为128比特，密钥长度为128比特。 3.163.16 SSF33SSF33 算法算法 SSF33SSF33 algorithmalgorithm 一种国家商用密码分组加密算法，分组长度为128比特，密钥长度为128比特。 4 4缩略

14、语缩略语 下列缩略语适用于本规范： 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个人身份识别码（P

15、ersonal Identification Number) MAC消息鉴别码（Message Authentication Code） ECC椭圆曲线密码算法（Elliptic Curve Cryptography） 5 5结构模型结构模型 5.15.1 层次关系层次关系 智能 IC 卡及智能密码钥匙密码应用接口位于智能 IC 卡及智能密码钥匙应用程序与设备之间， 如图 1 所示。 3 智能IC卡及智能密码钥匙应用程序 智能IC卡及智能密码钥匙密码应用接口 智能IC卡及智能密码钥匙设备驱动 设备1设备2设备n 图 1 接口在应用层次关系中的位置 5.25.2 设备的应用结构设备的应用结构 一

16、个设备中存在设备认证密钥和多个应用，应用之间相互独立。设备的逻辑结构如图 2 所示。 设备认证密钥 应应用用1 1 应应用用n n 图 2 设备逻辑结构 应用由管理员 PIN、用户 PIN、文件和容器组成，可以存在多个文件和多个容器。 每个应用维护各自的与管理员 PIN 和用户 PIN 相关的权限状态。 应用的逻辑结构如图 3 所示。 4 管理员PIN 用户PIN 文件1 文件n 加密公钥 加密私钥 签名公钥 签名私钥 会话密钥1 会话密钥n 容器1 加密公钥 加密私钥 签名公钥 签名私钥 会话密钥1 会话密钥n 容器n 应用结构 图 3 应用逻辑结构图 容器中存放加密密钥对、签名密钥对和会话

17、密钥。其中加密密钥对用于保护会话密钥，签名密 钥对用于数字签名和验证，会话密钥用于数据加解密和 MAC 运算。其中，签名密钥对由内部产生， 加密密钥对由外部产生并安全导入，会话密钥可由内部产生或者由外部产生并安全导入。 6 6数据类型定义数据类型定义 6.16.1 算法标识算法标识 6.1.16.1.1分组密码算法标识分组密码算法标识 分组密码算法标识包含密码算法的类型和加密模式。 分组密码算法标识的编码规则为：从低位到高位，第 0 位到第 7 位按位表示分组密码算法工作 模式，第 8 位到第 31 位按位表示分组密码算法类型，分组密码算法的标识如表 1 所示。 表 1 分组密码算法标识表 标

18、签标签标识符标识符描述描述 SGD_SM1_ECB0 x00000101 SM1 算法 ECB 加密模式 SGD_SM1_CBC0 x00000102 SM1 算法 CBC 加密模式 SGD_SM1_CFB0 x00000104 SM1 算法 CFB 加密模式 SGD_SM1_OFB0 x00000108 SM1 算法 OFB 加密模式 SGD_SM1_MAC0 x00000110 SM1 算法 MAC 运算 SGD_SSF33_ECB0 x00000201 SSF33 算法 ECB 加密模式 5 SGD_SSF33_CBC0 x00000202 SSF33 算法 CBC 加密模式 SGD_S

19、SF33_CFB0 x00000204 SSF33 算法 CFB 加密模式 SGD_SSF33_OFB0 x00000208 SSF33 算法 OFB 加密模式 SGD_SSF33_MAC0 x00000210 SSF33 算法 MAC 运算 SGD_SMS4_ECB0 x00000401 SMS4 算法 ECB 加密模式 SGD_SMS4_CBC0 x00000402 SMS4 算法 CBC 加密模式 SGD_SMS4_CFB0 x00000404 SMS4 算法 CFB 加密模式 SGD_SMS4_OFB0 x00000408 SMS4 算法 OFB 加密模式 SGD_SMS4_MAC0

20、x00000410 SMS4 算法 MAC 运算 6.1.26.1.2非对称密码算法标识非对称密码算法标识 非对称密码算法标识仅定义了密码算法的类型，在使用非对称算法进行数字签名运算时，可将 非对称密码算法标识符与密码杂凑算法标识符进行“或”运算后使用，如“RSA with SHA1”可表 示为 SGD_RSA | SGD_SHA1，即 0 x00010002， “|”表示“或”运算。 非对称密码算法标识的编码规则为：从低位到高位，第 0 位到第 7 位为 0，第 8 位到第 15 位 按位表示非对称密码算法的算法协议，如果所表示的非对称算法没有相应的算法协议则为 0，第 16 位到第 31

21、位按位表示非对称密码算法类型，非对称密码算法的标识如表 2 所示。 表 2 非对称密码算法标识表 标签标签标识符标识符描述描述 SGD_RSA0 x00010000 RSA 算法 SGD_SM2_10 x00020100 椭圆曲线签名算法 SGD_SM2_20 x00020200 椭圆曲线密钥交换协议 SGD_SM2_30 x00020400 椭圆曲线加密算法 6.1.36.1.3密码杂凑算法标识密码杂凑算法标识 密码杂凑算法标识符可以在进行密码杂凑运算或计算 MAC 时应用，也可以与非对称密码算法标 识符进行“或”运算后使用，表示签名运算前对数据进行密码杂凑运算的算法类型。 密码杂凑算法标识

22、的编码规则为：从低位到高位，第 0 位到第 7 位表示密码杂凑算法，第 8 位 到第 31 位为 0，密码杂凑算法的标识如表 3 所示。 表 3 密码杂凑算法标识表 标签标签标识符标识符描述描述 SGD_SM30 x00000001 SM3 密码杂凑算法 SGD_SHA10 x00000002 SHA1 密码杂凑算法 SGD_SHA2560 x00000004 SHA256 密码杂凑算法 6.26.2 基本数据类型基本数据类型 本规范中的字节数组均为高位字节在前（Big-Endian）方式存储和交换。基本数据类型定义如 表 4 所示： 表 4 基本数据类型 类型名称类型名称描述描述定义定义 I

23、NT8 有符号 8 位整数 INT16 有符号 16 位整数 INT32 有符号 32 位整数 UINT8 无符号 8 位整数 UINT16 无符号 16 位整数 UINT32 无符号 32 位整数 6 BOOL 布尔类型，取值为 TRUE 或 FALSE BYTE 字节类型，无符号 8 位整数 typedef UINT8 BYTE CHAR 字符类型，无符号 8 位整数 typedef UINT8 CHAR SHORT 短整数，有符号 16 位 typedef INT16 SHORT USHORT 无符号 16 位整数 typedef UINT16 USHORT LONG 长整数，有符号 3

24、2 位整数 typedef INT32 LONG ULONG 长整数，无符号 32 位整数 typedef UINT32 ULONG UINT 无符号 32 位整数 typedef UINT32 UINT WORD 字类型，无符号 16 位整数 typedef UINT16 WORD DWORD 双字类型，无符号 32 位整 数 typedef UINT32 DWORD FLAGS 标志类型，无符号 32 位整 数 typedef UINT32 FLAGS LPSTR 8 位字符串指针，按照 UTF8 格式存储及交换 typedef CHAR * LPSTR HANDLE 句柄，指向任意数据对

25、象的 起始地址 typedef void * HANDLE DEVHANDLE 设备句柄 typedef HANDLE DEVHANDLE HAPPLICATION 应用句柄 typedef HANDLE HAPPLICATION HCONTAINER 容器句柄 typedef HANDLE HCONTAINER 6.36.3 常量定义常量定义 数据常量标识定义了在规范中用到的常量的取值。 数据常量标识的定义如表 5 所示。 表 5 常量定义 常量名常量名取值取值描述描述 TRUE0 x00000001 布尔值为真 FALSE0 x00000000 布尔值为假 DEVAPI_stdcall _

26、stdcall 函数调用方式 ADMIN_TYPE0 管理员 PIN 类型 USER_TYPE1 用户 PIN 类型 6.46.4 复合数据类型复合数据类型 6.4.16.4.1版本版本 （1）类型定义 typedef struct Struct_Version BYTE major; BYTE minor; VERSION; （2）数据项描述参见表 6： 表 6版本定义 数据项数据项类型类型意义意义备注备注 majorBYTE 主版本号 minorBYTE 次版本号 主版本号和次版本号以“.”分隔，例如 Version 1.0，主版本号为 1，次版本号为 0；Version 2.10，主 版

27、本号为 2，次版本号为 10。 6.4.26.4.2设备信息设备信息 7 （1）类型定义 typedef struct Struct_DEVINFO VERSIONVersion; CHARManufacturer64; CHARIssuer64; CHARLabel32; CHARSerialNumber32; VERSIONHWVersion; VERSIONFirmwareVersion; ULONGAlgSymCap; ULONGAlgAsymCap; ULONGAlgHashCap; ULONGDevAuthAlgId; ULONGTotalSpace; ULONGFreeSpace

28、; BYTE Reserved64; DEVINFO,*PDEVINFO; （2）数据项描述参见表 7： 表 7设备信息描述 数据项数据项类型类型意义意义备注备注 VersionVERSION 版本号数据结构版本号，本结构的版本号 为 1.0 Manufacturer CHAR 数组设备厂商信息以 0为结束符的 ASCII 字符 串 Issuer CHAR 数组发行厂商信息以 0为结束符的 ASCII 字符 串 Label CHAR 数组设备标签以 0为结束符的 ASCII 字符 串 SerialNumber CHAR 数组序列号以 0为结束符的 ASCII 字符 串 HWVersionVER

29、SION 设备硬件版本 FirmwareVersionVERSION 设备本身固件版本 AlgSymCapULONG 分组密码算法标识 AlgAsymCapULONG 非对称密码算法标识 AlgHashCapULONG 密码杂凑算法标识 DevAuthAlgIdULONG 设备认证使用的分组 密码算法标识 TotalSpaceULONG 设备总空间大小 FreeSpaceULONG 用户可用空间大小 ReservedBYTE 保留扩展 6.4.36.4.3RSARSA 公钥数据结构公钥数据结构 （1）类型定义 typedef struct Struct_RSAPUBLICKEYBLOB ULO

30、NGAlgID; ULONGBitLen; 8 BYTEModulusMAX_RSA_MODULUS_LEN; BYTEPublicExponentMAX_RSA_EXPONENT_LEN; RSAPUBLICKEYBLOB, *PRSAPUBLICKEYBLOB; MAX_RSA_MODULUS_LEN 为算法模数的最大长度； MAX_RSA_EXPONENT_LEN 为算法指数的最大长度。 （2）数据项描述参见表 8： 表 8RSA 公钥数据结构 数据项数据项类型类型意义意义备注备注 AlgIDULONG 算法标识号 BitLenULONG 模数的实际位长度必须是 8 的倍数 Modulu

31、s BYTE 数组模数 n = p * q实际长度为 BitLen/8 字节 #define MAX_RSA_MODULUS_LEN 256 #define MAX_RSA_EXPONENT_LEN 4 PublicExponent BYTE 数组公开密钥 e一般为 00010001 6.4.46.4.4RSARSA 私钥数据结构私钥数据结构 （1）类型定义 typedef struct Struct_RSAPRIVATEKEYBLOB ULONGAlgID; ULONGBitLen; BYTEModulusMAX_RSA_MODULUS_LEN; BYTEPublicExponentMAX_

32、RSA_EXPONENT_LEN; BYTEPrivateExponentMAX_RSA_MODULUS_LEN; BYTEPrime1MAX_RSA_MODULUS_LEN/2; BYTEPrime2MAX_RSA_MODULUS_LEN/2; BYTEPrime1ExponentMAX_RSA_MODULUS_LEN/2; BYTEPrime2ExponentMAX_RSA_MODULUS_LEN/2; BYTECoefficientMAX_RSA_MODULUS_LEN/2; RSAPRIVATEKEYBLOB, *PRSAPRIVATEKEYBLOB; MAX_RSA_MODULUS_

33、LEN 为 RSA 算法模数的最大长度； （2）数据项描述参见表 9： 表 9RSA 私钥数据结构 数据项数据项类型类型意义意义备注备注 AlgIDULONG 算法标识号 BitLenULONG 模数的实际位长度必须是 8 的倍数 Modulus BYTE 数组模数 n = p * q实际长度为 BitLen/8 字节 PublicExponent BYTE 数组公开密钥 e一般为 00010001 PrivateExponent BYTE 数组私有密钥 d实际长度为 BitLen/8 字节 Prime1 BYTE 数组素数 p实际长度为 BitLen/16 字节 Prime2 BYTE 数组

34、素数 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.56.4.5ECCECC 公钥数据结构公钥数据结构 （1）类型定义 typedef struct Struct_ECCPUBLICKEYBLOB 9 ULONGBitLen; BYTEXCoordinateECC_MAX_XCOO

35、RDINATE_BITS_LEN/8; BYTEYCoordinateECC_MAX_YCOORDINATE_BITS_LEN/8; ECCPUBLICKEYBLOB, *PECCPUBLICKEYBLOB; ECC_MAX_XCOORDINATE_LEN 为 ECC 算法 X 坐标的最大长度； ECC_MAX_YCOORDINATE_LEN 为 ECC 算法 Y 坐标的最大长度。 （2）数据项描述参见表 10： 表 10 ECC 公钥数据结构 数据项数据项类型类型意义意义备注备注 BitLenULONG 模数的实际 位长度 必须是 8 的倍数 XCoordinate BYTE 数组曲线上点的 X 坐标 有限域上的整数 #define ECC_MAX_XCOORDINATE_BITS_LEN 512 YCoordinate BYTE 数组曲线上点的 Y 坐标 有限域上的整数 #define ECC_MAX_YCOORDINATE_BITS_LEN 512 6.4.66.4.6ECCECC 私钥数据结构私钥数据结构