GM/T 0056-2018 多应用载体密码应用接口规范

犐犆犛３５．０４０

犔８０

GM/T0056—2018

多应用载体密码应用接口规范

Specificationofcryptographyapplicationinterfacewithmulti-

applicationsequipment

2018-05-02发布2018-05-02实施

GM/T0056-2018

目次

前言II

引言III

1范围1

2规范性引用文件1

3术语和定义1

4符号和缩略语2

5多应用载体系统框架2

6多应用载体密码应用接口调用流程3

6.1密码应用接口调用流程3

6.2密码算法能力标识4

6.3密码应用接口规格4

7Java技术方案密码应用接口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.1SCP02安全通道30

A.3.2SCP11安全通道31

A.4CAP包签名与校验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

I

GM/T0056-2018

前言

本标准依据GB/T1.1-2009给出的规则起草。

请注意本文件的某些内容可能涉及专利，本文件的发布机构不承担识别这些专利的责任。

本标准由密码行业标准化技术委员会提出并归口。

本标准起草单位：北京中电华大电子设计有限责任公司、上海华虹集成电路有限责任公司、北京同

方微电子有限公司、恒宝股份有限公司、北京握奇数据系统有限公司、东信和平科技股份有限公司、北

京华大智宝电子系统有限公司、上海复旦微电子集团股份有限公司、国民技术股份有限公司、北京南瑞

智芯微电子科技有限公司、成都信息工程大学、武汉天喻信息产业股份有限公司、华大半导体有限公司。

本标准主要起草人：兰天、吴秉男、苑中魁、袁巧、陈操、刘平、王庆林、王怀英、耿佳、白长虹、

汪雪琳、张楠、王永吉、李志远、陈悦、李静进、何迪、赵永刚、王宝鸫、陈安新、吴震、饶金涛、黄

惠瑜、许晶、刘欣。

II

GM/T0056-2018

引言

本文中多应用载体是指具备独立、开放的片上操作系统、提供多应用运行环境、支持载体上多个应

用的下载、安装、重用、共存和安全隔离的载体，通常由硬件、驱动、COS和应用构成。

多应用载体中的用户应用在使用SM2/3/4系列算法时，需要载体的多应用环境提供SM2/3/4系列算法

的密码应用调用接口。由于目前多应用载体相关标准未定义SM2/3/4系列算法的应用接口，造成用户应

用无法使用的问题。为此，编制本标准以规范SM2/3/4系列算法在多应用载体中的密码算法能力标识、

接口规格，保障用户应用使用密码功能的统一性和完整性。

多应用载体可以使用不同的技术方案实现，如Java技术方案、C技术方案等。本版本主要描述了Java

技术方案中的密码应用接口，其他技术方案的密码应用接口根据应用发展情况在后续版本中给出。

III

GM/T0056-2018

多应用载体密码应用接口规范

1范围

本标准规定了多应用载体中SM2/3/4系列算法的密码应用接口，包括：

--定义SM2/SM3/SM4算法在多应用载体中的标识。

--定义SM2/SM3/SM4的算法的密码应用接口规格。

本标准适用于各种多应用载体的研制，也可用于指导多应用载体的密码应用检测。

2规范性引用文件

下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅注日期的版本适用于本文件。

凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。

GB/T32905-2016信息安全技术SM3密码杂凑算法

GB/T32907-2016信息安全技术SM4分组密码算法

GB/T32918-2016信息安全技术SM2椭圆曲线公钥密码算法

RFC2898SpecificationofPKCS#5

3术语和定义

下列术语和定义适用于本文件。

3.1

命令command

终端向载体发出的一条信息，该信息启动一个操作或请求一个应答。

3.2

响应response

载体处理完成收到的命令报文后，回送给终端的报文。

3.3

报文message

由终端向载体或载体向终端发出的，不含传输控制字符的字节串。

3.4

多应用载体multi-applicationsequipment

本文中指具备独立、开放的片上操作系统、提供多应用运行环境、支持载体上多个应用的下载、安

装、重用、共存和安全隔离的载体，通常由硬件、驱动、COS和应用构成。

3.5

1

GM/T0056-2018

SM2算法SM2algorithm

由GB/T32918定义的一种算法。

3.6

SM3算法SM3algorithm

由GB/T32905定义的一种算法。

3.7

SM4算法SM4algorithm

由GB/T32907定义的一种算法。

3.8

SM9算法SM9algorithm

一种采用双线性对的椭圆曲线公钥密码算法。

4符号和缩略语

下列符号和缩略语适用于本文件。

AID应用标识符（ApplicationIdentifier）

AKEY辅助密钥（AuxiliaryKey）

API应用编程接口（ApplicationProgrammingInterface）

CBC链式加密（Cipher-blockchaining）

