GM/T 0019-2012 通用密码服务接口规范

ICs35.040

L80

备案号:38317—2013

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

GM/T001g~z012

‘

通用密码服务接口规范

UniversaIcryptographyserviceinterfacespecification

⒛12冖1⒈22发布2012-11-22实施

国家密码管理局发布

GM/T0019ˉ—2012

目次

¨¨¨¨

¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨

目刂舀I

引言Ⅱ

·

1范围¨1

2规范性引用文件¨1

···

3术语和定义¨1

·

4符号和缩略语¨1

···

5算法标识和数据结构¨2

···

5,1算法标识与常量定义¨2

5.2密码服务接口数据结靥定义和说明2

¨

6密码服务接口·4

·

6.1通用密码服务接口在公钥密码基础设施应用技术体系框架中的位置¨4

··

6.2密码服务接口组成和功能说明·

5

·

7密码服务接口函数定义··

6

·

7.1环境类函数¨6

7.2证书类函数·8

7,3密码运算类函数15

7.4消息类函数35

附录A(规范性附录)密码服务接口错误代码定义45

参考文献·47

GM/T0019ˉ—2012

亠

刖口

本标准依据GB/T1.1—⒛09给出的规则起草。

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

本标准的附录A为规范性附录。

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

本标准起草:北京数字认证股份有限司、上海、

单位公格尔软件股份有限公司北京海泰方圆科技有

、江全工心、上

限公司无锡南信息安程技术中海数字证书认证中心有限公司、卫士通信息产业股份有限

、、工

公司山东得安信息技术有限公司国家信息安全程技术研究中心。

主要人:刘、、、、、

本标准起草平李述胜谭武征增徐强承、元正、、玉、

柳寿刘李高志权孔凡袁峰。

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

《

GM/T0019-⒛12

引亠

一

一

口

本标准依托于密码设各层的GM/T0018《密码设应口》GM/T0016《

备用接规范和智能密币乏乏

密码应用接口规范》,为典型密码服务层和应用层规定了统一的通用密码服务接口。

通用密码服务接口在公钥密码基础设施支撑的前提下,向应用系统和典型密码服务层提供各类逼

用的密码服务,有利于密码服务接口产品的开发,有利于应用系统在密码服务过程中的集成和实施,有

利于实现各应用系统的互联互通。

GM/T0019—2012

通用密码服务接口规范

1范围

本标准规定了统一的通用密码服务接口。

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

可用于指导直接使用密码设备的应用系统的开发。

2规范性引用文件

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

。不日(包)适

件凡是注期浊最新版本括所有的修改单用于本文

GlNI/T0O06

GM/T001

GM/T00

GM/T

GM/T

GM/T

PKCSeSynt

3术语和定

下列术语

3.1

数字证书山

一

、、

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

息的数字文件。

3,2

用户密钥t1serkey

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

3.3

容器container

一

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

4符号和缩略语

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

APIApplicati°nProgramInterface应用程序接口,简称应用接口

CACertihcationAuthority证书认证机构

CNCommonName通用名

GM/T0019-2012

CRI'CertiⅡcateRcx/ocationust证书撤销列表

DERⅡstinguishedEncodingRules可区分编码规则

DNDlstinguishedName可识别名

ECCEllipticCurveCr”tography椭圆曲线密码

LDAPLigl△tweight¤rectoryAccessProtocol量级目访

轻录问协议

OIDO切ectIⅡnti伍er对标识

象符

PKCSthePublicKeyCryptographyStandard公钥密码标准

5算法标识和数据结构

5.1算法标识与常量定义

量定义、法和证识的义见GM/T0006。

本规范所使用常各类算标识书解析标具体定

5.2密码服务接口数据结构定义和说明

5.2,1常量定义

数据常量标识定义了在规范中用到的常量的取值。

数据常量标识的定义如表1所示。

表1常量定义

常量名取值描述

SGD~MAX~COUNT6迮枚举出的对象数量最大值

SGDR/IAXNAMEsIZE证项长最大

书某信息的字符串度值

5,2,2用户证书列表(见表2)

表2用户证书列表

