1、 ICS ICS 35.04035.040 L L 8080 备案号：备案号：GM/T 00560056-20182018 多应用载体密码应用接口规范 Specification of cryptography application interface with multi-applications equipment （报批稿）2018-05-02 发布 2018-05-02 实施 国家密码管理局国家密码管理局 发 布发 布 中 华 人 民 共 和 国 密 码 行 业 标 准中 华 人 民 共 和 国 密 码 行 业 标 准 GM/T 0056-2018 I 目 次 前言.II 引言.II
2、I 1 范围.1 2 规范性引用文件.1 3 术语和定义.1 4 符号和缩略语.2 5 多应用载体系统框架.2 6 多应用载体密码应用接口调用流程.3 6.1 密码应用接口调用流程.3 6.2 密码算法能力标识.4 6.3 密码应用接口规格.4 7 Java 技术方案密码应用接口.5 7.1 简介.5 7.2 密码算法能力标识.5 7.3 密码应用包定义.6 7.4 密码应用接口定义.6 7.5 密码应用类信息.6 附录 A（资料性附录）多应用安全管理的密码应用要求.29 A.1 简介.29 A.2 密码算法标识获取.30 A.3 安全通道的密码应用规则.30 A.3.1 SCP02 安全通道
3、.30 A.3.2 SCP11 安全通道.31 A.4 CAP 包签名与校验.31 A.5 应用管理授权令牌.31 A.5.1 下载令牌.32 A.5.2 安装令牌.32 A.5.3 迁移令牌.32 A.5.4 删除令牌.32 A.6 委托管理收条.33 附录 B 多应用安全管理的证书格式.34 B.1 多应用安全管理证书格式.34 参考文献.36 GM/T 0056-2018 II 前 言 本标准依据GB/T 1.1-2009给出的规则起草。请注意本文件的某些内容可能涉及专利，本文件的发布机构不承担识别这些专利的责任。本标准由密码行业标准化技术委员会提出并归口。本标准起草单位：北京中电华大电
4、子设计有限责任公司、上海华虹集成电路有限责任公司、北京同方微电子有限公司、恒宝股份有限公司、北京握奇数据系统有限公司、东信和平科技股份有限公司、北京华大智宝电子系统有限公司、上海复旦微电子集团股份有限公司、国民技术股份有限公司、北京南瑞智芯微电子科技有限公司、成都信息工程大学、武汉天喻信息产业股份有限公司、华大半导体有限公司。本标准主要起草人：兰天、吴秉男、苑中魁、袁巧、陈操、刘平、王庆林、王怀英、耿佳、白长虹、汪雪琳、张楠、王永吉、李志远、陈悦、李静进、何迪、赵永刚、王宝鸫、陈安新、吴震、饶金涛、黄惠瑜、许晶、刘欣。GM/T 0056-2018 III 引 言 本文中多应用载体是指具备独立、
5、开放的片上操作系统、提供多应用运行环境、支持载体上多个应用的下载、安装、重用、共存和安全隔离的载体，通常由硬件、驱动、COS和应用构成。多应用载体中的用户应用在使用SM2/3/4系列算法时，需要载体的多应用环境提供SM2/3/4系列算法的密码应用调用接口。由于目前多应用载体相关标准未定义SM2/3/4系列算法的应用接口，造成用户应用无法使用的问题。为此，编制本标准以规范SM2/3/4系列算法在多应用载体中的密码算法能力标识、接口规格，保障用户应用使用密码功能的统一性和完整性。多应用载体可以使用不同的技术方案实现，如Java技术方案、C技术方案等。本版本主要描述了Java技术方案中的密码应用接口
6、，其他技术方案的密码应用接口根据应用发展情况在后续版本中给出。GM/T 0056-2018 1 多应用载体密码应用接口规范 1 范围 本标准规定了多应用载体中SM2/3/4系列算法的密码应用接口，包括：-定义SM2/SM3/SM4算法在多应用载体中的标识。-定义SM2/SM3/SM4的算法的密码应用接口规格。本标准适用于各种多应用载体的研制，也可用于指导多应用载体的密码应用检测。2 规范性引用文件 下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅注日期的版本适用于本文件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。GB/T 32905-2016 信息安全技
7、术 SM3密码杂凑算法 GB/T 32907-2016 信息安全技术 SM4分组密码算法 GB/T 32918-2016 信息安全技术 SM2椭圆曲线公钥密码算法 RFC 2898 Specification of PKCS#5 3 术语和定义 下列术语和定义适用于本文件。3.1 命令 command 终端向载体发出的一条信息，该信息启动一个操作或请求一个应答。3.2 响应 response 载体处理完成收到的命令报文后，回送给终端的报文。3.3 报文 message 由终端向载体或载体向终端发出的，不含传输控制字符的字节串。3.4 多应用载体 multi-applications equip
8、ment 本文中指具备独立、开放的片上操作系统、提供多应用运行环境、支持载体上多个应用的下载、安装、重用、共存和安全隔离的载体，通常由硬件、驱动、COS和应用构成。3.5 GM/T 0056-2018 2 SM2算法 SM2 algorithm 由GB/T 32918定义的一种算法。3.6 SM3算法 SM3 algorithm 由GB/T 32905定义的一种算法。3.7 SM4算法 SM4 algorithm 由GB/T 32907定义的一种算法。3.8 SM9算法 SM9 algorithm 一种采用双线性对的椭圆曲线公钥密码算法。4 符号和缩略语 下列符号和缩略语适用于本文件。AID
9、应用标识符（Application Identifier）AKEY 辅助密钥（Auxiliary Key）API 应用编程接口（Application Programming Interface）CBC 链式加密（Cipher-block chaining）COS 片上操作系统（Chip Operating System）ECB 电子密码本（Electronic Codebook）ISO 国际标准化组织（International Organization for Standardization）MAC 消息鉴别码（Message Authentication Code）MKEY 报文密钥（M
10、essage Key）OFB 输出反馈（Output Feedback）5 多应用载体系统框架 多应用载体由硬件层、驱动层、OS层、应用层构成，详见图1。GM/T 0056-2018 3 接口驱动载体操作系统内核密码算法库用户应用1用户应用n应用层OS层驱动层芯片硬件硬件层密码应用接口多应用安全管理环境其他系统应用接口 图1 多应用载体安系统框架 其中硬件层是芯片，包括CPU、密码算法协处理器、存储器等。驱动层包括各芯片硬件的接口驱动、以及和密码算法协处理器配套的算法库。OS层包括支持多应用调度的载体操作系统内核,向应用层提供的系统应用接口，以及密码应用接口。应用层包括多应用安全管理环境以及各
11、种用户应用。多应用安全管理环境是一个特定的用户级别程序，用于实现多应用的安全管理和安全隔离；用户应用实现各种业务应用功能。应用层通过OS层的密码应用接口实现密码功能的调用。6 多应用载体密码应用接口调用流程 6.1 密码应用接口调用流程 多应用载体中，调用密码应用接口的流程如图2所示：GM/T 0056-2018 4 上位机软件安全载体上的用户应用多应用载体操作系统密码应用接口a.获得载体支持的算法能力b.返回载体支持的算法能力支持密码算法c.调用用户应用(使用密码算法)流程结束处理调用命令调用密码功能d.调用密码应用APIe.返回密码应用调用结果f.返回用户应用调用结果流程结束算法处理不支持
12、支持 图2 多应用载体密码应用接口调用流程 上位机软件是载体外的客户端软件，用户应用是在安全载体内运行的、实现密码安全功能嵌入式软件。用户应用调用密码算法的流程说明如下：a）获得载体算法能力：上位机软件使用多应用载体的基本命令，获取载体上的算法能力，该命令和载体上的用户应用无关。该步骤为可选步骤，如果上位机软件已知该载体的算法能力，可以跳过该步骤。b）返回算法能力：多应用载体操作系统返回载体支持的算法能力。如果载体算法能力和上位机不匹配，流程结束。如果匹配，转c。该步骤为可选步骤，如果客户端软件已知该载体的算法能力，可以跳过该步骤。c）调用密码应用接口：如果载体支持密码算法，上位机软件调用载体
13、上的用户应用。载体上用户应用收到调用命令后，根据命令进行处理。d）调用密码应用接口：如果该命令的处理需要使用密码功能，通过载体操作系统的密码应用接口进行调用。e）返回密码应用接口调用结果：密码应用API被调用后，进行算法处理并向载体上的用户应用返回处理结果。f）返回应用调用结果：载体上的用户应用向上位机软件返回调用结果。流程结束。6.2 密码算法能力标识 多应用载体应对所支持的密码算法能力进行标识，以便于载体外实体获得载体算法支持情况。由于多应用载体可以使用不同的技术方案实现，如Java技术方案、C技术方案等，相应技术方案的算法能力标识参见第7章。6.3 密码应用接口规格 GM/T 0056-
14、2018 5 多应用载体中应定义密码应调用的接口规格，以便于载体上的用户应用调用。由于安全载体在实现中使用不同的技术方案，如Java技术方案、C技术方案等，相应技术方案的调用接口规格参见第7章。7 Java 技术方案密码应用接口 7.1 简介 本部分描述了使用Java技术方案的多应用载体中，SM2/3/4系列算法的能力标识和应用接口规格定义，使用SM2/3/4系列算法的应用可以调用这些应用接口以达到对密码功能的使用。密码算法中的密钥对象需通过GMKeyBuilder.buildKey方法创建密钥实例，然后通过setXXX等方法设置密钥对象所使用的密钥值，签名算法、加解密算法将使用这些密钥对象。
15、对称密钥对象包括：SM4Key，非对称密钥对象包括：SM2PrivateKey、SM2PublicKey。签 名 与 验 证 算 法 是 通 过 GMSignature 类 实 现 的，在 使 用 签 名 与 验 证 算 法 前 需 要 通 过GMSignature.getInstance方法获得相应算法的实例对象，再配合相应的密钥对象以实现生成签名数据与验证签名数据的目的。数 据 加 解 密 算 法 是 通 过 GMCipher 类 实 现 的，在 使 用 数 据 加 解 密 算 法 前 需 要 通 过GMCipher.getInstance方法获得相应算法的实例对象，再配合相应的密钥对象以
16、实现对数据加密或解密的目的。数 据 杂 凑 算 法 是 通 过 GMMessageDigest 类 实 现 的，在 使 用 数 据 杂 凑 算 法 前 需 要 通 过GMMessageDigest.getInstance方法获得SM3算法的实例对象，然后才可对数据进行杂凑计算。密码算法API中定义了GMKeyPair类，用于在载体内生成密码算法中的非对称密钥对（SM2）。7.2 密码算法能力标识 多应用载体密码算法能力标识定义见表1。表1 密码算法能力标识 标识 对应密码算法能力 0 x00 0 x0F 保留 0 x10 0 x17 保留 0 x18 SM4_ECB 0 x19 SM4_CBC
17、 0 x1A SM4_OFB 0 x1B 保留 0 x1C-0 x1F 保留 0 x20 SM3_256 0 x21 0 x27 保留 0 x28 SM2_256 0 x29-0 x2F 保留 0 x30 SM9_256 0 x31 0 xFF 保留 GM/T 0056-2018 6 7.3 密码应用包定义 密码应用包定义见表2。表2 包信息 项 定义 包名 com.guomi AID 0 xA0:0 x0:0 x0:0 x0:0 x0:0 x53:0 x43:0 x43:0 x41:0 x01 主版本号 1 次版本号 0 7.4 密码应用接口定义 7.4.1 类定义 密码应用类定义如下。cl
18、ass java.lang.Object class com.guomi.GMCipherGMCipher class com.guomi.GMKeyBuilderGMKeyBuilder class com.guomi.GMKeyPairGMKeyPair class com.guomi.GMMessageDigestGMMessageDigest class com.guomi.GMSignatureGMSignature class com.guomi.GMCipherExtendGMCipherExtend class com.guomi.GMSM2KeyExchangeGMSM2Ke
19、yExchange 7.4.2 接口定义 密码应用接口定义如下。interface javacard.security.Key interface javacard.security.SecretKey interface com.guomi.SM4KeySM4Key interface javacard.security.PrivateKey interface com.guomi.SM2PrivateKeySM2PrivateKey interface javacard.security.PublicKey interface com.guomi.SM2PublicKeySM2Public
20、Key interface com.guomi.SM2Key interface com.guomi.SM2PrivateKeySM2PrivateKey interface com.guomi.SM2PSM2PublicublicKeyKey 7.5 密码应用类信息 7.5.1 SM4Key 7.5.1.1 概述 SM4Key包含一个16字节的密钥AKEY，用于SM4算法的加解密运算。GM/T 0056-2018 7 一旦密钥数据被设置，该密钥对象就将处于初始化完成状态（isInitialized方法将返回true），该密钥可以被使用了。SM4Key接口定义见表3。表3 SM4Key 返回值
21、 定义 说明 byte getKey(byte keyData,short kOff)获得密钥引用 void setKey(byte keyData,short kOff)设置密钥数据 7.5.1.2 setKey 7.5.1.2.1 声明 public abstract void setKey(byte keyData,short kOff)throws CryptoException,NullPointerException,ArrayIndexOutOfBoundsException;7.5.1.2.2 描述 本方法用于设置SM4密钥数据。输入的密钥数据长度为16字节。数据格式为大端并且
22、右对齐，即最低有效位为最后那个字节的最低有效位。7.5.1.2.3 参数 keyData -此byte数组存放待设置的密钥数据。kOff -密钥数据在byte数组中的起始位置。7.5.1.2.4 抛出异常 CryptoException.ILLEGAL_VALUE -密码数据需要解密而且解密出错时抛出该异常。NullPointerException -keyData参数为null时抛出该异常。ArrayIndexOutOfBoundsException -kOff参数为负数或者超过keyData数组时，或者kOff加上密钥数据长度超出keyData数据长度时，抛出该异常。7.5.1.3 get
23、Key 7.5.1.3.1 声明 public abstract byte getKey(byte keyData,short kOff)throws CryptoException,NullPointerException,ArrayIndexOutOfBoundsException;7.5.1.3.2 描述 本方法获得的SM4密钥引用。密钥引用指向的数据长度为16字节。数据格式为大端并且右对齐，即最低有效位为最后那个字节的最低有效位。GM/T 0056-2018 8 7.5.1.3.3 参数 keyData -此byte数组存放返回的密钥数据。kOff -密钥数据在byte数组中的起始位置
24、。7.5.1.3.4 返回值 以字节计的密钥数据的长度。7.5.1.3.5 抛出异常 CryptoException.UNINITIALIZED_KEY-密钥对象没有正确初始化时。NullPointerException -keyData参数为null时。ArrayIndexOutOfBoundsException -kOff参数为负数或者超过keyData数组时，或者kOff加上密钥数据长度超出keyData数据长度时，抛出该异常。7.5.2 SM2Key 7.5.2.1 概述 SM2Key是非对称密钥的一种，分为公钥和私钥，用于SM2算法的运算。SM2Key接口定义见表4。表4 SM2Ke
25、y 返回值 定义 说明 short getA(byte buffer,short offset)获得曲线参数A short getB(byte buffer,short offset)获得曲线参数B short getG(byte buffer,short offset)获得曲线参数G 7.5.2.2 getA 7.5.2.2.1 声明 public short getA(byte buffer,short offset)throws CryptoException,NullPointerException,ArrayIndexOutOfBoundsException;7.5.2.2.2 描述
26、 本方法用于获取曲线参数A的数据。输出的数据长度为32字节。数据格式为大端并且右对齐，即最低有效位为最后那个字节的最低有效位。7.5.2.2.3 参数 buffer -此byte数组存放输出的数据。offset -数据在byte数组中的起始位置。7.5.2.2.4 返回值 GM/T 0056-2018 9 以字节计的曲线参数A的数据长度。7.5.2.2.5 抛出异常 CryptoException.UNINITIALIZED_KEY-密钥处于未初始化状态时抛出该异常。NullPointerException -keyData参数为null时抛出该异常。ArrayIndexOutOfBounds
27、Exception -offset参数为负数或者超过buffer数组时，或者offset加上曲线参数A长度超出buffer数据长度时，抛出该异常。7.5.2.3 getB 7.5.2.3.1 声明 public short getB(byte buffer,short offset)throws CryptoException,NullPointerException,ArrayIndexOutOfBoundsException;7.5.2.3.2 描述 本方法用于获取曲线参数B的数据。输出的数据长度为32字节。数据格式为大端并且右对齐，即最低有效位为最后那个字节的最低有效位。7.5.2.3.
28、3 参数 buffer -此byte数组存放输出的数据。offset -数据在byte数组中的起始位置。7.5.2.3.4 返回值 以字节计的曲线参数B的数据长度。7.5.2.3.5 抛出异常 CryptoException.UNINITIALIZED_KEY-密钥处于未初始化状态时抛出该异常。NullPointerException -buffer参数为null时抛出该异常。ArrayIndexOutOfBoundsException -offset参数为负数或者超过buffer数组时，或者offset加上曲线参数B长度超出keyData数据长度时，抛出该异常。7.5.2.4 getG 7.
29、5.2.4.1 声明 public short getG(byte buffer,short offset)throws CryptoException,NullPointerException,ArrayIndexOutOfBoundsException;7.5.2.4.2 描述 本方法用于获取曲线参数G的数据。输出的数据长度为64字节,前32字节为G值x坐标，后32字节为y坐标。数据格式为大端并且右对齐，即最低有效位为最后那个字节的最低有效位。GM/T 0056-2018 10 7.5.2.4.3 参数 buffer -此byte数组存放输出的数据。offset -数据在byte数组中的起
30、始位置。7.5.2.4.4 返回值 以字节计的曲线参数G的数据长度。非压缩格式，返回的G值格式为x坐标和y坐标内容，前面不包含标识信息。7.5.2.4.5 抛出异常 CryptoException.UNINITIALIZED_KEY-密钥处于未初始化状态时抛出该异常。NullPointerException -buffer参数为null时抛出该异常。ArrayIndexOutOfBoundsException -offset参数为负数或者超过buffer数组时，或者offset加上曲线参数G长度超出buffer数据长度时，抛出该异常。7.5.3 SM2PrivateKey 7.5.3.1 概述
31、 SM2PrivateKey接口用于生成数据的签名。由于SM2算法曲线方程和参数已经固定，一旦私钥数据被设置，该私钥对象就将处于初始化完成状态（isInitialized方法将返回true），该密钥可以被使用了。SM2PrivateKey接口定义见表5。表5 SM2PrivateKey 返回值 定义 说明 short getS(byte buffer,short offset)获得私钥数据 void setS(byte buffer,short offset,short length)设置私钥数据 7.5.3.2 getS 7.5.3.2.1 声明 public short getS(byte
32、 buffer,short offset)throws CryptoException,NullPointerException,ArrayIndexOutOfBoundsException;7.5.3.2.2 描述 本方法获得的SM2私钥数据。输出的私钥引用数据长度为32字节。数据格式为大端并且右对齐，即最低有效位为最后那个字节的最低有效位。7.5.3.2.3 参数 buffer -此byte数组存放返回的私钥数据。offset -数据在byte数组中的起始位置。GM/T 0056-2018 11 7.5.3.2.4 返回值 以字节计的私钥数据的长度，本规范中固定为32。7.5.3.2.5
33、抛出异常 CryptoException.UNINITIALIZED_KEY-密钥处于未初始化状态时抛出该异常。NullPointerException -buffer参数为null时抛出该异常。ArrayIndexOutOfBoundsException -offset参数为负数或者超过buffer数组时，或者offset加上密钥数据长度超出buffer数据长度时，抛出该异常。7.5.3.3 setS 7.5.3.3.1 声明 public void setS(byte buffer,short offset short length)throws CryptoException,NullPointerException,ArrayIndexOutOfBoundsException;7.5.3.3.2 描述 本方法用于设置SM2私钥数据。输入的私钥引用数据长度为32字节。数据格式为大端并
