DB11/T 254.2-2004 政务数字证书规范 第2部分：应用接口

ICS35.240.30

L70

备案号：16484-2005DB

北京市地方标准

DB11/T254.2-2004

政务数字证书规范

第2部分：应用接口

Specificationofdigitalcertificateforgovernmentaffair

Part2:Applicationprogramminginterface

2004-12-20发布2005-02-01实施

北京市质量技术监督局发布

DB11/T254.2-2004

目次

前言.............................................................................................................................................................II

引言............................................................................................................................................................III

1范围..................................................................................................................................................................1

2规范性引用文件..............................................................................................................................................1

3术语和定义、缩略语......................................................................................................................................1

3.1术语和定义...................................................................................................................................................1

3.2缩略语...........................................................................................................................................................2

4政务数字证书应用接口..................................................................................................................................2

4.1数字证书应用接口体系结构.......................................................................................................................2

4.2数字证书应用接口组成和功能说明...........................................................................................................3

5政务数字证书应用接口函数定义..................................................................................................................5

5.1环境函数.......................................................................................................................................................5

5.2设备管理函数...............................................................................................................................................6

5.3证书函数.......................................................................................................................................................7

5.4密码服务函数.............................................................................................................................................12

5.5消息函数.....................................................................................................................................................30

附录A(规范性附录)政务数字证书应用接口宏定义和说明..................................................................34

A.1类型宏定义................................................................................................................................................34

A.2常量宏定义................................................................................................................................................34

A.3全局参数....................................................................................................................................................34

附录B(规范性附录)政务数字证书应用接口数据结构定义和说明......................................................36

附录C(规范性附录)政务数字证书应用接口错误代码定义和说明......................................................37

附录D(资料性附录)政务数字证书典型应用框架图..............................................................................38

D.1典型应用框架图........................................................................................................................................38

D.2典型业务流程分析....................................................................................................................................39

附录E(资料性附录)政务数字证书典型应用示例..................................................................................40

E.1程序基本流程............................................................................................................................................40

E.2程序示例说明............................................................................................................................................40

I

DB11/T254.2-2004

前言

DB11/T254-2004《政务数字证书规范》分为二个部分：

——第1部分：格式；

——第2部分：应用接口。

本部分为DB11/T254-2004的第2部分。

本部分从总体上同国家相关标准保持一致，并结合北京市实际工作特点而制定。

本部分的附录A、附录B和附录C是规范性附录，附录D和附录E是资料性附录。

本部分由北京市信息化工作办公室提出并归口。

本部分主要起草单位：北京数字证书认证中心、中国科学院研究生院信息安全国家重点实验室、北

京市国家保密局、北京市国密办。

本部分主要起草人：阳俊彪、姚世全、陈淑仪、高能、张秀娟、孙永、荆继武、李述胜。

II

DB11/T254.2-2004

引言

信息技术和网络技术在极大地促进了社会的经济、科技、文化、教育和管理等各个方面发展的同时，

又带来了巨大的信息安全风险。随着北京市电子政务工程的不断深入和发展，迫切需要在开放的网络环

境下建立一个真实、有效的身份信任体制，确认电子政务参与方的各自身份，建立彼此间的信任关系以

及保证信息的保密性、完整性和可用性。以PKI为核心的网络身份认证体系和信息加密技术已成为业界

广泛认同的一种构造网络身份信任体制的重要方式，并成为信息安全保障体系中极其重要的组成部分之

一。

数字证书应用接口是PKI技术应用的关键和核心，是电子政务应用系统使用和应用PKI技术的桥梁。

为了确保政务数字证书在电子政务信息的应用中能够通用，实现信息系统互联互通，统一数字证书应用

接口规范，更好形成统一的网络信任体系。

III

DB11/T254.2-2004

政务数字证书规范第2部分：应用接口

1范围

本部分规定了政务数字证书应用接口体系结构，各个接口函数的函数名称、参数和返回值以及政务

数字证书应用接口所需的宏定义、数据结构和错误代码。

本部分适用于数字证书认证机构、数字证书认证系统的开发商、电子政务应用部门以及基于数字证

书的安全应用开发商进行信息系统建设。

应用于电子商务领域的数字证书应用接口，也可参照本部分。

本部分不涉及任何具体的密码运算，所有密码运算均在符合国家有关法规的密码设备中进行。

