GB/T 43694-2024 网络安全技术 证书应用综合服务接口规范

　　ICS 35. 030 CCS L 80

　　中 华 人 民 共 和 国 国 家 标 准

　　GB/T 43694—2024

　　网络安全技术 证书应用综合服务接口规范

　　Cybersecuritytechnology—Certificateapplication

　　integrated serviceinterfacespecification

　　2024-04-25发布 2024-11-01实施

　　国家市场监督管理总局国家标准化管理委员会

　　

　　发

　　

　　布

　　GB/T 43694—2024

　　目 次

　　前言 Ⅰ

　　1 范围 1

　　2 规范性引用文件 1

　　3 术语和定义 1

　　4 缩略语 2

　　5 证书应用综合服务接 口 2

　　5. 1 证书应用综合服务接口在公钥密码应用技术体系框架中的位置 2

　　5. 2 证书应用综合服务接口分类 2

　　5. 3 客户端服务接 口 2

　　5. 4 服务器端服务接 口 2

　　6 标识和数据结构 3

　　6. 1 标识定义 3

　　6. 2 数据结构定义 3

　　6. 3 数据格式要求 3

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

　　7. 1 客户端 COM组件接 口 3

　　7. 2 客户端 JavaScript脚本接 口 16

　　7. 3 服务器端 COM组件接 口 28

　　7. 4 服务器端 Java组件接 口 42

　　8 接口验证方法 56

　　8. 1 验证环境 56

　　8. 2 验证原则 56

　　8. 3 验证场景 57

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

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

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

　　附录 D (资料性) 证书应用综合服务接口汇总 67

　　附录 E (资料性) 客户端 JavaScript脚本接口异步调用示例说明 73

　　参考文献 74

　　GB/T 43694—2024

　　前 言

　　本文件按照 GB/T 1. 1—2020《标准化工作导则 第 1部分 :标准化文件的结构和起草规则》的规定起草 。

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

　　本文件由全国网络安全标准化技术委员会(SAC/TC260)提出并归 口 。

　　本文件起草单位 :北京数字认证股份有限公司 、博雅中科(北京) 信息技术有限公司 、北京奇虎科技有限公司 、山东得安信息技术有限公司 、中国电力科学研究院 、北京信安世纪科技股份有限公司 、无锡江南信息安全工程技术中心 、中国电子技术标准化研究院 、格尔软件股份有限公司 、中电科网络安全科技股份有限公司 、深圳市不动产登记中心 、郑州信大捷安信息技术股份有限公司 、阿里云计算有限公司 、浙江九州量子信息技术股份有限公司 、航天信息股份有限公司 、数安时代科技股份有限公司 、智巡密码(上海)检测技术有限公司 、中科信息安全共性技术国家工程研究中心有限公司 、中国汽车工程研究院股份有限公司 。

　　本文件主要起草人 :刘伟 、赵 永 省 、夏 鲁 宁 、李 述 胜 、刘 中 、程 科 伟 、浦 雨 三 、张 屹 、张 志 磊 、马 洪 富 、袁中林 、李智 虎 、焦 靖 伟 、刘 平 、黄 晶 晶 、谭 武 征 、寇 建 波 、颜 海 龙 、刘 献 伦 、刘 为 华 、肖 淑 婷 、张 文 科 、杨倩媚 、董亮亮 、周蔚林 、韩玮 、高振鹏 、胡建勋 、刘冲 、牟洁 。

　　Ⅰ

　　GB/T 43694—2024

　　网络安全技术 证书应用综合服务接口规范

　　1 范围

　　本文件规定了面向证书应用的综合服务接口要求和定义 ,描述了相应验证方法 。

　　本文件适用于公钥密码基础设施应用技术体系下证书应用中间件和证书应用系统的开发 , 以及密码应用支撑平台的研制和检测 。

　　2 规范性引用文件

　　下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款 。其中 , 注 日期的引用文件 ,仅该日期对应的版本适用于本文件 ;不注日期的引用文件 ,其最新版本(包括所有的修改单) 适用于本文件 。

　　GB/T 20518

　　信息安全技术

　　公钥基础设施 数字证书格式

　　GB/T 25061

　　信息安全技术

　　XML数字签名语法与处理规范

　　GB/T 25069

　　信息安全技术

　　术语

　　GB/T 33560

　　信息安全技术

　　密码应用标识规范

　　GB/T 35275

　　信息安全技术

　　SM2密码算法加密签名消息语法规范

　　GB/T 35276

　　信息安全技术

　　SM2密码算法使用规范

　　GB/T 35291

　　信息安全技术

　　智能密码钥匙应用接口规范

　　GB/T 36322

　　信息安全技术

　　密码设备应用接口规范

　　GB/T 43578

　　信息安全技术

　　通用密码服务接口规范

　　GM/T 0094—2020 公钥密码应用技术体系框架规范

　　GM/Z 4001 密码术语

　　3 术语和定义

　　GB/T 25069、GM/Z 4001界定的以及下列术语和定义适用于本文件 。

　　3. 1

　　数字证书 digitalcertificate

　　由 CA签名的包含公开密钥拥有者信息 、公开密钥 、签发者信息 、有效期以及扩展信息的一种数据结构 。

　　注 : 数字证书也称公钥证书 ,按类别分为个人证书 、机构证书和设备证书 ,按用途分为签名证书和加密证书 。

　　[来源 :GM/Z 4001—2013,2. 115] 3.2

　　用户密钥 userkey

　　存储在设备内部的用于应用密码运算的非对称密钥对 。

　　注 : 用户密钥包含签名密钥对和加密密钥对 。

　　3.3

　　密钥容器 key container

　　密码设备中用于保存用户密钥的唯一性存储空间 。

　　1

　　GB/T 43694—2024

　　4 缩略语

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

　　B/S:浏览器/服务器(Browser/Server)

　　CA:证书认证机构(Certification Authority)

　　COM :组件对象模型(ComponentObjectModel)

　　CRL:证书撤销列表(Certificate Revocation List)

　　JAR:Java归档文件(Java Archive)

　　LDAP:轻量级目录访问协议(LightweightDirectory Access Protocol)

　　OID:对象标识符(ObjectIdentifier)

　　XML:可扩展标记语言(Extensible Markup Language)

　　5 证书应用综合服务接口

　　5. 1 证书应用综合服务接口在公钥密码应用技术体系框架中的位置

