GM/T 0020-2012 证书应用综合服务接口规范

ICs35.040

L80

备案号:38318—2013

中华人民共和国密码行业标准

GM/T0020—⒛12

熏

证书应用综合服务接口规范

⒛12艹22发布⒛12-1⒈22实施

国家密码管理局发布

GM/T0020-2012

目次

前言·…………………………Ⅲ

·…………………………

引言Ⅳ

………………………·

1范围1

2规范性引用文件·…………………………1

3术语和定义………………·

4缩略语·……·……………·

·

5算法标识和数据结构…∵………………

5.1标识定义·……………

5.2数据结构定义·………………·……………………·

6证书应用综合服务接口概述……………·

……·…………

6.1概述…………………

6.2客户端服务接口·……………·……………………·

6.3服务器端服务接口¨………………·

·

7证书应用综合服务接口函数定义……………·………·

7.1客户端控件接口函数·……………¨3

7.2服务器端COM组件接口函数……………………10

7.3Java组口函………………18

件接数

附录A(规范性附录)证书应用综合服务接口错误代码定义…………26

B(资…………·

附录料性附录)证书应用综合服务接口典型部署模型29

………………·

附录C(资料性附录)证书应用综合服务接口集成示例30

……………………·

参考文献32

GM/T0020-⒛12

亠

刚曰

本标准按照GB/T1.1—⒛09的规则编写。

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

本标准由国家密码管理局提出并归口。

本标准中的附录A为规范性附录,附录B和附录C为资料性附录。

:北、、

本标准起草单位京数字认证股份有限公司上海格尔软件股份有限公司北京海泰方圆科技有

、证证心、全工心、卫士业

限公司上海市数字书认中有限公司无锡江南信息安程技术中成都通信息产股

正、、

、元通山

份有限公司长春吉大信息技术股份有限公司兴唐信科技有限公司东得安信息技术有限公

、全工研心、码理局码测心。

司国家信息安程技术究中国家密管商用密检中

王玉

:刘、、、、、、元正、丽、、、、

本标准起草人平李述胜谭武征柳增寿刘承徐强李赵丽妮娜孔凡袁峰

胸

李志伟。

本标准凡涉及密码算法相关内容,按照国家有关法规实施。

GM/T0020一⒛12

引曰

本标准依托于GM/T0019—⒛12《通用密码服务接口规范》,向上为应用层规定了统一的高级密码

服务接口。

口上、证应口,屏了码

证书应用综合服务接为层的应用系统提供简洁易用的书用接蔽各类密设备

(服务器密码机和智能密码钥匙等)的设各差异性,屏蔽了各类密码设备的密码应用接口之间的差异性,

实现应用与密码设各无关性,可简化应用开发的复杂性。证书应用综合服务接口分成客户端服务接口

和服务器端服务接口两类,可满足B/S和C/S等多种架构的应用系统的调用需求,有利于密码服务接

口产品的开发,有利于应用系统在密码服务过程中的集成和实施,有利于实现各应用系统的互联互通。

廨

GM/T0020-ˉ2012

证书应用综合服务接口规范

1范围

本标准规定了面向证书应用的统一服务接口。

本标准适用于公钥密码应用技术体系下密码应用服务产品的开发,密码应用支撑平台的研制及检

测,也可用于指导直接使用密码设备和密成和开发。

2规范性引用文件

下列文件对于本是必不可少的。凡是注日的引用文1

期件版本适用于本文

,凡不日,其(包)适

件是注期最新版所

本括有的改用于

修单本文侔

GM/T0O06

GM/TO0

GM/T

GM/T

GM/T

PKCSyptogra

RFC327ensible

3术语和定

下列术语

3.1

数字证书d

一

证开、开、

由认权威数字⒈密钥拥有者信息公密钥签期以及些扩展信

息的数字文件。

3.2

用户密钥11serltey

存储在设各内部的用于应用密码运算的非对称密钥对,包含签名密钥对和加密密钥对。

3,3

容器container

密码设各中用于保存密钥所划分的唯一性存储空间。

4缩略语

下列缩略语适用于本文件:

APIApplicationProgramIllterface应口,简应口

用程序接称用接

cationAuthority证

CACertiⅡ书认证机构

CNCommonName通

用名

GM/T0020-ˉ2012

cateRevocationLlst证

CRLCertiⅡ书撤销列表

CSPCryptographicScrviceProvider力

口月

密艮务提供者

DERαstinguishedEncodingRules可

区分编码规则

DNDlstinguishedName可

识别名