本部分凡涉及密码相关内容，按国家有关法规实施。

2规范性引用文件

下列文件中的条款通过本部分的引用而成为本部分的条款。凡是注日期的引用文件，其随后所有的

修改单（不包括勘误的内容）或修订版均不适用于本部分，然而，鼓励根据本部分达成协议的各方研究

是否可使用这些文件的最新版本。凡是不注日期的引用文件，其最新版本适用于本部分。

ISO/IEC8825-1：1998，信息技术-ASN.1编码规则：基本编码规则（BER）的规范，正规编码规则

（CER）和可区分编码规则（DER）

IETFRFC3280InternetX.509PublicKeyInfrastructureCertificateandCertificate

RevocationList(CRL)Profile因特网X.509公开密钥基础设施证书与证书撤销列表轮廓

PKCS1:RSACryptographyStandardPKCS1：RSA密码标准

PKCS7:CryptographicMessageSyntaxStandardPKCS7：密码消息语法标准

3术语和定义、缩略语

3.1术语和定义

下列术语和定义适用于本部分。

3.1.1

证书认证机构（CA）certificationauthority(CA)

受用户信任，负责创建和分配证书的权威机构。

3.1.2

证书验证certificatevalidation

确认证书在给定时间有效的过程，可能包含一个证书认证路径的构造和处理，确保该路径上的所有

证书在给定时间有效（即证书没有被撤销或者过期）。

3.1.3

证书撤销列表（黑名单）certificaterevocationlist(CRL)

一个已标识的列表，它指定了一系列证书发布者认为无效的证书。

3.1.4

数字证书（证书）digitalcertificate

由国家认可的、由CA进行数字签名的一个可信的数字化文件。数字证书包含有公开密钥拥有者的信

息、公开密钥、签名算法和CA的数字签名。

3.1.5

政务数字证书governmentaffairdigitalcertificate

1

DB11/T254.2-2004

用来标识电子政务参与方真实身份的数字证书。根据参与方的不同类别分为政务证书认证机构证

书、政务个人证书、政务机构证书、政务设备证书、政务代码签名证书。

3.1.6

私有密钥（私钥）privatekey

（在公钥密码体制中）用户密钥对中仅为该用户所知的密钥。

3.1.7

公开密钥（公钥）publickey

（在公钥密码体制中）用户密钥对中公布给公众的密钥。

3.1.8

公开密钥基础设施（PKI）publickeyinfrastructure

支持公钥管理体制的基础设施，提供鉴别、加密、完整性和不可否认性服务。

3.1.9

信任trust

通常，当一个实体假设另一个实体完全按照前者的期望行动时，则称前者“信任”后者。这种“信任”

可能只适用于某些特定功能。本部分中“信任”的关键作用是描述鉴别实体和权威机构之间的关系；鉴别

实体应确信它能够“信任”权威机构仅创建有效且可靠的证书。

3.2缩略语

下列缩略语适用于本部分：

API应用程序接口（ApplicationProgrammingInterface），简称应用接口

CA证书认证机构（CertificationAuthority）

CN通用名（CommonName）

CRL证书撤销列表（黑名单）（CertificateRevocationList）

CSP加密服务提供者（CryptographicServiceProvider）

DER可区分编码规则（DistinguishedEncodingRules）

DN可辨别名（DistinguishedName）

LDAP轻量级目录访问协议（LightweightDirectoryAccessProtocol）

OID对象标识符（ObjectIdentifier）

PKCS公钥密码使用标准(thePublic-KeyCryptographyStandard)

4政务数字证书应用接口

4.1数字证书应用接口体系结构

证书数字证书应用接口体系结构，如图1所示：

2

DB11/T254.2-2004

身份认证保密性完整性不可否认性

应用程序应用层

政务数字证书应用接口

环境函数设备管理函数证书函数消息函数

接口层

密码服务函数

密码设备（加密机、加密卡、智能IC卡和USBKEY等）

设备层

密钥

图1政务数字证书应用接口体系结构

政务数字证书应用接口位于应用系统和密码设备之间，应用程序通过调用政务数字证书应用接口实

现身份认证、实现信息的保密性、完整性和不可否认性；政务数字证书应用接口通过标准接口，在密码

设备中实现具体的密码运算和密钥使用。

政务数字证书应用接口通过支持PKCS11和CSP接口方式，屏蔽各类密码设备（加密机、加密卡、智

能IC卡和智能USBKEY等）的设备差异性，屏蔽各类密码设备的密码应用接口的差异性，实现应用程序

与密码设备无关性。

政务数字证书应用接口提供的消息函数符合PKCS7格式。

政务数字证书应用接口证书格式按DB11/TXXXX.1-2004执行，证书解码按ISO/IEC8825-1执行，黑

名单（CRL）解码按IETFRFC3280执行，公钥加密体系按PKCS1和PKCS7执行。

本部分在证书和CRL获取上，支持LDAP方式。

本部分中所引用的MD2、MD5、SHA-1和RSA密码算法均为举例说明。

4.2数字证书应用接口组成和功能说明

数字证书应用接口由以下部分组成：

·环境函数

·设备管理函数

·证书函数

·密码服务函数

·消息函数

4.2.1环境函数

3

DB11/T254.2-2004

环境函数负责创建和管理安全程序空间，负责创建和管理安全程序空间中所需的各种资源、信号，

并确保安全程序空间在应用程序运行期间不会被非法访问，造成信息泄漏。环境函数负责完成与密码设

备的安全连接，确保后续的安全操作是在安全、可信的程序空间中进行。

应用程序在使用政务数字证书应用接口时，要首先调用初始化环境函数（PKI_Initialize）创建和

初始化安全的应用程序空间，完成与密码设备连接和初始化工作。在中止应用程序之前，应调用清除环

境函数（PKI_Finalize），中止与密码设备的连接，销毁所创建的安全程序空间，防止由于内存残留所

带来的安全风险。

4.2.2设备管理函数

设备管理函数负责在用户与密码设备之间创建和管理安全访问令牌。设备管理函数支持创建两种类

型的用户安全访问令牌，一种是普通用户，该类型的安全访问令牌标识该用户是普通用户，只能访问密

码设备中属于私有的信息和数据；另一类是超级用户（或安全官员），该类型的安全访问令牌标识该用

户是超级用户（安全官员），可以访问密码设备中的公有信息，设置和修改普通用户的PIN。

应用程序在调用任何密码服务函数，进行任何密码运算之前都必须首先调用设备管理函数的用户登

录函数（PKI_Login），建立安全访问令牌。建立了安全访问令牌后，则可以调用任何密码服务函数。

在不再调用任何密码服务函数，应调用注销登录函数（PKI_Logout）注销安全访问令牌，确保密码设备

不被非法访问。另外，用户可以定期通过调用修改PIN函数（PKI_ChangePin），修改创建安全访问令牌

时所需提供的PIN，确保密码设备不被非法使用。

4.2.3证书函数

证书函数主要是设置各类数字证书到应用接口会话环境中、验证用户证书和获取数字证书或黑名

单，提供了包括证书获取、黑名单（CRL）获取、可信根CA证书设置、用户证书验证和用户证书信息获

取等一系列具体函数。应用程序通过调用证书函数，可以很方便地实现基于数字证书的身份认证，从证

书中获取有关信息，实现授权管理、访问控制等安全机制。

证书函数在具体使用中，要先通过调用证书和CRL获取函数或其他途径，获取相关证书和黑名单

（CRL）,然后调用相关的证书设置函数：添加信任的CA根证书、添加CA证书、设置用户证书等设置证书

应用环境。在此基础上，调用相关函数进行证书验证，实现用户身份认证；调用取证书信息和取证书扩

展信息获取证书中有关信息，实现授权管理和访问控制等安全机制。

4.2.4密码服务函数

密码服务函数负责具体与密码设备交互实现具体地密码运算，并将密码运算后地结果返回给应用程

序，是应用程序实现数据保密性、完整性和不可否认性等安全机制的基础。

密码服务函数提供包括BASE64编解码、随机数生成、数字摘要以及各种对称和非对称密码运算等共

39个具体的函数。密码服务函数支持定长数据和不定长数据的密码运算，对于定长数据可以直接调用相

关函数进行处理；对于不定长数据，需要先创建相应的密码运算对象，然后调用相应的函数对数据进行

持续处理。当数据处理完时，要调用相应的函数表示数据处理完，最后要调用相应函数销毁相应的密码

运算对象。