COS片上操作系统（ChipOperatingSystem）

ECB电子密码本（ElectronicCodebook）

ISO国际标准化组织（InternationalOrganizationforStandardization）

MAC消息鉴别码（MessageAuthenticationCode）

MKEY报文密钥（MessageKey）

OFB输出反馈（OutputFeedback）

5多应用载体系统框架

多应用载体由硬件层、驱动层、OS层、应用层构成，详见图1。

2

GM/T0056-2018

用户应用1用户应用n

应用层

多应用安全管理环境

其他系统应用接口密码应用接口

OS层

载体操作系统内核

驱动层接口驱动密码算法库

硬件层芯片硬件

图1多应用载体安系统框架

其中硬件层是芯片，包括CPU、密码算法协处理器、存储器等。

驱动层包括各芯片硬件的接口驱动、以及和密码算法协处理器配套的算法库。

OS层包括支持多应用调度的载体操作系统内核,向应用层提供的系统应用接口，以及密码应用接口。

应用层包括多应用安全管理环境以及各种用户应用。多应用安全管理环境是一个特定的用户级别程

序，用于实现多应用的安全管理和安全隔离；用户应用实现各种业务应用功能。应用层通过OS层的密码

应用接口实现密码功能的调用。

6多应用载体密码应用接口调用流程

6.1密码应用接口调用流程

多应用载体中，调用密码应用接口的流程如图2所示：

3

GM/T0056-2018

多应用载体操作系统

上位机软件安全载体上的用户应用密码应用接口

a.获得载体支持的算法能力

b.返回载体支持的算法能力

不支

支持密码算

持

法

支持

流程结束c.调用用户应用(使用密码算法)

处理调用命令

调用密码功能

d.调用密码应用API

算法处理

e.返回密码应用调用结果

f.返回用户应用调用结果

流程结束

图2多应用载体密码应用接口调用流程

上位机软件是载体外的客户端软件，用户应用是在安全载体内运行的、实现密码安全功能嵌入式软

件。

用户应用调用密码算法的流程说明如下：

a）获得载体算法能力：上位机软件使用多应用载体的基本命令，获取载体上的算法能力，该命令

和载体上的用户应用无关。该步骤为可选步骤，如果上位机软件已知该载体的算法能力，可以跳过

该步骤。

b）返回算法能力：多应用载体操作系统返回载体支持的算法能力。如果载体算法能力和上位机不

匹配，流程结束。如果匹配，转c。该步骤为可选步骤，如果客户端软件已知该载体的算法能力，

可以跳过该步骤。

c）调用密码应用接口：如果载体支持密码算法，上位机软件调用载体上的用户应用。载体上用户

应用收到调用命令后，根据命令进行处理。

d）调用密码应用接口：如果该命令的处理需要使用密码功能，通过载体操作系统的密码应用接口

进行调用。

e）返回密码应用接口调用结果：密码应用API被调用后，进行算法处理并向载体上的用户应用返回

处理结果。

f）返回应用调用结果：载体上的用户应用向上位机软件返回调用结果。流程结束。

6.2密码算法能力标识

多应用载体应对所支持的密码算法能力进行标识，以便于载体外实体获得载体算法支持情况。

由于多应用载体可以使用不同的技术方案实现，如Java技术方案、C技术方案等，相应技术方案的

算法能力标识参见第7章。

6.3密码应用接口规格

4

GM/T0056-2018

多应用载体中应定义密码应调用的接口规格，以便于载体上的用户应用调用。

由于安全载体在实现中使用不同的技术方案，如Java技术方案、C技术方案等，相应技术方案的调

用接口规格参见第7章。

7Java技术方案密码应用接口

7.1简介

本部分描述了使用Java技术方案的多应用载体中，SM2/3/4系列算法的能力标识和应用接口规格定

义，使用SM2/3/4系列算法的应用可以调用这些应用接口以达到对密码功能的使用。

密码算法中的密钥对象需通过GMKeyBuilder.buildKey方法创建密钥实例，然后通过setXXX等方法

设置密钥对象所使用的密钥值，签名算法、加解密算法将使用这些密钥对象。对称密钥对象包括：

SM4Key，非对称密钥对象包括：SM2PrivateKey、SM2PublicKey。

签名与验证算法是通过GMSignature类实现的，在使用签名与验证算法前需要通过

GMSignature.getInstance方法获得相应算法的实例对象，再配合相应的密钥对象以实现生成签名数据

与验证签名数据的目的。

数据加解密算法是通过GMCipher类实现的，在使用数据加解密算法前需要通过

GMCipher.getInstance方法获得相应算法的实例对象，再配合相应的密钥对象以实现对数据加密或解密

的目的。

数据杂凑算法是通过GMMessageDigest类实现的，在使用数据杂凑算法前需要通过