　　公钥密码应用技术体系框架由应用层 、典型密码应用支撑层 、通用密码应用支撑层 、基础设施安全支撑平台 、密码设备服务层组成 。证书应用综合服务接口属于通用密码应用支撑层 ,是中间件 , 为典型密码应用支撑层和应用层提供密码服务 。其功能主要包括 :负责完成与密码设备的安全连接 ;实现基于数字证书的身份认证 ,从证书中获取有关信息 ,实现授权管理 、访问控制等安全机制 ;负责具体与密码设备交互实现具体的密码运算 ;将数据按照 GB/T 35275要求的格式进行封装 ,实现数据封装格式与应用系统无关性 ,实现应用系统互联互通和信息共享 。证书应用综合服务接口规范在公钥密码应用技术框架内的位置应遵循 GM/T 0094—2020的第 4章 。

　　5.2 证书应用综合服务接口分类

　　证书应用综合服务接口包括客户端服务接口和服务器端服务接口两类 。它位于典型密码应用支撑层和密码设备服务层之间 ,既可被典型密码应用支撑层调用也可被应用层直接调用 , 向上层提供证书信息解析 、基于数字证书身份认证 、信息的机密性 、完整性和不可否认性等密码服务 。

　　5.3 客户端服务接口

　　客户端服务接口采用支持多种编程语言的 COM组件和客户端常使用的 JavaScript脚本语言为例描述 ,其适用于客户端程序调用 ,接口的形态包括动态库 、控件 、插件 、扩展等 。

　　客户端服务接口一般通过调用智能密码钥匙应用接口或通用密码服务接口来实现 ,此类接口应符合 GB/T 35291或 GB/T 43578中的规定 ,主要功能包括 :配置管理 、证书解析 、签名与验证 、加密与解密数字信封 、XML数据签名与验证等 。

　　5.4 服务器端服务接口

　　服务器端服务接口采用支持多种编程语言的 COM组件和服务端常使用的 Java语言为例描述 ,其适用于服务器端程序调用 ,接口的形态包括 COM组件 、JAR包等 ,支持主流操作系统 。

　　服务器端服务接口一般通过调用密码设备应用接口或通用密码服务接口来实现 ,此类接口应符合GB/T 36322或 GB/T 43578中的规定 ,功能基本与客户端服务接口相对应 , 主要包括 :配置管理 、证书解析 、签名与验证 、加密与解密数字信封 、XML数据签名与验证 、时间戳等 。

　　2

　　GB/T 43694—2024

　　6 标识和数据结构

　　6. 1 标识定义

　　本文件所使用的常量 、各类算法标识和证书解析标识应符合 GB/T 33560的规定 。

　　6.2 数据结构定义

　　本文件规定的接口处理的数据分为两种类型 :

　　数据类型 A:是一种基于公钥的加密或签名结构 , 当公钥算法为 RSA 时 ,数据的结构参见 PKCS# 1 v1. 5;当公钥算法为 SM2时 ,数据的结构应符合 GB/T 35276的规定 。

　　数据类型 B:是一种基于证书的加密或签名结构 , 当证书的公钥算法为 RSA 时 , 消 息 的 结 构 参 见PKCS#7;当证书的公钥算法为 SM2时 ,消息的结构应符合 GB/T 35275的规定 。

　　6.3 数据格式要求

　　本文件所涉及的数字证书格式应符合 GB/T 20518的规定 。

　　本文件所描述的 Base64编码格式参见 RFC4648中 Base64Encoding部分 。

　　在没有特殊说明的情况下 ,本文件中字符串采用 UTF-8编码 ,其格式参见 RFC3629。

　　本文件所定义接口返回的错误码或抛出的异常信息应符合附录 A,典型部署模型可参见附录 B,集成示例可参见附录 C。

　　本文件以 COM组件为例进行接口描述时 ,所用到的数据类型说明见表 1。

　　表 1 COM 组件数据类型说明

　　类型

　　说明

　　BSTR

　　字符串类型 ,不同的开发语言应采取对应的类型定义 ,如 :char* 、CString、java.lang. String等

　　LONG

　　32位整数

　　SHORT

　　16位整数

　　BOOL

　　布尔类型 ,其取值范围是 TRUE和 FALSE,其中 TRUE表示真值 ,FALSE表示假值

　　空串

　　长度等于 0 的字符串

　　非空

　　长度大于 0 的字符串

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

　　7. 1 客户端 COM 组件接口

　　7. 1. 1 客户端 COM 组件接口综述

　　客户端 COM组件接口提供配置管理 、证书解析 、签名与验证 、加密与解密数字信封 、XML数据签名与验证等功能 ,共包含 35个接 口 。 客户端 COM 组件接口列表见附录 D 的表 D. 1, 7. 1. 2~ 7. 1. 36给出了接口详细定义 。

　　7. 1.2 获取接口版本信息

　　获取接口版本信息接口定义应符合表 2 的规定 。

　　3

　　GB/T 43694—2024

　　表 2 获取接口版本信息接口定义

　　原型

　　BSTR SOF_GetVersion()

　　描述

　　获取接口的版本号

　　参数

　　无

　　返回值