密码服务函数在整个政务数字证书应用接口中属于底层函数，并不是所有的密码服务函数都必须在

应用程序中使用。

4.2.5消息函数

消息函数主要是将数据按照PKCS7格式进行封装，实现数据封装格式与应用系统无关性，实现应用

系统互联互通和信息共享。

4

DB11/T254.2-2004

消息函数提供了PKCS7格式的数据编解码、PKCS7格式的签名数据编解码和PKCS7格式的数字信封编

解码，能够非常方便应用程序实现身份认证、保密性、完整性和不可否认性等安全措施。

5政务数字证书应用接口函数定义

以下所定义的函数，除明确说明外，其接口参数都不能为空。

5.1环境函数

环境函数包括以下具体函数：

·初始化环境：PKI_Initialize

·清除环境：PKI_Finalize

·获取接口版本信息：PKI_GetVersion

5.1.1初始化环境PKI_Initialize

函数名称PKI_RV

PKI_Initialize(

unsignedlongproviderType,

char*providerParameter,

char*devMngApi);

功能简介初始化安全应用程序空间

参数说明providerType[IN]:密码服务模块类型

当providerType==PKI_PROVIDER_CSP时

providerParameter:CSP的名称

devMngApi：设备管理接口库路径

当providerType==PKI_PROVIDER_PKCS11时

providerParameter:PKCS11库的路径

devMngApi：设备管理接口库路径

返回值RV_OK：成功

其他：失败

5.1.2清除环境：PKI_Finalize

函数名称PKI_RV

PKI_Finalize(void);

功能简介清除应用程序空间

参数说明无

返回值RV_OK：成功

其他：失败

5.1.3获取接口版本信息：PKI_GetVersion

5

DB11/T254.2-2004

函数名称PKI_RV

PKI_GetVersion(

unsignedlong*versoin)

功能简介取接口版本号

参数说明version[OUT]:版本号

version的高2字节表示主版本号，低2字节表示次版本号

返回值RV_OK：成功

其他：失败

5.2设备管理函数

设备管理函数包括以下具体函数：

·用户登录：PKI_Login

·修改PIN：PKI_ChangePin

·注销登录：PKI_Logout

5.2.1用户登录：PKI_Login

函数名称PKI_RV

PKI_Login(unsignedlongusrType,

unsignedchar*pin,

unsignedlongpinLen)

功能简介用户登录密码设备，建立安全令牌。

参数说明usrType[IN]：用户类型//0:SUPER_LOGIN1:USR_LOGIN

pin[IN]：设备口令

pinLen[IN]：设备口令长度

返回值RV_OK：成功

其他：失败

5.2.2修改PIN：PKI_ChangePin

函数名称PKI_RV

PKI_ChangePin(unsignedlongusrType,

unsignedchar*oldPin,

unsignedlongoldPinLen,

unsignedchar*newPin,

unsignedlongnewPinLen);

功能简介修改设备PIN

参数说明usrType[IN]:用户类型//0:SUPER_LOGIN1:USR_LOGIN

oldPin[IN]：设备当前口令

6

DB11/T254.2-2004

oldPinLen[IN]：设备当前口令长度

newPin[IN]：设备新口令

newPinLen[IN]：设备新口令长度

返回值RV_OK：成功

其他：失败

5.2.3注销登录：PKI_Logout

函数名称PKI_RV

PKI_Logout(unsignedlongusrType)

功能简介设备注销登录

参数说明usrType[IN]:用户类型//0:SUPER_LOGIN1:USR_LOGIN

返回值RV_OK：成功

其他：失败

5.3证书函数

证书函数包括以下具体函数：

·添加信任的CA根证书：PKI_AddTrustedRootCaCertificate

·添加CA证书：PKI_AddCaCertificate

·添加黑名单：PKI_AddCrl

·设置用户证书：PKI_SetUsrCertificate

·获取用户证书：PKI_GetUsrCertificate

·验证用户证书：PKI_VerifyUsrCertificate

·根据CRL文件验证用户证书是否被注销：PKI_VerifyUsrCertificateByCrl

·OCSP在线证书状态查询：PKI_OcspVerifyCertificate

·通过LDAP方式获取证书：PKI_GetCertFromLdap

·通过LDAP方式根据证书获取CRL：PKI_GetCrlFromLdap