I'DAPI△ghtweightDlrectoryAccessPr°tocol轻

量级目录访问协议

l·tifier对

OIDO叻ectI巾象标识符

tography⒊andard公

PKCSthePublicKeyCr”钥密码标准

5算法标识和数据结构

5.1标识定义

、法识和证书识的具定义见GM/T∞06。

本规范所使用常量各类算标解析标体

5.2数据结构定义

‘∶

本规范对应的接口处理的数据分为两种类型:

数据类型A:当公钥算法为RSA时,数据的结构遵循PKCS杵1;当公钥算法为SM2时,数据的结

构遵循GM/T0009。

数据类型B:当公钥算法为RSA时,消息的结构遵循PKCS鞋7;当公钥算法为SM2时,消息的结构

遵循GM/T0010。

6证书应用综合服务接口概述

6.1概述

证书应用综合服务接口位于应用系统和典型密码服务接口之间,向应用层直接提供证书信息解析、

证证和机、整性、不可否认性级密码服务。该接口可直接供应用系

基于数字书身份认信息的密性完等高

统调用,将应用系统的密码服务请求转向通用密码服务接口,通过通用密码服务接口调用相应的密码设

各实现具体的密码运算和密钥操作。通用密码服务接口应遵循GM/T0019。

本规范所定义的证书应用综合服务接口包括客户端服务接口和服务器端服务接口两类。其中服务

口COM组和Java形两描述。本文所涉及的数字证书格式应遵循

器端服务接采用件形式式类

GM/T0015。

6.2客户端服务接口

本规范定义的客户端服务接口采用客户端控件方式。客户端控件适用于客户端程序调用,接口的

Wind。

DI'1'动ActiveX控Applet插,接口wsXP、Windows2000、

形态包括态库、件、件等应支持

Windows7等

Vista、

Windows2003、终端用户使用的主流操作系统。

口:配理、证、证、、、

客户端控件接的主要函数功能应包括置管书解析签名与验加密与解密数字信封

XMI'数据的签名与验证等。

口,本以Acti讹X控,其BsTR代回

在定义客户端服务接时规范件为例进行描述中表函数返值或参

java.

OLECHAR字,如CString、

数类型为符串类型,不同的开发语言应采取对应的类型定义:char※、

lang,String等

。

6.3服务器端服务接口

口COM组Webservice等

服务器端服务接口适用于服务器端程序调用,接的形态包括件、JAR包、

2

GM/T0020-2012

口Wind。

ws、Linux、

,接Unix、

形态应支持AⅨ№la⒒s等

、服务器使用的主流操作系统。服务器端服务

接口的函数功能与客户端控件接口相对应,主要包括:配置管理、证、

数字书解析签名与验证、

加密与解

XML数

、、

密数据信封据的签名证、。

与验时间戳等

7证书应用综合服务接口函数定义

7.1客户端控件接口函数

7.1.1客户端接口函数定义

客户端控件接口包括以下函数:

a)口SOF~GetVer⒍

获取接的版本号on

b)设置签名算法SOF_&tSignMethod

c)获得当前签名算法SOF~GetSignMethod

d)设置加密算法SOF~SetEncryptMethod~

e)获得加密算法SOnsetEncryptMethod

f)获得证书列表SOF~GetUserhst

g)导出用户证书SOF~ExportUserCert

h)校验证书口令SOF~Login

i)获取用户认证口令剩余重试次数SOF~GetPinRetryCourlt

j)修改证书口令SOF~ChangePassWd

k)导出用户加密证书SoF~ExportExChangeUserCert

D获得证书信息SOF~GetCertInfo

m)获证展SOF~GeCerthfoByOid

得书扩信息

n)SOF~GetDevi。

获得设各信息eInfo

o)∷

验证证书有效性SOF~ValidateCert

p)g证

数字签名SOF~⒊汔ta

q)验证签名SOF~VeⅡfySignedData

r)文件签名SOF~SignRle

s)SO廴gnedFile

验证文件签名Vedy⒊

t)ptData

加密数据SOF~Enc叩

u)解密数据SOF~DecryptData

v)文件加密SOF~EncryptFile

w)文SOF~DecryptRle

件解密

x)gnMessage

消息签名SOF~⒏

y)验证消息签名SOF~VerifySignedMessage

z)解析消息签名SO廴GetInfoFrom⒏gnedMessage

aa)XML数签SOF~SignDataXML

字名

bb)验XML数SO廴VeofySignedDataXML

证字签名

cc)解gnatureInfo