　　接口版本号(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7. 1.3 设置签名算法

　　设置签名算法接口定义应符合表 3 的规定 。

　　表 3 设置签名算法接口定义

　　原型

　　LONG SOF_SetSignMethod(LONG SignMethod)

　　描述

　　设置接口在签名和验签运算时使用的签名算法

　　参数

　　SignMethod(签名算法标识 ,应符合 GB/T 33560的规定)

　　返回值

　　SOR_OK(成功)

　　其他(失败 ,返回符合表 A. 1定义的错误代码)

　　7. 1.4 获得签名算法

　　获得签名算法接口定义应符合表 4 的规定 。

　　表 4 获得签名算法接口定义

　　原型

　　LONG SOF_GetSignMethod()

　　描述

　　获得接口当前使用的签名算法

　　参数

　　无

　　返回值

　　当前使用的签名算法标识(成功)

　　0(当前没有设置签名算法)

　　7. 1.5 设置加密算法

　　设置加密算法接口定义应符合表 5 的规定 。

　　表 5 设置加密算法接口定义

　　原型

　　LONG SOF_SetEncryptMethod(LONG EncryptMethod)

　　描述

　　设置接口进行数据加密时使用的对称算法

　　参数

　　EncryptMethod(对称加密算法标识 ,应符合 GB/T 33560的规定 ,本接口可支持不带附加认证数据的加

　　解密算法)

　　返回值

　　SOR_OK(成功)

　　其他(失败 ,返回表 A. 1定义的错误代码)

　　4

　　GB/T 43694—2024

　　7. 1.6 获得加密算法

　　获得加密算法接口定义应符合表 6 的规定 。

　　表 6 获得加密算法接口定义

　　原型

　　LONG SOF_GetEncryptMethod()

　　描述

　　获得接口当前使用的对称加解密算法

　　参数

　　无

　　返回值

　　当前使用的加密算法标识(成功)

　　0(当前没有设置加密算法)

　　7. 1.7 获得证书列表

　　获得证书列表接口定义应符合表 7 的规定 。

　　表 7 获得证书列表接口定义

　　原型

　　BSTR SOF_GetUserList()

　　描述

　　取得当前已安装证书的用户列表

　　参数

　　无

　　返回值

　　证书列表[成功 ,返回证书列表字符串数据 ,格式为 :用户名 1||CertID1&&& 用户名 2||CertID2&&&… ,根据证书应用的 策 略 不 同 得 到 不 同 的 证 书 列 表 返 回 值 。 在 证 书 列 表 中 , 用 户 名 代 表 证 书 的 通 用 名(Common Name) ,CertID是证书唯一标识 ,其 格 式 由 实 现 者 自 定 义 , 宜 包 含 容 器 名 、应 用 名 、设 备 序 列号等项 。通过 CertID应找到唯一的签名证书 、加密证书 ,并使用对应的用户密钥]

　　空串(失败或当前不存在证书用户列表 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7. 1. 8 导出用户签名证书

　　导出用户签名证书接口定义应符合表 8 的规定 。

　　表 8 导出用户签名证书接口定义

　　原型

　　BSTR SOF_ExportUserCert(BSTR CertID)

　　描述

　　根据证书唯一标识 ,获取 Base64编码的签名证书字符串

　　参数

　　CertID(证书唯一标识)

　　返回值

　　Base64编码的签名证书字符串(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7. 1.9 证书登录

　　证书登录接口定义应符合表 9 的规定 。

　　5

　　GB/T 43694—2024

　　表 9 证书登录接口定义

　　原型

　　BOOL SOF_Login(BSTR CertID,BSTR PassWd)

　　描述

　　校验证书口令 ,进行证书认证

　　参数

　　CertID(证书唯一标识)

　　PassWd(证书口令)

　　返回值

　　TRUE (成功)

　　FALSE(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　安全规则

　　证书登录成功后 ,表示该证书用户 已 拥 有 私 钥 使 用 权 限 , 即 登 录 状 态 。登 录 状 态 下 , 可 正 常 调 用 签 名 、解密等需要私钥使用权限的接 口 ,获得计算结果

　　7. 1. 10 获取证书口令剩余重试次数

　　获取证书口令剩余重试次数接口定义应符合表 10的规定 。

　　表 10 获取证书口令剩余重试次数接口定义

　　原型

　　LONG SOF_GetPinRetryCount(BSTR CertID)

　　描述

　　获取证书口令的剩余重试次数

　　参数

　　CertID(证书唯一标识)

　　返回值

　　剩余口令重试次数 , 当重试次数小于或等于 0 时表示证书口令已被锁定

　　7. 1. 11 修改证书口令

　　修改证书口令接口定义应符合表 11的规定 。

　　表 11 修改证书口令接口定义

　　原型

　　BOOL SOF_ChangePassWd(BSTR CertID,BSTR OldPassWd,BSTR NewPassWd)

　　描述

　　修改设备的用户认证口令

　　参数

　　CertID(证书唯一标识)

　　OldPassWd(旧证书口令)

　　NewPassWd(新证书口令)

　　返回值

　　TRUE(成功)

　　FALSE(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7. 1. 12 导出用户加密证书

　　导出用户加密证书接口定义应符合表 12的规定 。

　　6

　　GB/T 43694—2024

　　表 12 导出用户加密证书接口定义

　　原型

　　BSTR SOF_ExportExChangeUserCert(BSTR CertID)

　　描述

　　根据证书唯一标识 ,获取 Base64编码的加密(交换)证书字符串

　　参数

　　CertID(证书唯一标识)

　　返回值

　　Base64编码的加密证书字符串(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7. 1. 13 获得证书信息

　　获得证书信息接口定义应符合表 13的规定 。

　　表 13 获得证书信息接口定义

　　原型

　　BSTR SOF_GetCertInfo(BSTR Base64Cert,SHORT Type)

　　描述

　　获取证书内指定类型的信息

　　参数

　　Base64Cert(Base64编码的证书字符串)

　　Type(证书解析标识 ,应符合 GB/T 33560的规定)

　　返回值

　　指定类型的证书信息(成功)

　　空串(失败或证书中不存在该项内容)

　　7. 1. 14 获得证书扩展信息

　　获得证书扩展信息接口定义应符合表 14的规定 。

　　表 14 获得证书扩展信息接口定义

　　原型

　　BSTR SOF_GetCertInfoByOid(BSTR Base64Cert,BSTR Oid)

　　描述

　　根据 OID获取证书私有扩展项信息

　　参数

　　Base64Cert(Base64编码的证书字符串)

　　Oid(私有扩展对象 ID,如“1. 2. 156. xxx”)

　　返回值

　　证书私有扩展项 OID对应的信息(成功)

　　空串(失败或证书中不存在该私有扩展项)

　　7. 1. 15 获得设备信息

　　获得设备信息接口定义应符合表 15的规定 。

　　7

　　GB/T 43694—2024

　　表 15 获得设备信息接口定义

　　原型

　　BSTR SOF_GetDeviceInfo(BSTR CertID,LONG Type)

　　描述

　　根据证书唯一标识和类型代码获得设备信息

　　参数

　　CertID(证书唯一标识)

　　Type(设备信息的类型 ,应符合 GB/T 33560的规定)

　　返回值

　　对应的设备信息(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7. 1. 16 验证证书有效性

　　验证证书有效性接口定义应符合表 16的规定 。

　　表 16 验证证书有效性接口定义

　　原型

　　LONG SOF_ValidateCert(BSTR Base64Cert)

　　描述

　　验证证书有效性

　　参数

　　Base64Cert(Base64编码的证书字符串)

　　返回值

　　SAR_OK(验证成功)

　　其他(验证失败 ,失败原因应符合表 A. 1 中的错误代码范围 0X0B000500~ 0X0B000505)

　　验证策略

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

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

　　b) 各层证书的有效期验证 ;

　　c) 各层证书的吊销状态 。在特殊情况下(如 : 网络条件不允许) ,证书的吊销状态可采取灵活方式 , 由应用系统各层内部维护一个吊销列表 ,在证书登录认证时应用该吊销列表 。验证证书有效性也可采取代理验证方式

　　7. 1. 17 数据签名

　　数据签名接口定义应符合表 17的规定 。

　　表 17 数据签名接口定义

　　原型

　　BSTR SOF_SignData(BSTR CertID,BSTR InData)

　　描述

　　对字符串数据进行数字签名 ,返回 Base64编码的数据类型 A签名结果

　　参数

　　CertID(证书唯一标识)

　　InData(原文)

　　返回值

　　Base64编码的签名值(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　安全规则

　　本接口应在登录状态下才能成功返回签名值 ,否则应返回空串

　　8

　　GB/T 43694—2024

　　7. 1. 18 验证数据签名

　　验证数据签名接口定义应符合表 18的规定 。

　　表 18 验证数据签名接口定义

　　原型

　　BOOL SOF_VerifySignedData(BSTR Base64Cert,BSTR InData,BSTR SignValue)

　　描述

　　验证数据签名 ,签名值格式为 Base64编码的数据类型 A

　　参数

　　Base64Cert(Base64编码的签名者证书字符串)

　　InData(原文)

　　SignValue(Base64编码的签名值)

　　返回值

　　TRUE(成功)

　　FALSE(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7. 1. 19 文件签名

　　文件签名接口定义应符合表 19的规定 。

　　表 19 文件签名接口定义

　　原型

　　BSTR SOF_SignFile(BSTR CertID,BSTR InFile)

　　描述

　　根据文件全路径 ,对指定文件进行数字签名 ,返回 Base64编码的数据类型 A签名结果

　　参数

　　CertID(证书唯一标识)

　　InFile(原文文件全路径)

　　返回值

　　Base64编码的签名值(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　安全规则

　　本接口应在登录状态下才能成功返回签名值 ,否则应返回空串

　　7. 1.20 验证文件签名

　　验证文件签名接口定义应符合表 20的规定 。

　　表 20 验证文件签名接口定义

　　原型

　　BOOL SOF_VerifySignedFile(BSTR Base64Cert,BSTR InFile,BSTR SignValue)

　　描述

　　验证文件的数字签名 ,签名值格式为 Base64编码的数据类型 A

　　参数

　　Base64Cert(Base64编码的签名者证书)

　　InFile(原文文件全路径)

　　SignValue(Base64编码的签名值)

　　返回值

　　TRUE(成功)

　　FALSE(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　9

　　GB/T 43694—2024

　　7. 1.21 数据加密

　　数据加密接口定义应符合表 21的规定 。

　　表 21 数据加密接口定义

　　原型

　　BSTR SOF_EncryptData(BSTR Base64Cert,BSTR InData)

　　描述

　　数字信封加密 ,加密过程为使用临时 产 生 的 对 称 密 钥 加 密 数 据 ,然 后 使 用 数 字 证 书 的 公 钥 加 密 对 称 密钥 ,返回 Base64编码格式的数据类型 B密文数据

　　参数

　　Base64Cert(Base64编码的数据接收者的加密证书 ,若使用多个证书对数据加密 ,证书之间用 &&& 作为分隔符连接)

　　InData(待加密的明文)

　　返回值

　　Base64编码的密文数据(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7. 1.22 数据解密

　　数据解密接口定义应符合表 22的规定 。

　　表 22 数据解密接口定义

　　原型

　　BSTR SOF_DecryptData(BSTR CertID,BSTR InData)

　　描述

　　使用证书对应的私钥解密数字信封 ,密文数据格式为 Base64编码的数据类型 B

　　参数

　　CertID(证书唯一标识)

　　InData(待解密的 Base64编码的密文数据)

　　返回值

　　解密后的明文数据(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　安全规则

　　本接口应在登录状态下才能解密得到明文 ,否则应返回空串

　　7. 1.23 消息签名

　　消息签名接口定义应符合表 23的规定 。

　　表 23 消息签名接口定义

　　原型

　　BSTR SOF_SignMessage(SHORT Flag,BSTR CertID,BSTR InData)

　　描述

　　对字符串数据进行消息签名 ,返回 Base64编码的数据类型 B签名结果

　　参数

　　Flag(是否为 Detached 的标识) ,取值范围 :

　　a) 1:表示 Detached, 即不带原文 ;

　　b) 0:表示 Attached, 即带原文

　　CertID(证书唯一标识)

　　InData(原文)

　　返回值

　　Base64编码的消息签名值(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　安全规则

　　签名结果包含 :原文(可选) 、签名者证书 、签名算法和签名值 。

　　本接口应在登录状态下才能返回签名值 ,否则应返回空串

　　10

　　GB/T 43694—2024

　　7. 1.24 验证消息签名

　　验证消息签名接口定义应符合表 24的规定 。

　　表 24 验证消息签名接口定义

　　原型

　　BOOL SOF_VerifySignedMessage(BSTR SignedMessage,BSTR InData)

　　描述

　　验证消息签名 ,签名值格式为 Base64编码的数据类型 B

　　参数

　　SignedMessage(Base64编码的消息签名值)

　　InData(原文 ,若签名结果中包含原文 ,忽略本参数)

　　返回值

　　TRUE(成功)

　　FALSE(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7. 1.25 解析消息签名

　　解析消息签名接口定义应符合表 25的规定 。

　　表 25 解析消息签名接口定义

　　原型

　　BSTR SOF_GetInfoFromSignedMessage(BSTR SignedMessage,SHORT Type)

　　描述

　　解析消息签名值中的信息 ,包括 :原文 、签名值 、签名证书等 ,消息签名值格式为 Base64编码的数据类型 B

　　参数

　　SignedMessage(Base64编码的消息签名值)

　　Type(获取的信息类型) ,取值范围 :

　　a) 1:解析出原文 ;

　　b) 2:解析出 Base64编码的签名者证书 ;

　　c) 3:解析出 Base64编码的签名值

　　返回值

　　解析结果(成功)

　　空串(失败或不存在该项)

　　7. 1.26 XML数据签名

　　XML数据签名接口定义应符合表 26的规定 。

　　表 26 XML数据签名接口定义

　　原型

　　BSTR SOF_SignDataXML(BSTR CertID,BSTR InData)

　　描述

　　对 XML数据进行数字签名 ,证书为 RSA算法时签名结果参见 RFC3275,证书为 SM2算法时签名结果应符合 GB/T 25061的规定

　　参数

　　CertID(证书唯一标识)

　　InData(XML格式的签名原文)

　　返回值

　　XML签名结果(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　11

　　GB/T 43694—2024

　　表 26 XML数据签名接口定义 (续)

　　安全规则

　　本接口在登录状态下才能返回签名值 ,否则返回空串 。

　　缺省配置和参数如下 :

　　a) 采用封皮签名 ,签名前应对签名原文做格式化 ;

　　b) 格 式 化 方 法 采 用 带 注 释 的 XML格 式 化 1.1,证 书 为 RSA算 法 时 标 识 符 为 http://www. w3. org/ 2006/12/xml-c14n11#WithComment,证书为 SM2算法时标识符为 http://127.0.0.1/2006/12/xml- c14n11#WithComments

　　7. 1.27 验证 XML数据签名

　　验证 XML数据签名接口定义应符合表 27的规定 。

　　表 27 验证 XML数据签名接口定义

　　原型

　　BOOL SOF_VerifySignedDataXML(BSTR XMLSignedData)

　　描述

　　验证 XML签名

　　参数

　　XMLSignedData(XML签名结果)

　　返回值

　　TRUE(成功)

　　FALSE(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7. 1.28 解析 XML数据签名

　　解析 XML数据签名接口定义应符合表 28的规定 。

　　表 28 解析 XML数据签名接口定义

　　原型

　　BSTR SOF_GetXMLSignatureInfo(BSTR XMLSignedData,SHORT Type)

　　描述

　　解析 XML数据签名 ,获取签名值 、XML原文 、证书和相关算法等信息

　　参数

　　XMLSignedData(XML签名结果)

　　Type(待解析的参数类型) ,取值范围 :

　　a) 1:解析出 XML原文 ;

　　b) 2:解析出摘要值 ;

　　c) 3:解析出签名值 ;

　　d) 4:解析出签名证书 ;

　　e) 5:解析出摘要算法 ;

　　f) 6:解析出签名算法

　　返回值

　　解析结果(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　12

　　GB/T 43694—2024

　　表 28 解析 XML数据签名接口定义 (续)

　　安全规则

　　XML签名缺省配置和参数值样例 :

　　a) XML原文取自 Object元素 ;

　　b) 摘要值取自 DigestValue元素,形如 http://127.0.0.1/2001/04/xmldsig-more#sm3;

　　c) 签名值取自 SignatureValue元素 ,为 Base64编码 ;