GMMessageDigest.getInstance方法获得SM3算法的实例对象，然后才可对数据进行杂凑计算。

密码算法API中定义了GMKeyPair类，用于在载体内生成密码算法中的非对称密钥对（SM2）。

7.2密码算法能力标识

多应用载体密码算法能力标识定义见表1。

表1密码算法能力标识

标识对应密码算法能力

0x00–0x0F保留

0x10–0x17保留

0x18SM4_ECB

0x19SM4_CBC

0x1ASM4_OFB

0x1B保留

0x1C-0x1F保留

0x20SM3_256

0x21–0x27保留

0x28SM2_256

0x29-0x2F保留

0x30SM9_256

0x31–0xFF保留

5

GM/T0056-2018

7.3密码应用包定义

密码应用包定义见表2。

表2包信息

项定义

包名com.guomi

AID0xA0:0x0:0x0:0x0:0x0:0x53:0x43:0x43:0x41:0x01

主版本号1

次版本号0

7.4密码应用接口定义

7.4.1类定义

密码应用类定义如下。

classjava.lang.Object

——classcom.guomi.GMCipher

——classcom.guomi.GMKeyBuilder

——classcom.guomi.GMKeyPair

——classcom.guomi.GMMessageDigest

——classcom.guomi.GMSignature

——classcom.guomi.GMCipherExtend

——classcom.guomi.GMSM2KeyExchange

7.4.2接口定义

密码应用接口定义如下。

interfacejavacard.security.Key

——interfacejavacard.security.SecretKey

——interfacecom.guomi.SM4Key

——interfacejavacard.security.PrivateKey

——interfacecom.guomi.SM2PrivateKey

——interfacejavacard.security.PublicKey

——interfacecom.guomi.SM2PublicKey

interfacecom.guomi.SM2Key

——interfacecom.guomi.SM2PrivateKey

——interfacecom.guomi.SM2PublicKey

7.5密码应用类信息

7.5.1SM4Key

7.5.1.1概述

SM4Key包含一个16字节的密钥AKEY，用于SM4算法的加解密运算。

6

GM/T0056-2018

一旦密钥数据被设置，该密钥对象就将处于初始化完成状态（isInitialized方法将返回true），

该密钥可以被使用了。

SM4Key接口定义见表3。

表3SM4Key

返回值定义说明

bytegetKey(bytekeyData[],shortkOff)获得密钥引用

voidsetKey(bytekeyData[],shortkOff)设置密钥数据

7.5.1.2setKey

7.5.1.2.1声明

publicabstractvoidsetKey(

bytekeyData[],

shortkOff

)throwsCryptoException,NullPointerException,ArrayIndexOutOfBoundsException;

7.5.1.2.2描述

本方法用于设置SM4密钥数据。输入的密钥数据长度为16字节。数据格式为大端并且右对齐，即最

低有效位为最后那个字节的最低有效位。

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.3getKey

7.5.1.3.1声明

publicabstractbytegetKey(

bytekeyData[],

shortkOff

)throwsCryptoException,NullPointerException,ArrayIndexOutOfBoundsException;

7.5.1.3.2描述

本方法获得的SM4密钥引用。密钥引用指向的数据长度为16字节。数据格式为大端并且右对齐，即

最低有效位为最后那个字节的最低有效位。

7

GM/T0056-2018

7.5.1.3.3参数

keyData-此byte数组存放返回的密钥数据。

kOff-密钥数据在byte数组中的起始位置。

7.5.1.3.4返回值

以字节计的密钥数据的长度。

7.5.1.3.5抛出异常

CryptoException.UNINITIALIZED_KEY-密钥对象没有正确初始化时。

NullPointerException-keyData参数为null时。

ArrayIndexOutOfBoundsException-kOff参数为负数或者超过keyData数组时，或者kOff加上

密钥数据长度超出keyData数据长度时，抛出该异常。

7.5.2SM2Key

7.5.2.1概述

SM2Key是非对称密钥的一种，分为公钥和私钥，用于SM2算法的运算。

SM2Key接口定义见表4。

表4SM2Key

返回值定义说明

shortgetA(byte[]buffer,shortoffset)获得曲线参数A

shortgetB(byte[]buffer,shortoffset)获得曲线参数B

shortgetG(byte[]buffer,shortoffset)获得曲线参数G

7.5.2.2getA

7.5.2.2.1声明

publicshortgetA(

bytebuffer[],

shortoffset

)throwsCryptoException,NullPointerException,ArrayIndexOutOfBoundsException;

7.5.2.2.2描述

本方法用于获取曲线参数A的数据。输出的数据长度为32字节。数据格式为大端并且右对齐，即最

低有效位为最后那个字节的最低有效位。