析XML签名数据SOF~GetXML⒊

dd)产SOF~GenRandom

生随机数

ee)获SOF~GetLastError()

取最新的错误代码

Acti次

以X控件形态为例,下面对接口函数进行定义。

GM/T0020—⒛12

7.1.2获取接口版本信息sOF~GetVersion

原型:BSTRSOF_GetVersion()

描述:获取控件的版本号。

参数:无

返回值:非空.成功

空失败

etsignMethod

7,1,3设置签名算法sOF』

原型:longSOF~SctSignMeth°

设置接口在签名虏用的签名算法。

SignR/Iet

返回值:0

苴《失败,详见错误代码表

7.1.4获得当法sOF_GetsignMethod

原型:

描述:

参数:

返回

7.1.5

原型:

描述:

参数:

返回值:

7.1.6获得加密算

longSOF_

描述:获得控件使用的

无

回:爿前用的加密法的预义

返值|0当控件使算定值

0没有设置加密算法

7.1.7获得证书列表sOF~GetUserList

原型:BSTRSOF_GetUserustO

描述:取得当前已安装证书的用户列表c

参数:无

1HCont蔚

返回值:非空用户列表字符串数据格式为:用户名nerName1&&&用户

⒏&…

名2HCo时aincrName2⒏

空失败

GM/T0020ˉ—2012

各注:根据证书应用的策略不同得到不同的证书列表。在证书列表中,用户名代表证书的

CN项nerName代

内容;Cont“表证书和密钥对应的容器名,也可以是代表证书实体身

份的唯一的号码,通ContaincrName可一

过以找到唯的加证、,并

密书签名证书使用对

应的密钥。

7.1,8导出用户证书sOFExportUserCert

原型:BSTRSOF~ExportUserCert(BSTRContainerName)

描述:根据证书器,获base64编

容名取码的证书字符串。

t“nerNameEi司

参数:Col△证书器

容名

返回值:非空书字符串

空

备注:默认导出签

7.1,9校验证书口令

原型:1Login(BsTRContainerName,BSTRPassWd)

描述:的用户认证口令,进行用户认证。

参数:

返回值:

灞

Ⅷ

7,1.10获

原型:

描述:

参数:

返回值:

7.1,l1修改证

型:BOOngePassWd(BSTRContainerName,

原ζsWd,

BS

描述:修改设备的

ContainerNameEio

参数:书容器名

OldPassWdEil·

l

NewPassWdEi删新口令

返回值:TRUE修改口令成功

FALSE失败

7.1,12导出用户加密证书sOF』xportExChangeUserCert

原型:BSTRSOF~ExportExChangeUserCert(BSTRContainerName)

描述:根证书器,获base64编(交)证

据容名取码的加密换书字符串。

:ContainerNameEi司

参数证书容器名

返回:闫base64编

值|z兰码的证书字符串

空失败

GˇI/T0020ˉ—2012

7.1,13获得证书信息sOF_GetCertInfo

原型:BSTRSOF_etCertInfo(BSTRBase64EncodeCert,sh°

rtType)

描述:获取证书内指定类型的信息。

参数:Base64EncodeCertEi司

base64编

码的证书

TypeEin彐获取信息的类型,代码标识见GM/T0006

返回值:非空证书内指定类型的信息

空失败

7.1.14获得证书扩展信息sOF~GetCertInfoByoid

型:BSTRSOF~etCertInf°

原ByOid(BSTRBase64EncodeCert,BSTROid)

描述:根据OID获取证书私有扩展项信息。

参数:Base64Enc°deCertEil11base64编

码的证书

oidEin彐攵ID,如“

私有扩展对象1,2.156。xxx”

返回值:非空证书私有扩展项OID对应的信息

空失败

7.1,15获得设备信息s0廴GetDeviceInfo

原型:BSTRSOF_GetDeviccInfo(BSTRContainerName,longtype)

描述:根据容器和类型代码获得设各信息。

参数:ContainerNameEin]

证书容器名

typeEi司信息类别,定义详见GM/T0006的设备信息标识表

返回值:非空type对

应的设各信息

空失败

7.1,16s0廴

验证证书有效性VaIidateCert

原型:longSOF~ValidateCert(BSTRBase64Enc°

deCert)

描述:验证证书有效性。

参数:Base64EncodeCertEilllbase64编

码的证书

返回值:0验证成功

其他△证书不被信任

2超过有效期范围

3证书已作废

4证书已冻结

5证书未生效

6其他错误

各注:基本的证书验证策略应包括