　　d) 签名证书取自 X509Data元素 ,为 Base64编码 ;

　　e) 摘 要 算 法 取 自 DigestMethod元 素 的 Algorithm 属 性, 形 如 http://127.0.0.1/2001/04/xmldsig-more

　　# sm3;

　　f) 签名算法取自 SignatureMethod元素的 Algorithm属性,形如 http://127.0.0.1/2001/04/xmldsig-more# sm2-sm3

　　7. 1.29 产生随机数

　　产生随机数接口定义应符合表 29的规定 。

　　表 29 产生随机数接口定义

　　原型

　　BSTR SOF_GenRandom(LONG RandomLen)

　　描述

　　产生指定长度的随机数

　　参数

　　RandomLen(待产生随机数的字节长度)

　　返回值

　　Base64编码的随机数(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7. 1.30 获取最新的错误信息

　　获取最新的错误信息接口定义应符合表 30的规定 。

　　表 30 获取最新的错误信息接口定义

　　原型

　　LONG SOF_GetLastError()

　　描述

　　获取最新的错误代码

　　参数

　　无

　　返回值

　　错误代码 ,应符合表 A. 1错误代码表

　　7. 1.31 计算数据摘要

　　计算数据摘要接口定义应符合表 31的规定 。

　　表 31 计算数据摘要接口定义

　　原型

　　BSTR SOF_ HashData(LONG HashAlg,BSTR InData,BSTR SignCert,BSTR UserID)

　　描述

　　计算数据摘要 。若采用 SM3算法 , 当 SignCert和 UsreID为空时 , 只计算数据的摘要值 , 当 SignCert和UsreID值不为空时 ,应按照 GB/T 35276规定的预处理过程计算 ,摘要值可作为 SM2签名的输入

　　13

　　GB/T 43694—2024

　　表 31 计算数据摘要接口定义 (续)

　　参数

　　HashAlg(摘要算法 ,应符合 GB/T 33560的规定)

　　Indata(原文)

　　SignCert(Base64编码的签名者证书 , 当摘要算法为 SM3时有效 ,如不需要可传空串)

　　UserID(签名者用户 ID, 当摘要算法为 SM3时有效 ,若 SignCert参数为空 ,本参数无意义)

　　返回值

　　Base64编码的数据摘要值(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7. 1.32 计算文件摘要

　　计算文件摘要接口定义应符合表 32的规定 。

　　表 32 计算文件摘要接口定义

　　原型

　　BSTR SOF_ HashFile(LONG HashAlg,BSTR InFile,BSTR SignCert,BSTR UserID)

　　描述

　　计算文件数据摘要 ,若采用 SM3算法 , 当 SignCert和 UsreID为空时 ,只计算数据的摘要值 , 当 SignCert和 UsreID值不为空时 ,应按照 GB/T 35276规定的预处理过程计算 ,摘要值可作为 SM2签名的输入

　　参数

　　HashAlg(摘要算法 ,应符合 GB/T 33560的规定)

　　InFile(原文文件全路径)

　　SignCert(Base64编码的签名者证书 , 当摘要算法为 SM3时有效 ,如不需要可传空串)

　　UserID(签名者用户 ID, 当摘要算法为 SM3时有效 ,若 SignCert参数为空 ,本参数无意义)

　　返回值

　　Base64编码的文件摘要值(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7. 1.33 摘要数据签名

　　摘要数据签名接口定义应符合表 33的规定 。

　　表 33 摘要数据签名接口定义

　　原型

　　BSTR SOF_SignHashData(BSTR CertID,BSTR Base64HashData,LONG HashAlg)

　　描述

　　对数据摘要值签名 ,返回 Base64编码的数据类型 A签名结果 。

　　Base64HashData参数一般是 SOF_ HashData或 SOF_ HashFile 函 数 的 计 算 结 果 。 当 采 用 SM2算 法 签名时 ,SM3算法的摘要值应按照 GB/T 35276规定的预处理过程计算

　　参数

　　CertID(证书唯一标识)

　　Base64HashData(Base64编码的摘要值)

　　HashAlg(摘要算法 ,应符合 GB/T 33560的规定)

　　返回值

　　Base64编码的签名值(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　安全规则

　　本接口应在登录状态下才能成功返回签名值 ,否则应返回空串

　　14

　　GB/T 43694—2024

　　7. 1.34 验证摘要数据签名

　　验证摘要数据签名接口定义应符合表 34的规定 。

　　表 34 验证摘要数据签名接口定义

　　原型

　　BOOL SOF_VerifySignedHashData(BSTR Base64Cert,

　　BSTR Base64HashData,

　　BSTR SignValue,LONG HashAlg)

　　描述

　　数据摘要签名验证 ,签名值格式为 Base64编码的数据类型 A。

　　若使用 SM2算法验证签名 ,Base64HashData参数是 SM3算法的摘要值 ,应按照 GB/T 35276规定的预处理过程计算

　　参数

　　Base64Cert(Base64编码的签名者证书)

　　Base64HashData(Base64编码的摘要值)

　　SignValue(Base64编码的签名值)

　　HashAlg(摘要算法 ,应符合 GB/T 33560的规定)

　　返回值

　　TRUE(成功)

　　FALSE(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7. 1.35 证书登出

　　证书登出接口定义应符合表 35的规定 。

　　表 35 证书登出接口定义

　　原型

　　BOOL SOF_Logout(BSTR CertID)

　　描述

　　退出登录状态

　　参数

　　CertID(证书唯一标识)

　　返回值

　　TRUE(成功)

　　FALSE(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　安全规则

　　证书登出表示释放该证书用户对应的私钥使用权限 。证书登出后再调用签名 、解密等需要拥有私钥 使用权限才能正常操作的接口时 ,应再次成功调用 SOF_Login接口获取私钥使用权限

　　7. 1.36 证书登录状态检测

　　证书登录状态检测接口定义应符合表 36的规定 。

　　表 36 证书登录状态检测接口定义

　　原型

　　BOOL SOF_IsLogin(BSTR CertID)

　　描述

　　判断证书用户是否为登录状态

　　参数

　　CertID(证书唯一标识)

　　返回值

　　TRUE(登录状态)

　　FALSE(非登录状态)

　　15

　　GB/T 43694—2024

　　7.2 客户端 JavaScript脚本接口

　　7.2. 1 客户端 JavaScript脚本接口综述

　　客户端 JavaScript脚本接口采用异步方式定义 ,所有接口的返回值都通过回调函数的第一个参数返回 ,提供配置管理 、证书解析 、签名与验证 、加密与解密数字信封 、XML数据签名与验证等功能 ,共包含 32个接 口 。客户端 JavaScript脚本接口列表见表 D. 2。 7. 2. 2~ 7. 2. 33给出了接口详细定义 ,其调用示例说明见附录 E。

　　7.2.2 获取接口版本信息

　　获取接口版本信息接口定义应符合表 37的规定 。

　　表 37 获取接口版本信息接口定义

　　原型

　　functionSOF_GetVersion(cb,ctx)

　　描述

　　获取接口的版本号

　　参数

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　接口版本号(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7.2.3 设置签名算法

　　设置签名算法接口定义应符合表 38的规定 。

　　表 38 设置签名算法接口定义

　　原型

　　functionSOF_SetSignMethod(SignMethod,cb,ctx)

　　描述

　　设置接口在签名和验签运算时使用的签名算法

　　参数

　　SignMethod(签名算法标识 ,应符合 GB/T 33560的规定)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　SAR_OK(成功)

　　其他(失败 ,返回表 A. 1定义的错误代码)

　　7.2.4 获得签名算法

　　获得签名算法接口定义应符合表 39的规定 。

　　表 39 获得签名算法接口定义

　　原型

　　functionSOF_GetSignMethod(cb,ctx)

　　描述

　　获得接口当前使用的签名算法

　　16

　　GB/T 43694—2024

　　表 39 获得签名算法接口定义 (续)

　　参数

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　当前使用的签名算法标识(成功)

　　0(当前没有设置签名算法)

　　7.2.5 设置加密算法

　　设置加密算法接口定义应符合表 40的规定 。

　　表 40 设置加密算法接口定义

　　原型

　　functionSOF_SetEncryptMethod(EncryptMethod,cb,ctx)

　　描述

　　设置接口进行数据加密时使用的对称算法

　　参数

　　EncryptMethod(对称密码算法标识 ,应符合 GB/T 33560 的 规 定 。本 接 口 支 持 不 带 附 加 认 证 数 据 的 加密算法)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　SOR_OK(成功)

　　其他(失败 ,返回符合表 A. 1定义的错误代码)

　　7.2.6 获得加密算法

　　获得加密算法接口定义应符合表 41的规定 。

　　表 41 获得加密算法接口定义

　　原型

　　functionSOF_GetEncryptMethod(cb,ctx)

　　描述

　　获得接口当前使用的对称加密算法

　　参数

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　当前使用的加密算法标识(成功)

　　0(当前没有设置加密算法)

　　7.2.7 获得证书用户列表

　　获得证书用户列表接口定义应符合表 42的规定 。

　　17

　　GB/T 43694—2024

　　表 42 获得证书用户列表接口定义

　　原型

　　functionSOF_GetUserList(cb,ctx)

　　描述

　　获取证书用户列表

　　参数

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　证书列表(成功 ,格式和 7. 1. 7相同)

　　空串(失败或当前不存在证书用户列表 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7.2. 8 导出用户签名证书

　　导出用户签名证书接口定义应符合表 43的规定 。

　　表 43 导出用户签名证书接口定义

　　原型

　　functionSOF_ExportUserCert(CertID,cb,ctx)

　　描述

　　根据证书唯一标识 ,获取 Base64编码的签名证书字符串

　　参数

　　CertID(证书唯一标识)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　Base64编码的签名证书字符串(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7.2.9 证书登录

　　证书登录接口定义应符合表 44的规定 。

　　表 44 证书登录接口定义

　　原型

　　functionSOF_Login(CertID,PassWd,cb,ctx)

　　描述

　　校验证书口令 ,进行用户认证

　　参数

　　CertID(证书唯一标识)

　　PassWd(证书口令)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　true(成功)

　　false(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　安全规则

　　证书登录成功后 ,表示该证书用户 已 拥 有 私 钥 使 用 权 限 , 即 登 录 状 态 。登 录 状 态 下 , 可 正 常 调 用 签 名 、解密等需要私钥使用权限的接 口 ,获得计算结果

　　7.2. 10 获取证书口令剩余重试次数

　　获取证书口令剩余重试次数接口定义应符合表 45的规定 。

　　18

　　GB/T 43694—2024

　　表 45 获取证书口令剩余重试次数接口定义

　　原型

　　functionSOF_GetPinRetryCount(CertID,cb,ctx)

　　描述

　　获取证书口令剩余重试次数

　　参数

　　CertID(证书唯一标识)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　剩余口令重试次数 , 当重试次数小于或等于 0 时表示证书口令已被锁定

　　7.2. 11 修改证书口令

　　修改证书口令接口定义应符合表 46的规定 。

　　表 46 修改证书口令接口定义

　　原型

　　function ChangeUserPassword(CertID,OldPassWd,NewPassWd,cb,ctx)

　　描述

　　修改证书口令

　　参数

　　CertID(证书唯一标识)

　　OldPassWd(旧证书口令)

　　NewPassWd(新证书口令)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　true(修改口令成功)

　　false(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7.2. 12 导出用户加密证书

　　导出用户加密证书接口定义应符合表 47的规定 。

　　表 47 导出用户加密证书接口定义

　　原型

　　functionSOF_ExportExChangeUserCert(CertID,cb,ctx)

　　描述

　　根据证书唯一标识 ,获取 Base64编码的加密(交换)证书字符串

　　参数

　　CertID(证书唯一标识)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　Base64编码的加密证书字符串(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7.2. 13 获得证书基本信息

　　获得证书基本信息接口定义应符合表 48的规定 。

　　19

　　GB/T 43694—2024

　　表 48 获得证书基本信息接口定义

　　原型

　　functionSOF_GetCertInfo(Base64Cert,Type,cb,ctx)

　　描述

　　获取证书基本信息

　　参数

　　Base64Cert(Base64编码的证书字符串)

　　Type(证书解析标识 ,应符合 GB/T 33560的规定)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　指定类型的证书信息(成功)

　　空串(失败或证书中不存在该项内容)

　　7.2. 14 获得证书扩展信息

　　获得证书扩展信息接口定义应符合表 49的规定 。

　　表 49 获得证书扩展信息接口定义

　　原型

　　functionSOF_GetCertInfoByOid(Base64Cert,Oid,cb,ctx)

　　描述

　　根据 OID获取证书扩展项信息

　　参数

　　Base64Cert(Base64编码的证书字符串)

　　Oid(私有扩展对象 ID,如“1. 2. 156. xxx”)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　证书私有扩展项 OID对应的信息(成功)

　　空串(失败或证书中不存在该私有扩展项)

　　7.2. 15 获得设备信息

　　获得设备信息接口定义应符合表 50的规定 。

　　表 50 获得设备信息接口定义

　　原型

　　functionSOF_GetDeviceInfo(CertID,Type,cb,ctx)

　　描述 :

　　根据证书唯一标识和类型代码获得设备信息

　　参数

　　CertID(证书唯一标识)

　　Type(设备信息的类型 ,应符合 GB/T 33560的规定)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　对应的设备信息(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　20

　　GB/T 43694—2024

　　7.2. 16 验证证书有效性

　　验证证书有效性接口定义应符合表 51的规定 。

　　表 51 验证证书有效性接口定义

　　原型

　　functionSOF_ValidateCert(Base64Cert,cb,ctx)

　　描述

　　验证证书有效性

　　参数

　　Base64Cert(Base64编码格式的证书)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　SAR_OK(验证成功)

　　其他(验证失败 ,失败原因应符合表 A. 1 中的错误代码范围 0X0B000500~ 0X0B000505)

　　验证策略

　　本接口传入的证书是 Base64格式的串 ,一般通过获取签名(或加密)证书来取得 。验证证书有效性在本地完成 ,可信根证书列表由实现者管理 。

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

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

　　b) 各层证书的有效期验证 ;

　　c) 各层证书的吊销状态 。在特殊情况下(如 : 网络条件不允许) ,证书的吊销状态可采取灵活方式 , 由应用系统各层内部维护一个吊销列表 ,在证书登录认证时应用该吊销列表 。验证证书有效性也可采取代理验证方式

　　7.2. 17 数据签名

　　数据签名接口定义应符合表 52的规定 。

　　表 52 数据签名接口定义

　　原型

　　functionSOF_SignData(CertID,InData,cb,ctx)

　　描述

　　对字符串数据进行数字签名 ,返回 Base64编码的数据类型 A签名结果

　　参数

　　CertID(证书唯一标识)

　　InData(原文)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　Base64编码的签名值(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　安全规则

　　本接口应在登录状态下才能成功返回签名值 ,否则应返回空串

　　7.2. 18 验证数据签名

　　验证数据签名接口定义应符合表 53的规定 。

　　21

　　GB/T 43694—2024

　　表 53 验证数据签名接口定义

　　原型

　　functionSOF_VerifySignedData(Base64Cert,InData,SignValue,cb,ctx)

　　描述

　　验证数据签名 ,签名值为 Base64编码的数据类型 A

　　参数

　　Base64Cert(Base64编码的签名者证书)

　　InData(原文)

　　SignValue(Base64编码的签名值)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　true(成功)

　　false(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7.2. 19 数据加密

　　数据加密接口定义应符合表 54的规定 。

　　表 54 数据加密接口定义

　　原型

　　functionSOF_EncryptData(Base64Cert,InData,cb,ctx)

　　描述

　　数字信封加密 ,加密过程为使用临时 产 生 的 对 称 密 钥 加 密 数 据 ,然 后 使 用 数 字 证 书 的 公 钥 加 密 对 称 密钥 ,返回 Base64编码的数据类型 B密文数据

　　参数

　　Base64Cert(Base64编码的数据接收者的加密证书 ,如使用多个证书对数据加密 ,证书之间用 &&& 作为分隔符连接)

　　InData(待加密的明文数据)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　Base64编码格式的密文数据(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7.2.20 数据解密

　　数据解密接口定义应符合表 55的规定 。

　　表 55 数据解密接口定义

　　原型

　　functionSOF_DecryptData(CertID,InData,cb,ctx)

　　描述

　　使用证书对应的私钥解密数字信封 ,密文数据格式为 Base64编码的数据类型 B

　　参数

　　CertID(证书唯一标识)

　　Indata(待解密的 Base64编码格式的密文数据)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　22

　　GB/T 43694—2024

　　表 55 数据解密接口定义 (续)

　　返回值

　　解密后的明文数据(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　安全规则

　　本接口应在登录状态下才能解密得到明文 ,否则应返回空串

　　7.2.21 消息签名

　　消息签名接口定义应符合表 56的规定 。

　　表 56 消息签名接口定义

　　原型

　　functionSOF_SignMessage(Flag,CertID,InData,cb,ctx)

　　描述

　　对字符串数据进行消息签名 ,返回 Base64编码的数据类型 B签名结果

　　参数

　　Flag(是否为 Detached 的标识) ,取值范围 :

　　a) 1:表示 Detached, 即不带原文 ;

　　b) 0:表示 Attached, 即带原文

　　CertID(证书唯一标识)

　　InData(原文)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　Base64编码的消息签名值(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　安全规则

　　本接口应在登录状态下才能成功返回签名值 ,否则应返回空串

　　7.2.22 验证消息签名

　　验证消息签名接口定义应符合表 57的规定 。

　　表 57 验证消息签名接口定义

　　原型

　　functionSOF_VerifySignedMessage(SignedMessage,InData,cb,ctx)

　　描述

　　验证消息签名 ,签名值的格式为 Base64编码的数据类型 B

　　参数

　　SignedMessage(Base64编码的消息签名值)

　　InData(原文 ,若签名中包含原文 ,忽略本参数)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　true(成功)

　　false(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　23

　　GB/T 43694—2024

　　7.2.23 解析消息签名

　　解析消息签名接口定义应符合表 58的规定 。

　　表 58 解析消息签名接口定义

　　原型

　　functionSOF_GetInfoFromSignedMessage(SignedMessage,Type,cb,ctx)

　　描述

　　解析消息签名值中的信息 ,包括 :原文 、签名值 、签名证书等 ,消息签名值格式为 Base64编码的数据类型 B

　　参数

　　SignedMessage(Base64编码的消息签名值)

　　Type(类型) ,取值范围 :

　　a) 1:解析出原文 ;

　　b) 2:解析出 Base64编码的签名者证书 ;

　　c) 3:解析出 Base64编码的签名值

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　解析结果(成功)

　　空串(失败或不存在该项)

　　7.2.24 XML数据签名

　　XML数据签名接口定义应符合表 59的规定 。

　　表 59 XML数据签名接口定义

　　原型

　　functionSOF_SignDataXML(CertID,InXMLData,cb,ctx)

　　描述

　　对 XML数据进行数字签名 ,证书为 RSA算法时签名结果参见 RFC3275,证书为 SM2算法时签名结果应符合 GB/T 25061的规定

　　参数

　　CertID(证书唯一标识)

　　InXMLData(待签名的 XML数据)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　XML签名结果(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　安全规则

　　本接口应在登录状态下才能返回签名值 ,否则应返回空串 。

　　缺省配置和参数 :

　　a) 采用封皮签名 ,签名前应对签名原文做格式化 ;

　　b) 格 式 化 方 法 采 用 带 注 释 的 XML格 式 化 1.1,证 书 为 RSA算 法 时 标 识 符 为 http://www. w3. org/ 2006/12/xml-c14n11#WithComment,证书为 SM2算法时标识符为 http://127.0.0.1/2006/12/xml- c14n11#WithComments

　　7.2.25 验证 XML数据签名

　　验证 XML数据签名接口定义应符合表 60的规定 。

　　24

　　GB/T 43694—2024

　　表 60 验证 XML数据签名接口定义

　　原型

　　functionSOF_VerifySignedDataXML(SignedXMLData,cb,ctx)

　　描述

　　验证 XML签名

　　参数

　　SignedXMLData(XML签名结果)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　true(成功)

　　false(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7.2.26 解析 XML数据签名

　　解析 XML数据签名接口定义应符合表 61的规定 。

　　表 61 解析 XML数据签名接口定义

　　原型

　　functionSOF_GetXMLSignatureInfo(XMLSignedData,Type,cb,ctx)

　　描述

　　解析 XML数据签名 ,获取签名值 、XML原文 、证书和相关算法等信息

　　参数

　　XMLSignedData(XML签名结果)

　　Type(待解析的参数类型) ,取值范围 :

　　a) 1:解析出 XML原文 ;

　　b) 2:解析出摘要值 ;

　　c) 3:解析出签名值 ;

　　d) 4:解析出签名证书 ;

　　e) 5:解析出摘要算法 ;

　　f) 6:解析出签名算法

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　解析结果(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　安全规则

　　XML签名缺省配置和参数值样例 :

　　a) XML原文取自 Object元素 ;

　　b) 摘要值取自 DigestValue元素,形如 http://127.0.0.1/2001/04/xmldsig-more#sm3;

　　c) 签名值取自 SignatureValue元素 ,为 Base64编码 ;

　　d) 签名证书取自 X509Data元素 ,为 Base64编码 ;

　　e) 摘 要 算 法 取 自 DigestMethod元 素 的 Algorithm 属 性, 形 如 http://127.0.0.1/2001/04/xmldsig-more

　　# sm3;

　　f) 签名算法取自 SignatureMethod元素的 Algorithm属性,形如 http://127.0.0.1/2001/04/xmldsig-more# sm2-sm3

　　7.2.27 产生随机数

　　产生随机数接口定义应符合表 62的规定 。

　　25

　　GB/T 43694—2024

　　表 62 产生随机数接口定义

　　原型

　　functionSOF_GenRandom(RandomLen,cb,ctx)

　　描述

　　产生指定长度的随机数

　　参数

　　RandomLen(待产生随机数的字节长度)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　Base64编码的随机数(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　7.2.28 获取最新的错误信息

　　获取最新的错误信息接口定义应符合表 63的规定 。

　　表 63 获取最新的错误信息接口定义

　　原型

　　functionSOF_GetLaseError(cb,ctx)

　　描述

　　获取最新的错误码

　　参数

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　错误代码 ,应符合表 A. 1错误代码表

　　7.2.29 计算数据摘要

　　计算数据摘要接口定义应符合表 64的规定 。

　　表 64 计算数据摘要接口定义

　　原型

　　functionSOF_ HashData(HashAlg,InData,SignCert,UserID,cb,ctx)

　　描述

　　计算数据摘要 ,若采用 SM3算 法 , 当 SignCert和 UsreID 为 空 时 , 只 计 算 数 据 的 摘 要 值 , 当 SignCert和UsreID值不为空时 ,应按照 GB/T 35276规定的预处理过程计算 ,摘要值可作为 SM2签名的输入

　　参数

　　HashAlg(摘要算法 ,应符合 GB/T 33560的规定)

　　InData(原始数据)

　　SignCert(Base64编码的签名者证书 , 当摘要算法为 SM3时有效 ,如不需要传空串)

　　UserID(签名者用户 ID,摘要算法为 SM3时有效 ,若 SignCert参数为空 ,本参数无意义)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　Base64编码的数据摘要值(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　26

　　GB/T 43694—2024

　　7.2.30 摘要数据签名

　　摘要数据签名接口定义应符合表 65的规定 。

　　表 65 摘要数据签名接口定义

　　原型

　　functionSOF_SignHashData(CertID,Base64HashData, HashAlg,cb,ctx)

　　描述

　　对数据摘要签名 ,返回 Base64编码的数据类型 A签名结果 。

　　Base64HashData值一般是 SOF_ HashData或 SOF_ HashFile 函 数 的 计 算 结 果 。 当 采 用 SM2算 法 签 名时 ,SM3算法的摘要值应按照 GB/T 35276规定的预处理过程计算

　　参数

　　CertID(证书唯一标识)

　　Base64HashData(Base64编码的摘要值)

　　HashAlg(摘要算法 ,应符合 GB/T 33560的规定)

　　cb(回调函数)

　　ctx(回调函数所需参数)

　　返回值

　　Base64编码的签名值(成功)

　　空串(失败 ,可通过 SOF_GetLastError获取符合表 A. 1定义的错误代码)

　　安全规则

　　本接口应在登录状态下才能成功返回签名值 ,否则应返回空串

　　7.2.31 验证摘要数据签名

　　验证摘要数据签名接口定义应符合表 66的规定 。

　　表 66 验证摘要数据签名接口定义

　　原型

　　functionSOF_VerifySignedHashData(

　　Base64Cert,Base64HashData,SignValue, HashAlg,cb,ctx)

　　描述

　　数据摘要签名验证 ,签名值为 Base64编码的数据类型 A。

　　若使用 SM2算法验证签名 ,Base64HashData参数是 SM3算法的摘要值 ,应按照 GB/T 35276规定的预处理过程计算

　　参数

　　Base64Cert(Base64编码签名者证书)

　　参数

　　Base64HashData(Base64编码摘要值)

　　SignValue(Base64编码的签名值)

　　HashAlg(摘要算法 ,应符合 GB/T 33560的规定)

　　cb(回调函数)