字段名称数据长度(字节)含义

certCount4证书总数

Certificatc4DER编码的数字证书

certificatcI'en4数字证书的长度

containcrNamc4容器名称

containcrNameLem钅容器名称的长度

keyUsage4密钥用途

实际数据结构定义:

typedefstructSGD~USR_CERT_ENUMLIST_(

unsignedintcertCount;

unsignedchar※cer0ficateESGD_MAX_COUNT彐;

unsignedintcertificateLenEsGD_MAX~COUNT彐;

unsigncdcharxcontainerNameESGD~MAX_COUNT彐;

unsignedintcontainerNameLenESGD_MA`COUNT];

h

Ⅱ

Ⅱ

Ι

Ι

■

Ⅱ

l

■GM/T0019-⒛12

Ⅱ

ⅡunsignedintkeyUsageESGD~MAX~COUNT];

Ⅱ

Ⅱ)SGD~USR_CERT~ENUMLIST;

Ⅱ

l

Ⅱ5.2.3密钥容器信息列表(见表3)

l

Ⅱ

匚表3密钥容器信息列表

Ⅰ

Ⅰ

Ⅰ数据长度(字节)

l

l

l

I

I

丨keyPairCount密钥容器信息总数

containerName

containerNameLen容器名称的度

诲

密钥用途:1:加密;2:签名;3:密钥交换

丨

}

丨密钥类型:1:sM2;2:RSA1024;3:RSA2048;

丨茌:RsA3072;5:RSA4096

}

}

ι

实际数据结构定义:

丨

{typedefstructSGD~KEYCONTAINERINFO~ENUMLIST~(

uns1gnedimtkeyPa1rCount;

unsignedcharxcon忱inerNameESGD~MAX_COUNT彐;

unsignedintcontainerNameLenESGD~MA廴COUNT];

unsignedintkeyUsage[SGD~MAX~COUNT];

unsignedintkeyTypeESGD~MAX~COUNT彐;

)SGD_KEYCONTAINERINFO~ENUMLIST;

5.2.4证书中DN的结构(见表4)

表4证书中DN的结构

字段名称数据长度(字节)含义

dnc国家名称

dnclenl国家名称的长度

dns256省份或直辖市名称

dn~s~len1省份或直辖市名称的长度

dn~l城市或地区的名称

dn~1~len1城市或地区的名称的长度

dno256机构名称数组

dn_o~len机构名称数组的长度

dnou机构单位名称数组

dnoulen机构单位名称数组的长度

dncn证书拥有者名称数组

d1刁1~~cn1en8证书拥有者名称数组的长度

dnemaⅡ256电子邮件数组

dnemai11en8电子邮件数组的长度

GM/T0019-⒛12

实际数据结构定义:

typedefstruct(

unsignedchardn_cESGD~MAX_NAME_SIZE彐;

unsignedchardn_c~lenE1彐;

unsigncdchardn~sESGD_MAX_NAME_SIZE彐;

unsignedch犭rdn_s_lenE1彐;

unsignedchardn_l[SGD_MAX_NAME_SIZE];

unsignedchardn_l_lenE1];

unsignedchardn_oE5][SGD~M

unsignedintdn_o~l

unsignedchard

unsignedin

unslgne

uns1g

uns1

un

}SGD

通用、

证书认证、

信

息的机密性(体的基础密码

操作请求,通钥操作。

通用密码

图1通用密码服务接口在公钥密码基础设施应用技术体系框架内的位置

GM/T0019一⒛12

6.2密码服务接口组成和功能说明

6,2.1概述

通用密码服务接口由以下部分组成:

a)环境类函数;

b)证书类函数;

c)密码运算类函数;

d)消息类函数。

6.2,2环境类函数

昕需的源、号,并

环境类函数负责创建和各种资信

,造函码

确保安全程序空间在应不会被非法访问成信息鲁数负责完成与密

、1还在用户与

设各的安全连接,确操作是在安全可信的程序空间中进行数负责

釜钫问牌。可创建两种类型的用户安全访问令普通用户,该类

密码设各之间创建令

型的安全访问令用户是普通用户,只能访问密码设各中属于自己的信:另一类是管瑁

员,该类型的安

应用程序初始化安全

的应用程序环境函数

(SAF_Finali带来的安

全风险。应昴数(sAF_

Login),;耋立调用任何

喇非法访问。

密码服务函Ι

6,2,3证书

证书类函书或CRI',提

CA根、证证系列具体函数。

供包括证书获取、、证书设置用户证书验和用户书信息

∶理、

应用程序通过调用现基于数字证书的身份认证,从证书中获取实现授权管访

问控制等安全机制。的数字证书格式应遵循GM/TO01

6.2.4密码运算类函数

密码运算类函数负责具体与密码,并将密码运算后的结果返回给应

、整性和不可抵赖性等安全机制的基础。

用程序,是应用程序实现数据保密性完

base64编码、机生、字摘要以及各种对称和非对称密码运算

密码运算类函数提供包括解随数成数

。码服务函数支持定长数据和不定长数据的密码运算,对于定长数据可以直接调用相关函数进行

等密

处理;对于不定长数据,需要先创建相应的密码运算对象,然后调用相应的函数对数据进行持续处理。

当数据处理完时,要调用相应的函数表示数据处理完,最后要调用相应函数销毁相应的密码运算对象。

6.2,5消息类函数

消息类函数主要是将数据按照PKCS#7格式进行封装,实现数据封装格式与应用系统无关性,实

现应用系统互联互通和信息共享。

PKCS#7格PKCS杵7格码和PKCS#7格

消息类函数提供了式的数据编解码、式的签名数据编解

证、、整性和不可否认性等安全措施。

式的数字信封编解码,能够非常方便应用程序实现身份认保密性完

GM/T0019-⒛12

7密码服务接口函数定义

7.1环境类函数

7.1.1概述

环境类函数包括以下亻函,各A错

具本数函数返回值见附录误代码定义:

a)初始化环境:SAFInitialize

b)清除环境:SAF~Finalize

c)获取接口版本信息:SAF~GetVers10n

d)用户登录:SAF~I'ogin

e)修改PIN:SAF~ChangePin

f)注销登录:SAF~Logout

7,1.2初始化环境滋

原型:intSAFInitiahze(void兴兴ePath);

描述:phAppHandle,charxpucCfgFⅡ

初始化密码服务程序空间。

参数:phAppHandleEin/ou司输人并返回应用接口句柄

pucCfgFnePathEin]配置文件全路径名,配置信息自定义,建议包括:密码

设备类型、码设态、

密备动库名称设备的配置、

文件应

用策略等°

0

返回值:成功

爿

|0失败,返回错误代码

7.1.3清除环境

原型:intSAFFinahze(void※hAppHandle);

描述:清除应用程序空间。

参数:hAppHandleEin]应用接口句柄

0

返回值:成功

爿00失败,返回错误代码

7.1.4获取接口版本信息

原型:intSAF~GetVersion(unsignedint兴puiVersion)

描述:取接口对应标准的版本号。

参数:p“Ver⒍onEou闸版本号

0

返回值:成功

爿0

卜失败,返回错误代码

:AA为

各注版本号的格式为:0xAABBCCCC,其中主版本号,BB为次版本号,CCCC为修

改号。

7.1,5用户登录

原型:intSAF~Login(

vo1d*hAppHandle,

6

GM/T0019-⒛12

unsignedintuilJsrType,

unsigned(冫har兴

pucContainerName,

unsignedintuiContainerNameLen,

※

unsignedcharpucPin,

unsignedintuiPinLen,

。

unsignedintxpuiRemainCount)

描述:用户登录密码设各,建立安全令牌。

参数:hAppHandleEi硐应用接口句柄

“UsrTypeEillI用户类型,当为0时表示管理员登录,为1时表示用户

登录

pt】cCont“nerName[irln容器名或密钥检索号

uiCon咖nerNameLenEin彐容器名或密钥检索号的长度

pucPinEin]设口

备令

uiRnLen[in彐泅设各口令长度

puRem缸nC°untEout]口令剩余重试次数

返回值:0