a)验证CA信任列表,各层都要进行签名和有效期验证;

b)各层证书的有效期;

c)各层证书的吊销状态。在特殊情况下(如:网络条件不允许),证书的吊销状态可采

取灵活方式,由应用系统各层内部维护一个吊销列表,在证书登录认证时应用该吊

销列表。证证

验书有效性也可采取代理验证方式。

6

GM/T0020-2012

gnDρ

7.1.17数字签名sOF⒊ta

原型:BSTRSOF~ignData(BSTRContainerName,BSTRInData)

描述:对字符串数据进行数字签名,签名值为数据类型A。

i司

nerName匚证器名

参数:Cont茄书容

taEin]

InD色签名原文

base64编

回:空码的签名结果

返值非

空失败

7.1.18验证签名sOF_VeriFysignedData

原型:BOOLSOF_VerifySignedData(

BSTRBase64EncodeCert,BSTRInData,BSTRSignValue)

描述:验证数字签名,签名值为数据类型A。

CertEi删码签证书

参数:Base64Enco啪base64编名者

InDataEin]签名原文

SignValueEin]base64编型A签

码的数据类名值

返回值:TRUE成功

FALSE失败

7.1.19文件签名sOFJignFiIe

原型:BSTRSOF~ignFile(BSTRContainerName,BSTRInFile)

描述:根据文仵路径,对指定文件中的数据进行数字签名,签名值为数据类型A。

nerNameEi司

参数:Cont“证书容器名

InFneEin]原文文件路径,包含文件名

base64编签果

回:闫码的名结

返值|空

空失败

7,1。⒛验证文件签名sOF_VeriFysignedFile

原型:BooLSOF~VerifySignedFile(

BSTRBase64EncodeCert,BSTRInFile,BSTRSignValuo)

描述:验证文件的数字签名,签名值为数据类型A。

码签证

的名者书

参数:BaseC4EncodeCertEi司base64编

InFileEin]全路径文件名称

SignVdueEin]base64编型A签

码的数据类名值

返回值:TRUE成功

FALSE失败

7.1.21加密数据sOFEncryptData

原型:BSTRSOF~ncryptData(BSTRBase64EncodeCert,BSTRIndata)

描述:使用临时产生的对称密钥加密数据,然后使用数字证书加密对称密钥。密文数据格式

为数据类型B。

码的加密用的数字证书

base64编

参数:BaseC4EncodeCertEi删

∷

IndataEi司待加密的明文

7

GM/T0020-2012

返回值:非空加密后的数据类型B的密文,采base64编

用码

空失败

7.1。22解密数据s0廴DecryptData

原型:BsTRSOF~ecryptData(BSTRContainerName,BSTRIndata)

描述:使用证书对应的私钥解密数字信封,密文数据格式为数据类型B。

:ContainerNameEilll

参数证书容器名

IndataEin]base64编B的

待解密的码的数据类型密文

返回值:非空解密后的明文

空

7,1.23文件加密sOF~Encry

原型BOOI冫ile(BSTRBase64Enile,BSTROutFile)

描述使件,得到数据类型B的数字信封文件:

参数deCertEirllbase64编

码的加密证书

待加密的全路径文件名称

返回值

7,l,24

原型File)

描述

参数tainerN

1eEin]

返回值:

7,l。25消息签名

原型—e,BSTRInData)

、

描述对字符串数据进名,签名结果的类型B。

参数flagEin]识,1:不带原文;0:带原文。

inerNameEin]

Con忱证书容器名

InDataEin彐签名原文

返回:非空base64编

值码的签名结果

空失败

备注:签名结果包含:原文(可选)+签名者证书+签名值。

7,1,26验证消息签名sOF~VerifysignedMessage

原型:

描述:验证数字签名,签名值为数据类型B。

MesmgeDataEin]

:“se64编

参数码的消息签名数据

GM/T0020-⒛12

InData[in彐原文。如果签名结果带原文,则本参数为空。

返回值:TRUE成功

FALsE失败

7,1,27解析消息签名sOF_GetInfoFromsignedMessage

原型

,包:原、、证。型B。

描述:解析签名包内的信息括文签名值签名书等信息签名包为数据类

:MessageDataEin彐码的签包

参数base64编名

type[in彐类型

回:爿解

返值Fz芒析

空

1时

备注:Type为签证3时

名者书;Type为

解析出

7.1.28XML数字ignDataXbIL

原型:_signDataXML(BSTRContainerName,BSTRInDa

描述:

nerNa

参数:

返回值:翩

各注: