1、ICS 35.240.30 L 70 备案号 ：58907-2018 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 I 目 次
2、前 言 II 引 言 . III 1 范围 1 2 规 范性 引用 文件 1 3 术 语和 定义 、缩 略语 1 4 结 构组 成 1 5 政 务数 字证 书应 用接 口 定义 2 附录A （规 范性 附录 ） 政务数 字证 书应 用接 口错 误代码 定义 和说 明 . 13 附录B （资 料性 附录 ） 政务数 字证 书典 型调 用示 例 . 15 DB11/T 254.2 2018 II 前 言 本部分 按照GB/T 1.1 2009 给出 的规 则起 草。 DB11/T 254.22018 政 务数字 证书 规范 分 为两 个部分 ： 第1部 分： 格式 ； 第2部 分： 应用 接口 。
3、 本部分 为DB11/T 254 2018 的第2 部分 。 本部分 代替DB11/T 254.2 2004 政务 数字 证书 规 范 第2 部分： 应用 接口 。 本部 分根据 电子 政 务 中数字 证书 接口 的使 用情 况， 对 原有 标准 的内 容进 行了结 构上 的调 整， 重新 定义了 接口 的架 构 和 接 口 的 形式。 新的接 口以GM/T 0020 2012 证书 应用 综合 服务接 口规 范 中 的定 义 为主， 并加入 法人 一证 通 项目实 施所 需的 扩展 接口 。 详细 修订 包括 ： 第2 章 ，引 用了 密码 行 业 标准 ； 第4 章， 重新命 名为 “ 结
4、构组 成”， 并将 接口的 组成部 分重新 定义 为设备 管理接 口、访 问控 制 接口、 容器 管理 接口 、密 码服务 接口 、证 书接 口和 通用接 口； 第5 章 ，按 照第4 章定 义的结 构重 新定 义接 口， 新的接 口采 用COM接 口形 式 ，在第5 章 的内 容中 ， 加入了 符合 密码 行业 标准 的接口 ，接 口内 容参 照了 密码行 业的 相关 标准 ； 删 除原附 录A“ 政务 数 字证书 应用接 口宏 定义和 说明” ，改为 “政 务数字 证 书应 用接口 错误 代 码定义 和说 明（ 规范 性附 录）” ，在 其中 给出 了政 务数字 证书 接口 的错 误码 定
5、义； 删 除了原 附录B “政 务 证书应 用接口 数据 结构定 义和说 明”， 改为 “政务 数字证 书典型 调用 示 例（资 料性 附录 ）” ； 删 除原 附录C “ 政务 数 字证书 应用 接口 错误 代码 定义和 说明 ”； 删 除原 附录D “ 政务 数 字证书 典型 应用 框架 图” ； 删 除原 附录E “ 政务 数 字证书 典型 应用 示例 ”。 本部分 由北 京市 经济 和信 息化委 员会 提出 并归 口 。 本部分 由北 京市 经济 和信 息化委 员会 组织 实施 。 本部分 主要 起草 单位 ： 北 京市经 济和 信息 化委 员会 、 北 京数 字认 证股 份有 限 公
6、司 、 中 国科 学院 信息 工程研 究所 、北 京市 国家 保密局 、北 京市 密码 管理 局。 本部分 主要 起草 人： 潘锋 、刘惠 刚、 刘莎 、姚 世全 、陈淑 仪、 高能 、荆 继武 、李述 胜、 李向 锋。 DB11/T 254.2 2018 III 引 言 信息技 术和 网络 技术 在极 大地促 进了 社会 的经 济、 科 技、 文 化、 教育 和管 理等 各 个方面 发展 的同 时， 也带来 了巨 大的 信息 安全 风险。 随着 北京 市电 子政 务工程 的不 断深 入和 发展 ， 迫切 需要 在开 放 的 网 络 环 境下建 立一 个真 实 、 有 效 的身份 信任 体制
7、， 确认 电 子政务 参与 方的 各自 身份 ， 建 立彼 此间 的信 任关 系 以 及保证 信息 的保 密性 、完 整性和 可用 性。 以公 开密 钥基础 设施 （Public Key Infrastructure ，PKI ）为 核 心 的网 络 身份 认 证体 系和 信 息加 密 技术 已 成为 业界 广 泛认 同 的一 种 构造 网络 身 份信 任 体制 的 重要方 式，并 成为 信息 安全 保障 体系中 极其 重要 的组 成部 分之一 。 数字证 书应 用接 口是PKI 技 术应用 的关 键和 核心 ，是 电子政 务应 用系 统使 用和 应用PKI技 术的 桥梁 。 为了确 保政 务
8、数 字证 书在 电子政 务信 息的 应用 中能 够通用 ， 实 现信 息系 统互 联互通 ， 统 一数 字 证 书 应 用 接口规 范 ， 能 够有 效降 低 数字证 书应 用集 成的 复杂 度， 有助 于更 好形 成统 一 的网络 信任 体系 。 本部 分 定 义了政 务数 字证 书应 用的 系统架 构， 并定 义了 政务 数字证 书应 用的 各种 接口 。 DB11/T 254.2 2018 1 政 务数字 证书规范 第 2 部分 ：应用 接口 1 范围 本部分 规定 了电 子政 务外 网中数 字证 书应 用接 口体 系结构 ， 各个 接口 函数 的 接口原 型 、 功 能、 参数 和返回
9、 值以 及政 务数 字证 书应用 接口 所需 的宏 定义 、错误 代码 和调 用示 例。 本部分 适用 于数 字证 书认 证机构 、 数 字证 书认 证系 统的开 发商 、 电 子政 务应 用部门 以及 基于 数字 证 书的安 全应 用开 发商 进行 信息系 统建 设。 应用于 电子 商务 领域 的数 字证书 应用 接口 ，也 可参 照本部 分。 2 规范性 引用 文件 下列文 件对 于本 部分 的应 用是必 不可 少的 。 凡 是注 日 期的引 用文 件， 仅注 日期 的 版本适 用于 本部 分。 凡是不 注日 期的 引用 文件 ，其最 新版 本（ 包括 所有 的修改 单） 适用 于本 部分
10、 。 GB/T 25069 2010 信息 安全技 术 术语 GM/T 0009 2012 SM2 密 码算法 使用 规范 GM/T 0010 2012 SM2 密 码算法 加密 签名 消息 语法 规范 3 术语和 定义 、缩 略语 3.1 术语和 定义 GB/T 250692010界 定的 以及下 列术 语和 定义 适用 于本文 件。 3.1.1 信任 trust 当一个 实体 假设 另一 个实 体完全 按照 前者 的期 望行 动时 ， 则 称前 者“ 信任” 后 者。 这种 “ 信任 ” 可能 只适用 于某 些特 定功 能。 本部分 中 “ 信任 ” 的 关键 作用是 描述 鉴别 实体 和
11、权 威机构 之间 的关 系； 鉴 别 实 体应确 信它 能够 “信 任” 权威机 构仅 创建 有效 且可 靠的证 书。 3.2 缩略语 下列缩 略语 适用 于本 部分 ： CA 证 书认 证机 构（Certification Authority ） COM 组 件对 象模 型（Component Object Model ） CSP 加 密服 务提 供者 （Cryptographic Service Provider ） OID 对 象标 识符 （Object Identifier ） PKCS 公 钥密 码使 用标 准(the Public-Key Cryptography Standard
12、) 4 结构组 成 DB11/T 254.2 2018 2 4.1 数字证 书应 用体 系结 构 4.1.1 政务证 书数 字证 书应 用的 一般体 系结 构， 如 图 1 所 示： 政务数字证书应用 应用层 应用程序 身份认证 机密性 完整性 不可否认性 政务数字证书应用接口 设备管理接口 访问控制接口 容器管理接口 密码服务接口 证书接口 密码设备 密钥 密钥 . 密钥 接口层 设备接口图1 数字证 书应 用架 构 4.1.2 政务数 字证 书应 用接 口位 于应用 层和 密码 设备 之间 ，应用 程序 通过 调用 政务 数字证 书应 用接 口 实现身 份认 证 、 实 现信 息 的机密
13、性 、 完 整性 和不 可 否认性 ； 政务 数字 证书 应 用接口 通过 设备 所提 供的 接 口进行 对设 备的 调用 。在 密码设 备中 实现 具体 的密 码运算 和密 钥使 用。 4.2 数字证 书应 用接 口组 成和 功能说 明 数字证 书应 用接 口由 以下 几个接 口部 分组 成： 设备管 理接 口： 负责 对所 连接的 密码 设备 进行 管理 、获取 密码 设备 的信 息 ； 访问控 制接 口： 负责 确认 用户是 否允 许连 接使 用密 码设备 ，包 括口 令验 证和 修改口 令等 接 口 ； 容器管 理接 口： 负责 对所 连接的 密码 设备 中的 容器 进行管 理； 密码
14、服 务接 口： 负责 具体 与 密码设 备交 互实 现具 体的 密码运 算， 并将 运算 结果 返 回给应 用程 序； 证书接 口： 负责 数字 证书 的解析 、证 书信 息的 获取 、有效 性检 查等 功能 ； 通用接 口： 负责 提供 通用 类的处 理功 能。 5 政务数 字证 书应 用接 口定 义 5.1 类型说 明 本部分 中的 相关 接口 ， 均 采 用 COM 形 式来 为例 来进 行 描述。 应用 接口 的错 误码 定 义和说 明见 附录A ， 使用JavaScript 进行 接口 调用的 示例 参见 附 录B。 接 口中主 要使 用到 的数 据类 型定义 列举 如下 ： boo
15、lean ： 表 示一 个布 尔值， 取值 为1 （True）和0（False）。 DB11/T 254.2 2018 3 LONG： 表 示一 个有 符号长 整数 ，其 位数 与取 值范围 与特 定的 平台 有关 。 BSTR： BSTR代 表一 个OLECHAR 字符 串类 型的 数 据。 5.2 设备管 理接 口 5.2.1 获取设 备数 量 获取设 备数 量接 口定 义如 下： 接口原 型： LONG GetDeviceCount() 功能描 述： 获 取当 前存 在的可 支持 的设 备数 量 参数： 无 返回值 ： 设 备数 量 备注： 无 5.2.2 获 取所 有的 设备 序列 号
16、 获取所 有设 备序 列号 接口 定义如 下： 接口原 型： BSTR GetAllDeviceSN() 功能描 述： 获取 当前 存在 的可 支持 的所有 设备 的序 列号 ，每 个设备 序列 号以 分号(;) 结尾 参数： 无 返回值 ： 所 有设 备序 列号的 组合 备注： 当前存 在所 有设 备序 列号 ， 例如“11111;22222;“ ， 各 个设备 序列 号间 使用 半角 的冒号 （:） 来分 隔 5.2.3 根据索 引获 取设 备序 列号 根据索 引获 取设 备序 列号 接口定 义如 下： 接口原 型： BSTR GetDeviceSNByIndex(LONG iIndex)
17、 功能描 述： 根 据索 引获 取设备 的序 列号 参数： iIndexIN 索 引， 从0开始 ，不 能大 于当 前存 在 的设备 数量 返回值 ： 成 功返 回设 备序列 号， 失败 返回 空 备注： 无 5.2.4 判断设 备是 否存 在 判断设 备是 否存 在接 口定 义如下 ： 接口原 型： boolean IsDeviceExist(BSTR sDeviceSN) 功能描 述： 判 断设 备是 否存在 参数： sDeviceSNIN 设备序 列号 返回值 ： 存 在返 回TRUE ，不 存在 返回FALSE 备注： 无 5.2.5 获取设 备详 细信 息 获取设 备详 细信 息接
18、口定 义如下 ： 接口原 型： BSTR GetDeviceInfo(BSTR sDeviceSN, LONG iType) 功能描 述： 获 取设 备详 细信息 参数： sDeviceSNIN 设备序 列号 iTypeIN 信 息 类型 DB11/T 254.2 2018 4 返回值 ： 成 功返 回设 备信息 ，失 败返 回空 备注： 目 前可 支持 的类型 参数 为： 0x00000001 设备 标签 0x00000002 设备 空余空 间 0x00000003 设备 序列号 0x00000004 设备 类型 返回“RSA“ 或“SM2“ 0x00000005 获取 证书密 码重 试次
19、数 0x00000007 设备 类型 返回“HARD“ 或“SOFT“ 0x00000008 对应 动态库 的名 称 0x00000009 CSP 名称 0x00000073 设备 类型 SM2设 备返 回“20“ 0x00000074 设备 的VID_PID （16 进制 数据 ） 5.3 访问控 制接 口 5.3.1 设备登 录 设备登 录接 口定 义如 下： 接口原 型: boolean SOF_Login(BSTR CertID, BSTR PassWd) 功能描 述: 登录 参数: CertIDIN 证 书操 作唯 一标 识， 也支持 只输 入设 备序 列号 。 PassWdIN 证
20、书 口令 。 返回值 ： 正 确返 回TRUE ，失 败返 回FALSE 备注： 无 5.3.2 设备登 出 设备登 出接 口定 义如 下： 接口原 型： boolean SOF_Logout (BSTR CertID) 功能描 述： 退出 登录 参数： CertIDIN 证 书操 作唯 一标 识 返回值 ： 正确 返回TRUE 失 败返 回FALSE 备注： 无 5.3.3 获取口 令重 试次 数 获取口 令重 试次 数接 口定 义如下 ： 接口原 型： LONG SOF_GetPinRetryCount(BSTR CertID) 功能描 述： 获取 证书 口 令重试 次数 参数： Cert
21、IDIN 证 书操 作唯 一标 识 返回值 ： 0 表 示重 试 次数， =0 表示 证书 口令 已 被锁死 ，必 须解 锁后 才能 使用 0 表 示获 取重 试次 数 失 败 备注： 无 5.3.4 修改登 录口 令 修改登 录口 令接 口定 义如 下： DB11/T 254.2 2018 5 接口原 型: boolean SOF_ChangePassWd(BSTR CertID, BSTR OldPassWd ，BSTR NewPassWd) 功能描 述: 修 改证 书口 令 参数: CertIDIN 证书操 作唯 一标 识 OldPassWdIN 原 始口 令，6-16 位可 显 示字符
22、 NewPassWdIN 新 口令 ，6-16 位 可显 示 字符 返回值 ： 成 功返 回TRUE ，失 败返 回FALSE 备注： 无 5.4 容器 管理 接口 5.4.1 获取容 器数 量 获取容 器数 量接 口定 义如 下： 接口原 型： LONG GetContainerCount(BSTR sDeviceSN) 功能描 述： 获 取容 器数 量 参数： sDeviceSNIN 设备 序列 号 返回值 ： 成 功返 回容 器数量 ，失 败返 回负 数 备注： 无 5.4.2 获取所 有容 器名 称 获取所 有容 器名 称接 口定 义如下 ： 接口原 型: BSTR SOF_GetAl
23、lContainerName (BSTR sDeviceSN) 功能描 述: 获 取所 有容 器名称 参数: sDeviceSNIN 设备 序列 号 返回值 ： 成功返 回所有 容器名 称， 失败或 设备内 不存在 容器 时返回 空。返 回格式 为使 用“& ” 符号分 隔的 容器 名， 即&. 备注： 无 5.4.3 删除容 器 删除容 器接 口定 义如 下： 接口原 型： boolean DeleteContainer(BSTR sDeviceSN, BSTR sContainerName) 功能描 述： 删 除容 器 参数： sDeviceSNIN 设备 序列 号 sContainerN
24、ameIN 容器名 称 返回值 ： 成 功返 回TRUE ，失 败返 回FALSE 备注： 调 用本 接口 前必须 已登 录 5.5 密码服 务接 口 5.5.1 产生密 钥对 产生密 钥对 接口 定义 如下 ： 接口原 型: boolean GenerateKeyPair(BSTR sDeviceSN, BSTR sContainerName, LONG iKeyType, boolean bSign) 功能描 述: 产 生密 钥对 参数: sDeviceSNIN 设备 序列 号 DB11/T 254.2 2018 6 sContainerNameIN 容器名称 ，应为 可 见字 符 ，不能
25、包 含/ 字符， 长 度在1-32 之间 iKeyTypeIN 密钥类 型，3表示256 位SM2 密钥 bSignIN 签 名或 加密 ，TRUE表 示签 名，FALSE表 示 加密 返回值 ： 成 功返 回TRUE ，失 败返 回FALSE 备注： 无 5.5.2 导出公 钥 导出公 钥接 口定 义如 下： 接口原 型: BSTR ExportPubKey(BSTR sDeviceSN, BSTR sContainerName, boolean bSign) 功能描 述: 导 出公 钥 参数: sDeviceSNIN 设备 序列 号 sContainerNameIN 容器名 称 bSign
26、IN 签 名或 加密,TRUE 表 示签 名公 钥,FALSE 表 示加密 公钥 返回值: 成 功返 回Base64 编 码的 公钥 ，失 败返 回 空 备注： 无 5.5.3 导出证 书请 求 导出证 书请 求接 口定 义如 下： 接口原 型： BSTR ExportCertificationReq(BSTR sDeviceSN, BSTR sContainerName, BSTR sDN) 功能描 述： 导 出证 书请 求 参数： sDeviceSN 设备 序列 号 sContainerNameIN 容器名 称 sDNIN DN 信息 ，如 果DN 项中 有逗 号(,) ，前 边加 上 进
27、 行转 义 返回值 ： 成 功返 回Base64 编 码的 证书 请求 ，失 败 返回空 备注： 无 5.5.4 导入签 名证 书 导入签 名证 书接 口定 义如 下： 接口原 型: boolean ImportSignCert(BSTR sDeviceSN, BSTR sContainerName, BSTR sCert) 功能描 述: 导 入签 名证 书 参数: sDeviceSNIN 设备 序列 号 sContainerNameIN 容器名 称 sCertIN Base64 编码 的 签名证 书 返回值: 成 功返 回TRUE ，失 败返 回FALSE 备注： 无 5.5.5 导入加 密
28、证 书和 加密 密钥 对 导入加 密证 书和 加密 密钥 对接口 定义 如下 ： 接口原 型: boolean ImportEncCert(BSTR sDeviceSN,BSTR sContainerName, BSTR sCert, BSTR sPriKeyCipher) 功能描 述: 导 入加 密证 书和加 密密 钥对 参数: sDeviceSNIN 设备 序列 号 sContainerNameIN 容器名 称 DB11/T 254.2 2018 7 sCertIN Base64 编码 的 加密证 书 sPriKeyCipherIN Base64 编码 的加 密密 钥 密文 返回值: 成
29、功返 回TRUE ，失 败返 回FALSE 备注： 无 5.5.6 数据签 名 数据签 名接 口定 义如 下： 接口原 型: BSTR SOF_SignData(BSTR CertID, BSTR InData) 功能描 述: 对 数据 进行 数字签 名。 参数: CertIDIN 证书 操作 唯一 标 识 InDataIN 签名原 文 返回值: 成 功返 回Base64 编 码的 签名 值， 失败 返 回空 备注: 签 名结 果应 符合GM/T 0009 2012中7.3的要 求 5.5.7 数据验 签 数据验 签接 口定 义如 下： 接口原 型: boolean SOF_VerifySig
30、nedData(BSTR Cert, BSTR InData ， BSTR SignValue) 功能描 述: 验 证数 据签 名。 参数: CertIN Base64编 码的 证书 InDataIN 签名 原文 SignValueIN Base64 编码 的签 名值 返回值: 成 功返 回TRUE ，失 败返 回FALSE 备注： 无 5.5.8 数字信 封加 密数 据 数字信 封加 密数 据接 口定 义如下 ： 接口原 型: BSTR SOF_EncryptData(BSTR Cert, BSTR Indata) 功能描 述: 产 生数 字信 封 参数: CertIN Base64 编码
31、的证书 。 IndataIN 原始 数据 返回值: 成 功返 回Base64 编 码的 密文 数据 ，失 败 返回空 备注: 使用临 时产生 的对称 密钥 加密数 据, 然后 使用 数字证 书加密 对称密 钥( 数 字信封)。格 式应符 合GM/T 0010 2012 中第9 章的 要求 5.5.9 数字信 封解 密数 据 数字信 封解 密数 据接 口定 义如下 ： 接口原 型: BSTR SOF_DecryptData(BSTR CertID, BSTR Indata) 功能描 述: 解 数字 信封 密 参数: CertIDIN 证书 操作 唯一 标识 IndataIN Base64 编码
32、的 密文数 据 返回值: 成 功返 回明 文数据 ，失 败返 回空 备注： 无 5.5.10 消息签 名 DB11/T 254.2 2018 8 消息签 名接 口定 义如 下： 接口原 型： BSTR SOF_SignMessage(short dwFlag ，BSTR CertID, BSTR InData) 功能描 述： 对 数据 进行 数字签 名。 参数： dwFlagIN 标识是 否Detached 。0 表 示 带原文 ，1 表示 不带 原文 。 CertIDIN 证 书操 作唯 一 标识 InDataIN 待 签名 的原 始数据 返回值 ： 成 功返 回Base64 编 码的 签名
33、 值， 失败 返 回空 备注： 对 字符 串数 据进行 数字 签名 ，格 式应 符合GM/T0012 2012 中第8章的 要求 5.5.11 验证消 息签 名 验证消 息签 名接 口定 义如 下： 接口原 型: boolean SOF_VerifySignedMessage(BSTR MessageData，BSTR InData) 功能描述: 对 数据 进行 验证签 名。 参数: MessageDataIN Base64 编码 的签 名值。 InDataIN 原始 数据 返回值: 成 功返 回TRUE ，失 败返 回FALSE 备注： 无 5.5.12 解析消 息签 名 解析消 息签 名接
34、 口定 义如 下： 接口原 型： BSTR SOF_GetInfoFromSignedMessage(BSTR SignedMessage ，short type) 功能描 述： 解析消 息签 名包 内的 信息 ，包括 ：原 文、 签名 值、 签名证 书等 信息 。 参数： SignedMessageIN Base64编 码的 签名 值。 typeIN 类 型， 取 值范围 如下 ： 1：原 文 2 ：签 名者 证书 3：签 名值 返回值 ： 成 功返 回解 析的信 息， 失败 返回 空 备注： 无 5.5.13 产生随 机数 产生随 机数 接口 定义 如下 ： 接口原 型: BSTR SOF
35、_GenRandom(LONG RandomLen) 功能描 述: 产 生随 机数 。 参数: RandomLenIN 随机 数的 长度 。 返回值: 成 功返 回Base64 编码 的随 机数 ，失 败返 回空 备注： 无 5.5.14 公钥加 密数 据 公钥加 密数 据接 口定 义如 下： 接口原 型： BSTR SOF_PubKeyEncrypt(BSTR sCert, BSTR sInData) 功能描 述： 公 钥加 密数 据 参数： sCertIN Base64编 码证 书 DB11/T 254.2 2018 9 sInDataIN 原 文数 据 返回值 ： 正 确返 回Base6
36、4 编 码的 密文 数据 ，失 败 返回空 备注： 无 5.5.15 私钥解 密数 据 私钥解 密数 据接 口定 义如 下： 接口原 型: BSTR SOF_PriKeyDecrypt(BSTR CertID, BSTR sInData) 功能描 述: 私 钥解 密数 据 参数: CertIDIN 证 书操 作唯 一标识 sInDataIN Base64 编码 的 密文数 据 返回值: 正 确返 回明 文数据 ，失 败返 回空 备注： 无 5.5.16 对称加 密数 据 对称加 密数 据接 口定 义如 下： 接口原 型： BSTR SOF_SymEncryptData(BSTR sKey, B
37、STR indata) 功能描 述： 对 称加 密数 据 参数： sKeyIN Base64编 码的对 称密 钥 indataIN 原 文数 据 返回值 ： 正 确返 回Base64 编 码的 密文 数据 ，失 败 返回空 备注： 无 5.5.17 对称解 密数 据 对称解 密数 据接 口定 义如 下： 接口原 型： BSTR SOF_SymDecryptData(BSTR sKey, BSTR indata) 功能描 述： 对 称解 密数 据 参数： sKeyIN Base64编 码的对 称密 钥 indataIN Base64 编码 的密文 返回值 ： 正 确返 回明 文数据 ，失 败返
38、回空 备注： 无 5.5.18 数据摘 要 数据摘 要接 口定 义如 下： 接口原 型： BSTR SOF_HashData(LONG hashAlg, BSTR sInData) 功能描 述： 对 数据 做摘 要 参数： hashAlgIN 摘 要算 法， 应 使用0x00000001,表示SM3 算法 sIndataIN 原始数 据 返回值 ： 正 确返 回Base64 编 码的 数据 ，失 败返 回 空 备注： 无 5.6 证书接 口 5.6.1 获取证 书用 户列 表 获取证 书用 户列 表接 口定 义如下 ： DB11/T 254.2 2018 10 接口原 型： BSTR SOF_
39、GetUserList() 功能描 述： 获 取已 安装 的证书 用户 列表 。 参数： 无 返回值 ： 证 书用 户列 表 备注： 返 回 的 证 书 用 户 列 表 格 式 为 ： 用 户 名1|CertID1& 用户名2|CertID2& 用 户 名 3|CertID3&. 。CertID 是证 书操 作唯 一标 识， 格 式为 容器 名称/ 设备 序列 号。 通 过CertID 可 以找 到唯 一的 签名证 书、 加密 证书 ，并 使用对 应密 钥。 5.6.2 导出用 户签 名证 书 导出用 户签 名证 书接 口定 义如下 ： 接口原 型： BSTR SOF_ExportUserCe
40、rt(BSTR CertID) 功能描 述： 根据 证书 操作 唯一 标识 获取Base64 编码 格式 的签 名证书 。 参数： CertIDIN 证 书操 作唯 一 标识 返回值 ： 成 功返 回Base64 编 码的 签名 证书 ，失 败 返回空 备注： 无 5.6.3 导出用 户加 密证 书 导出用 户加 密证 书接 口定 义如下 ： 接口原 型： BSTR SOF_ExportExchangeUserCert(BSTR CertID) 功能描 述： 根 据证 书操 作唯一 标识 获取Base64编 码格式 的证 书。 参数： CertIDIN 证 书操 作唯 一 标识 返回值 ： 成
41、 功返 回Base64 编 码的 加密 证书 ，失 败 返回空 备注： 无 5.6.4 验证证 书有 效性 验证证 书有 效性 接口 定义 如下： 接口原 型： LONG SOF_ValidateCert(BSTR Base64EncodeCert) 功能描 述： 验 证证 书有 效性 参数： Base64EncodeCertIN Base64编 码证 书 返回值 ： 正 确返 回0 失败返 回其 他值 如下 ： -1 证 书不 被 信任 -2 超 过有 效 期范围 -3 证 书已 作 废 -4 证 书已 冻 结 -5 证 书未 生 效 -6 其 他错 误 备注： 无 5.6.5 获取证 书基
42、 本信 息 获取证 书基 本信 息接 口定 义如下 ： 接口原 型: BSTR SOF_GetCertInfo(BSTR Cert, short Type) 功能描 述: 获 取证 书基 本 信息 参数: CertIN Base64 编码 的 证书。 TypeIN 信 息类 型 DB11/T 254.2 2018 11 返回值: 成 功返 回证 书 的基本 信息 ，失 败返 回空 备注: 目 前可 支持 的 证书信 息类 型参 数如 下： 1 证 书版 本号 返回“V1“ 或“V2“ 或 “V3“ 2 证 书序 列号 3 证 书类 型 返回“RSA“ 或“SM2“ 4 颁 发者 国家 名(C)
43、 多 个 用逗号(,) 分割 5 颁 发者 组织 名(O) 多 个 用逗号(,) 分割 6 颁 发者 部门 名(OU) 多 个用逗 号(,)分割 7 颁 发者 省州 名(ST) 多 个用逗 号(,)分割 8 颁 发者 通用 名(CN) 多 个用逗 号(,)分割 9 颁 发者 城市 名(L) 多 个 用逗号(,) 分割 10 颁 发者EMAIL(E) 多个 用逗号(,) 分割 11 证 书有 效开 始日 期 格式YYYYMMDDHHMMSS 12 证 书有 效结 束日 期 格式YYYYMMDDHHMMSS 13 使 用者 国家 名(C) 多 个 用逗号(,) 分割 14 使 用者 组织 名(O)
44、 多 个 用逗号(,) 分割 15 使 用者 部门 名(OU) 多 个用逗 号(,)分割 16 使 用者 省州 名(ST) 多 个用逗 号(,)分割 17 使 用者 通用 名(CN) 多 个用逗 号(,)分割 18 使 用者 城市 名(L) 多 个 用逗号(,) 分割 19 使 用者EMAIL(E) 多个 用逗号(,) 分割 20 证 书公 钥 Base64 编码 格式 21 颁 发者UID 22 使 用者UID 23 密 钥用 法 证 书中 如果 没有密 钥用 法扩 展项 返回”0 ” ， 密钥 用法 为加 密返 回”1”， 密钥用 法为 签名 返回 ”2 ” ，密钥 用法 既有 加密 也有
45、 签名返 回”3 33 使 用者DN 34 颁 发者DN 5.6.6 获 取证 书扩 展信 息 获取证 书扩 展信 息接 口定 义如下 ： 接口原 型: BSTR SOF_GetCertInfoByOid(BSTR Cert, BSTR Oid) 功能描 述: 根据OID 获取 证书的 私有 扩展 信息 参数: CertIN Base64 编码 的 证书 OidIN OID串 返回值: 成 功返 回对 应 的扩展 信息 ，失 败返 回空 备注： 无 5.6.7 获 取证 书唯 一实 体 标识 获取证 书唯 一实 体标 识接 口定义 如下 ： 接口原 型： BSTR SOF_GetCertEnt
46、ity(BSTR Cert) 功能描 述： 获 取证 书的 唯一实 体标 识 参数： CertIN Base64 编码 的证书 DB11/T 254.2 2018 12 返回值 ： 成 功返 回证 书唯一 实体 标识 ，失 败返 回空 备注： 无 5.7 通用接 口 5.7.1 获取最 后一 次出 错的 错误 码 获取最 后一 次出 错的 错误 码接口 定义 如下 ： 接口原 型： LONG SOF_GetLastError() 功能描 述： 获 取最 后一 次出错 的错 误码 参数： 无 返回值 ： 错 误码 。其 中0表 示正 常， 其它 表示 错 误。错 误码 定义 和说 明见 附录A
47、备注： 无 5.7.2 获取最 后一 次出 错的 错误 描述 获取最 后一 次出 错的 错误 描述接 口定 义如 下： 接口原 型： BSTR SOF_GetLastErrMsg() 功能描 述： 获 取最 后一 次出错 的错 误描 述 参数： 无 返回值 ： 错 误描 述信 息 备注： 无 DB11/T 254.2 2018 13 附 录 A （规范 性附 录） 政务数 字证 书应 用接 口错 误代码 定义 和说 明 A.1 有标 题 政 务数 字证 书 应用接 口错 误代 码定 义和 说明 政务数 字证 书应 用接 口错 误代码 定义 和说 明见 表A.1 。 表 A.1 政 务数 字证
48、书应 用接口 错误 代码 定义 和说 明 错误码( 十进制） 描述 1 设备序列错误（索引值错误） 2 设备序列号长度错误 3 打开设备错误 4 打开应用错误 5 没有打开设备 6 Pin 码长度错误 7 校验口令失败 8 获取Pin 码重试次数错误 9 修改管理员口令失败 10 修改用户口令失败 11 解锁用户口令失败 12 容器名称长度错误 13 创建容器失败 14 产生密钥对失败 15 打开容器失败 16 导出公钥失败 17 尚未登录 18 导入证书失败 19 容器类型错误 20 ENVSN 为空 21 写入ENVSN 失败 22 读取ENVSN 失败 23 获取容器数量失败 24 删除容器失败 25 判断容器是否存在失败 26 获取设备序列号失败 27 导入证书时，证书中的公钥和设备容器中的公钥不匹配 28 Base64 编码失败 29 Base64 解码失败 30 解析字符串失败