7.5.2.2.3参数

buffer-此byte数组存放输出的数据。

offset-数据在byte数组中的起始位置。

7.5.2.2.4返回值

8

GM/T0056-2018

以字节计的曲线参数A的数据长度。

7.5.2.2.5抛出异常

CryptoException.UNINITIALIZED_KEY-密钥处于未初始化状态时抛出该异常。

NullPointerException-keyData参数为null时抛出该异常。

ArrayIndexOutOfBoundsException-offset参数为负数或者超过buffer数组时，或者offset

加上曲线参数A长度超出buffer数据长度时，抛出该异常。

7.5.2.3getB

7.5.2.3.1声明

publicshortgetB(

bytebuffer[],

shortoffset

)throwsCryptoException,NullPointerException,ArrayIndexOutOfBoundsException;

7.5.2.3.2描述

本方法用于获取曲线参数B的数据。输出的数据长度为32字节。数据格式为大端并且右对齐，即最

低有效位为最后那个字节的最低有效位。

7.5.2.3.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.4getG

7.5.2.4.1声明

publicshortgetG(

bytebuffer[],

shortoffset

)throwsCryptoException,NullPointerException,ArrayIndexOutOfBoundsException;

7.5.2.4.2描述

本方法用于获取曲线参数G的数据。输出的数据长度为64字节,前32字节为G值x坐标，后32字节为y

坐标。数据格式为大端并且右对齐，即最低有效位为最后那个字节的最低有效位。

9

GM/T0056-2018

7.5.2.4.3参数

buffer-此byte数组存放输出的数据。

offset-数据在byte数组中的起始位置。

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.3SM2PrivateKey

7.5.3.1概述

SM2PrivateKey接口用于生成数据的签名。

由于SM2算法曲线方程和参数已经固定，一旦私钥数据被设置，该私钥对象就将处于初始化完成状

态（isInitialized方法将返回true），该密钥可以被使用了。

SM2PrivateKey接口定义见表5。

表5SM2PrivateKey

返回值定义说明

shortgetS(byte[]buffer,shortoffset)获得私钥数据

voidsetS(byte[]buffer,shortoffset,shortlength)设置私钥数据

7.5.3.2getS

7.5.3.2.1声明

publicshortgetS(

byte[]buffer,

shortoffset

)throwsCryptoException,NullPointerException,ArrayIndexOutOfBoundsException;

7.5.3.2.2描述

本方法获得的SM2私钥数据。输出的私钥引用数据长度为32字节。数据格式为大端并且右对齐，即

最低有效位为最后那个字节的最低有效位。

7.5.3.2.3参数

buffer-此byte数组存放返回的私钥数据。

offset-数据在byte数组中的起始位置。

10

GM/T0056-2018

7.5.3.2.4返回值

以字节计的私钥数据的长度，本规范中固定为32。

7.5.3.2.5抛出异常

CryptoException.UNINITIALIZED_KEY-密钥处于未初始化状态时抛出该异常。

NullPointerException-buffer参数为null时抛出该异常。

ArrayIndexOutOfBoundsException-offset参数为负数或者超过buffer数组时，或者offset

加上密钥数据长度超出buffer数据长度时，抛出该异常。

7.5.3.3setS

7.5.3.3.1声明

publicvoidsetS(

byte[]buffer,

shortoffset

shortlength

)throwsCryptoException,NullPointerException,ArrayIndexOutOfBoundsException;

7.5.3.3.2描述

本方法用于设置SM2私钥数据。输入的私钥引用数据长度为32字节。数据格式为大端并且右对齐，

即最低有效位为最后那个字节的最低有效位。

7.5.3.3.3参数

buffer-此byte数组存待设置的私钥数据。

offset-数据在byte数组中的起始位置。

length-以字节计的私钥数据的长度，本规范中固定为32。

7.5.3.3.4抛出异常

CryptoException.ILLEGAL_VALUE-输入的密钥长度不符合要求时或者密钥需要解密并且出错

时抛出该异常。

NullPointerException-buffer参数为null时抛出该异常。

ArrayIndexOutOfBoundsException-offset参数为负数或者超过buffer数组时，或者offset加

上密钥数据长度超出buffer数据长度时，抛出该异常。

7.5.4SM2PublicKey

7.5.4.1概述

SM2PublicKey接口用于验证数据的签名。

因为曲线方程和参数已经固定，因此一旦公钥数据被设置，该公钥对象就将处于初始化完成状态

（isInitialized方法将返回true），该公钥可以被使用。

SM2PublicKey接口定义见表6。

表6SM2PublicKey

11

GM/T0056-2018

返回值定义说明

shortgetW(byte[]buffer,shortoffset)获得公钥数据

voidsetW(byte[]buffer,shortoffset,shortlength)