ICS 35.240.30 L 70 DB11 北 京 市 地 方 标 准 DB11/T 254.2—2018 代替 DB11/T 254.2-2004 政务数字证书规范 第 2 部分：应用接口 Specification for digital certificate for government affairs Part 2: Application Programming Interface 2018 - 04 - 04 发布 北京市质量技术监督局 2018 - 07 - 01 实施 发 布 DB11/T 254.2—2018 目 次 前 言............................................................................. II 引 言............................................................................ III 1 范围............................................................................... 1 2 规范性引用文件..................................................................... 1 3 术语和定义、缩略语 ................................................................. 1 4 结构组成........................................................................... 2 5 政务数字证书应用接口定义 ........................................................... 2 附录 A（规范性附录） 政务数字证书应用接口错误代码定义和说明 ......................... 13 附录 B（资料性附录） 政务数字证书典型调用示例 ....................................... 15 I DB11/T 254.2—2018 前 言 本部分按照GB/T 1.1—2009给出的规则起草。 DB11/T 254.2—2018《政务数字证书规范》分为两个部分： ——第1部分：格式； ——第2部分：应用接口。 本部分为DB11/T 254—2018的第2部分。 本部分代替DB11/T 254.2—2004《政务数字证书规范 第2部分：应用接口》。本部分根据电子政务 中数字证书接口的使用情况，对原有标准的内容进行了结构上的调整，重新定义了接口的架构和接口的 形式。新的接口以GM/T 0020—2012 《证书应用综合服务接口规范》中的定义为主，并加入法人一证通 项目实施所需的扩展接口。详细修订包括： ——第2章，引用了密码行业标准； ——第4章，重新命名为“结构组成”，并将接口的组成部分重新定义为设备管理接口、访问控制 接口、容器管理接口、密码服务接口、证书接口和通用接口； ——第5章，按照第4章定义的结构重新定义接口，新的接口采用COM接口形式，在第5章的内容中， 加入了符合密码行业标准的接口，接口内容参照了密码行业的相关标准； ——删除原附录A“政务数字证书应用接口宏定义和说明”，改为“政务数字证书应用接口错误代 码定义和说明（规范性附录）”，在其中给出了政务数字证书接口的错误码定义； ——删除了原附录B“政务证书应用接口数据结构定义和说明”，改为“政务数字证书典型调用示 例（资料性附录）”； ——删除原附录C“政务数字证书应用接口错误代码定义和说明”； ——删除原附录D“政务数字证书典型应用框架图”； ——删除原附录E“政务数字证书典型应用示例”。 本部分由北京市经济和信息化委员会提出并归口。 本部分由北京市经济和信息化委员会组织实施。 本部分主要起草单位：北京市经济和信息化委员会、北京数字认证股份有限公司、中国科学院信息 工程研究所、北京市国家保密局、北京市密码管理局。 本部分主要起草人：潘锋、刘惠刚、刘莎、姚世全、陈淑仪、高能、荆继武、李述胜、李向锋。 DB11/T 254.2—2018 引 言 信息技术和网络技术在极大地促进了社会的经济、科技、文化、教育和管理等各个方面发展的同时， 也带来了巨大的信息安全风险。随着北京市电子政务工程的不断深入和发展，迫切需要在开放的网络环 境下建立一个真实、有效的身份信任体制，确认电子政务参与方的各自身份，建立彼此间的信任关系以 及保证信息的保密性、完整性和可用性。以公开密钥基础设施（Public Key Infrastructure，PKI）为 核心的网络身份认证体系和信息加密技术已成为业界广泛认同的一种构造网络身份信任体制的重要方 式，并成为信息安全保障体系中极其重要的组成部分之一。 数字证书应用接口是PKI技术应用的关键和核心，是电子政务应用系统使用和应用PKI技术的桥梁。 为了确保政务数字证书在电子政务信息的应用中能够通用，实现信息系统互联互通，统一数字证书应用 接口规范，能够有效降低数字证书应用集成的复杂度，有助于更好形成统一的网络信任体系。本部分定 义了政务数字证书应用的系统架构，并定义了政务数字证书应用的各种接口。 III DB11/T 254.2—2018 政务数字证书规范 第 2 部分：应用接口 1 范围 本部分规定了电子政务外网中数字证书应用接口体系结构，各个接口函数的接口原型、功能、参数 和返回值以及政务数字证书应用接口所需的宏定义、错误代码和调用示例。 本部分适用于数字证书认证机构、数字证书认证系统的开发商、电子政务应用部门以及基于数字证 书的安全应用开发商进行信息系统建设。 应用于电子商务领域的数字证书应用接口，也可参照本部分。 2 规范性引用文件 下列文件对于本部分的应用是必不可少的。凡是注日期的引用文件，仅注日期的版本适用于本部分。 凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本部分。 GB/T 25069—2010 信息安全技术 术语 GM/T 0009—2012 SM2密码算法使用规范 GM/T 0010—2012 SM2密码算法加密签名消息语法规范 3 术语和定义、缩略语 3.1 术语和定义 GB/T 25069—2010界定的以及下列术语和定义适用于本文件。 3.1.1 信任 trust 当一个实体假设另一个实体完全按照前者的期望行动时，则称前者“信任”后者。这种“信任”可能 只适用于某些特定功能。本部分中“信任”的关键作用是描述鉴别实体和权威机构之间的关系；鉴别实 体应确信它能够“信任”权威机构仅创建有效且可靠的证书。 3.2 缩略语 下列缩略语适用于本部分： CA 证书认证机构（Certification Authority） COM 组件对象模型（Component Object Model） CSP 加密服务提供者（Cryptographic Service Provider） OID 对象标识符（Object Identifier） PKCS 公钥密码使用标准(the Public-Key Cryptography Standard) 4 结构组成 1 DB11/T 254.2—2018 4.1 数字证书应用体系结构 4.1.1 政务证书数字证书应用的一般体系结构，如图 1 所示： 政务数字证书应用 身份认证 机密性 完整性 不可否认性 应用层 应用程序 政务数字证书应用接口 设备管理接口 访问控制接口 容器管理接口 密码服务接口 证书接口 接口层 设备接口 密码设备 密钥 密钥 ... 密钥 图1 数字证书应用架构 4.1.2 政务数字证书应用接口位于应用层和密码设备之间，应用程序通过调用政务数字证书应用接口 实现身份认证、实现信息的机密性、完整性和不可否认性；政务数字证书应用接口通过设备所提供的接 口进行对设备的调用。在密码设备中实现具体的密码运算和密钥使用。 4.2 数字证书应用接口组成和功能说明 数字证书应用接口由以下几个接口部分组成： ——设备管理接口：负责对所连接的密码设备进行管理、获取密码设备的信息； ——访问控制接口：负责确认用户是否允许连接使用密码设备，包括口令验证和修改口令等接口； ——容器管理接口：负责对所连接的密码设备中的容器进行管理； ——密码服务接口： 负责具体与密码设备交互实现具体的密码运算， 并将运算结果返回给应用程序； ——证书接口：负责数字证书的解析、证书信息的获取、有效性检查等功能； ——通用接口：负责提供通用类的处理功能。 5 政务数字证书应用接口定义 5.1 类型说明 本部分中的相关接口，均采用 COM 形式来为例来进行描述。应用接口的错误码定义和说明见附录A， 使用JavaScript进行接口调用的示例参见附录B。接口中主要使用到的数据类型定义列举如下： boolean： 2 表示一个布尔值，取值为1（True）和0（False）。 DB11/T 254.2—2018 LONG： BSTR： 表示一个有符号长整数，其位数与取值范围与特定的平台有关。 BSTR代表一个OLECHAR字符串类型的数据。 5.2 设备管理接口 5.2.1 获取设备数量 获取设备数量接口定义如下： 接口原型： LONG GetDeviceCount() 功能描述： 获取当前存在的可支持的设备数量 参数： 无 返回值： 设备数量 备注： 无 5.2.2 获取所有的设备序列号 获取所有设备序列号接口定义如下： 接口原型： BSTR GetAllDeviceSN() 功能描述： 获取当前存在的可支持的所有设备的序列号，每个设备序列号以分号(;)结尾 参数： 无 返回值： 所有设备序列号的组合 备注： 当前存在所有设备序列号，例如"11111;22222;"，各个设备序列号间使用半角的冒号 （:）来分隔 5.2.3 根据索引获取设备序列号 根据索引获取设备序列号接口定义如下： 接口原型： BSTR GetDeviceSNByIndex(LONG iIndex) 功能描述： 根据索引获取设备的序列号 参数： iIndex[IN] 索引，从0开始，不能大于当前存在的设备数量 返回值： 成功返回设备序列号，失败返回空 备注： 无 5.2.4 判断设备是否存在 判断设备是否存在接口定义如下： 接口原型： boolean IsDeviceExist(B