·取证书信息：PKI_GetCertificateInfo

·取证书扩展信息：PKI_GetExtTypeInfo

5.3.1添加信任的CA根证书：PKI_AddTrustedRootCaCertificate

函数名称PKI_RV

PKI_AddTrustedRootCaCertificate(

unsignedchar*certificate,

unsignedlongcertificateLen);

功能简介添加信任的CA根证书

参数说明certificate[IN]:DER编码的证书

certificateLen[IN]:DER编码的证书长度

返回值RV_OK：成功

其他：失败

7

DB11/T254.2-2004

5.3.2添加CA证书：PKI_AddCaCertificate

函数名称PKI_RV

PKI_AddCaCertificate(

unsignedchar*certificate,

unsignedlongcertificateLen);

功能简介添加CA证书

参数说明certificate[IN]:DER编码的证书

certificateLen[IN]:DER编码的证书长度

返回值RV_OK：成功

其他：失败

5.3.3添加黑名单：PKI_AddCrl

函数名称PKI_RV

PKI_AddCrl(

unsignedchar*derCrl,

unsignedlongderCrlLen);

功能简介添加黑名单

参数说明derCrl[IN]:DER编码的CRL

derCrlLen[IN]:DER编码的CRL长度

返回值RV_OK：成功

其他：失败

5.3.4设置用户证书：PKI_SetUsrCertificate

函数名称PKI_RV

PKI_SetUsrCertificate(

unsignedchar*containerName,

unsignedlongcontainerLen,

unsignedlongkeyUsage,

unsignedchar*certificate,

unsignedlongcertificateLen);

功能简介设置用户证书

参数说明containerName[IN]:密钥的容器名

containerNameLen[IN]:密钥的容器名长度

keyUsage[IN]:密钥用途

certificate[IN]:DER编码的证书

8

DB11/T254.2-2004

certificateLen[IN]:DER编码的证书长度

返回值RV_OK：成功

其他：失败

5.3.5获取用户证书：PKI_GetUsrCertificate

函数名称PKI_RV

PKI_GetUsrCertificate(

unsignedchar*containerName,

unsignedlongcontainerLen,

unsignedlongkeyUsage,

unsignedchar*certificate,

unsignedlong*certificateLen);

功能简介获取用户证书

参数说明containerName[IN]:容器名

containerNameLen[IN]:容器名长度

keyUsage[IN]:密钥用途

certificate[OUT]:DER编码的证书

certificateLen[OUT]:DER编码的证书长度

返回值RV_OK：成功

其他：失败

5.3.6验证用户证书：PKI_VerifyUsrCertificate

函数名称PKI_RV

PKI_VerifyUsrCertificate(

unsignedchar*usrCertificate,

unsignedlongusrCertificateLen);

功能简介验证用户证书

参数说明usrCertificate[IN]:DER编码的证书

usrCertificateLen[IN]:DER编码的证书长度

返回值RV_OK：成功

其他：失败

5.3.7根据CRL文件验证用户证书是否被注销：PKI_VerifyUsrCertificateByCrl

函数名称PKI_RV

PKI_VerifyUsrCertificateByCrl(

unsignedchar*usrCertificate,

9

DB11/T254.2-2004

unsignedlongusrCertificateLen,

unsignedchar*derCrl,

unsignedlongderCrlLen);

功能简介根据CRL文件验证用户证书是否被注销

参数说明usrCertificate[IN]:DER编码的证书

usrCertificateLen[IN]:DER编码的证书长度

derCrl[IN]:DER编码的黑名单

derCrlLen:DER编码的黑名单长度

返回值RV_OK：成功

其他：失败

5.3.8OCSP在线证书状态查询：PKI_OcspVerifyCertificate

函数名称PKI_RV

PKI_OcspVerifyCertificate(

char*ocspServerIpAddress,

unsignedlongocspServerPort,

unsignedchar*derRequestCert,

unsignedlongderRequestCertLen,

unsignedcharneedVerifedCert,

unsignedlongneedVerifedCertLen,

unsignedlong*certStatus);

功能简介通过OCSP验证证书的当前状态

参数说明ocspServerIpAddress[IN]:OCSPServerIP

ocspServerPort[IN]:OCSPServerPort

derRequestCert[IN]:发起OCSP申请的用户证书

derRe