GB/T 43694-2024
基本信息
标准号： GB/T 43694-2024
中文名称：网络安全技术 证书应用综合服务接口规范
标准类别：国家标准(GB)
英文名称：Cybersecurity technology—Certificate application integrated service interface specification
标准状态：现行
发布日期：2024-04-25
实施日期：2024-11-01
出版语种：简体中文
下载格式：.pdf .zip
下载大小：14127575
相关标签： 网络安全 技术 证书 应用 综合 服务 接口 规范
标准分类号
标准ICS号：35.030
中标分类号：电子元器件与信息技术>>信息处理技术>>L80数据加密
关联标准
出版信息
出版社：中国标准出版社
页数：80页【胶订-大印张】
标准价格：119.0
相关单位信息
起草人：刘伟 赵永省 夏鲁宁 李述胜 刘中 程科伟 浦雨三 张屹 张志磊 马洪富 袁中林 李智虎 焦靖伟 刘平 黄晶晶 谭武征 寇建波 颜海龙 刘献伦 刘为华 肖淑婷 张文科 杨倩媚 董亮亮 周蔚林 韩玮 高振鹏 胡建勋 刘冲 牟洁
起草单位：北京数字认证股份有限公司、博雅中科(北京)信息技术有限公司、北京奇虎科技有限公司、山东得安信息技术有限公司、中国电力科学研究院、北京信安世纪科技股份有限公司、无锡江南信息安全工程技术中心、中国电子技术标准化研究院、格尔软件股份有限公司等
归口单位：全国网络安全标准化技术委员会(SAC/TC 260)
提出单位：全国网络安全标准化技术委员会(SAC/TC 260)
发布部门：国家市场监督管理总局 国家标准化管理委员会
标准简介
本文件规定了面向证书应用的综合服务接口要求和定义，描述了相应验证方法。本文件适用于公钥密码基础设施应用技术体系下证书应用中间件和证书应用系统的开发，以及密码应用支撑平台的研制和检测。
标准图片预览
标准内容
ICS35.030
CCS L 80
中华人民共和国国家标准
43694—2024
网络安全技术
证书应用综合服务接口规范
Cybersecurity technology-Certificate applicationintegrated service interface specification2024-04-25发布
国家市场监督管理总局
国家标准化管理委员会
2024-11-01实施
GB/T43694—2024
1范围
规范性引用文件
3术语和定义
缩略语
证书应用综合服务接口
证书应用综合服务接口在公钥密码应用技术体系框架中的位置证书应用综合服务接口分类
客户端服务接口
服务器端服务接口
标识和数据结构
标识定义
数据结构定义
数据格式要求
证书应用综合服务接口定义
客户端COM组件接口
客户端JavaScript脚本接口
服务器端COM组件接口
服务器端Java组件接口
8接口验证方法
验证环境，
验证原则。
验证场景
附录A（规范性）证书应用综合服务接口错误代码定义附录B（资料性）证书应用综合服务接口典型部署模型.附录C（资料性）证书应用综合服务接口集成示例附录D（资料性）证书应用综合服务接口汇总附录E(资料性）
参考文献
客户端JavaScript
脚本接口异步调用示例说明
GB/T43694—2024
本文件按照GB/T1.1一2020《标准化工作导则第1部分：标准化文件的结构和起草规则》的规定起草。
请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。本文件由全国网络安全标准化技术委员会(SAC/TC260)提出并归口。本文件起草单位：北京数字认证股份有限公司、博雅中科（北京)信息技术有限公司、北京奇虎科技有限公司、山东得安信息技术有限公司、中国电力科学研究院、北京信安世纪科技股份有限公司、无锡江南信息安全工程技术中心、中国电子技术标准化研究院、格尔软件股份有限公司、中电科网络安全科技股份有限公司、深圳市不动产登记中心、郑州信大捷安信息技术股份有限公司、阿里云计算有限公司、浙江九州量子信息技术股份有限公司、航天信息股份有限公司、数安时代科技股份有限公司、智巡密码（上海检测技术有限公司、中科信息安全共性技术国家工程研究中心有限公司、中国汽车工程研究院股份有限公司。
本文件主要起草人：刘伟、赵永省、夏鲁宁、李述胜、刘中、程科伟、浦雨三、张屹、张志磊、马洪富、袁中林、李智虎、焦靖伟、刘平、黄晶晶、谭武征、寇建波、颜海龙、刘献伦、刘为华、肖淑婷、张文科、杨倩媚、董亮亮、周蔚林、韩玮、高振鹏、胡建勋、刘冲、牟洁。I
1范围
网络安全技术证书应用综合服务接口规范本文件规定了面向证书应用的综合服务接口要求和定义，描述了相应验证方法。GB/T43694—2024
本文件适用于公钥密码基础设施应用技术体系下证书应用中间件和证书应用系统的开发，以及密码应用支撑平台的研制和检测。2规范性引用文件
下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单)适用于本文件。
GB/T20518
GB/T25061
GB/T35276
GB/T35291
GB/T36322
GB/T43578
信息安全技术
公钥基础设施数字证书格式
信息安全技术
XML数字签名语法与处理规范
信息安全技术
信息安全技术
信息安全技术
信息安全技术
信息安全技术
信息安全技术
信息安全技术
密码应用标识规范
SM2密码算法加密签名消息语法规范SM2密码算法使用规范
智能密码钥匙应用接口规范
密码设备应用接口规范
通用密码服务接口规范
0094一2020公钥密码应用技术体系框架规范GM/Z4001
3术语和定义
密码术语
25069、GM/Z4001界定的以及下列术语和定义适用于本文件。3.1
数字证书digital certificate
由CA签名的包含公开密钥拥有者信息、公开密钥、签发者信息、有效期以及扩展信息的一种数据结构。
注：数字证书也称公钥证书，按类别分为个人证书、机构证书和设备证书，按用途分为签名证书和加密证书［来源：GM/Z4001—2013,2.115]3.2
用户密钥userkey
存储在设备内部的用于应用密码运算的非对称密钥对。注：用户密钥包含签名密钥对和加密密钥对3.3
密钥容器keycontainer
密码设备中用于保存用户密钥的唯一性存储空间。GB/T43694—2024
4缩略语
下列缩略语适用于本文件。
B/S：浏览器/服务器(Browser/Server）CA：证书认证机构(CertificationAuthority)COM：组件对象模型(ComponentObjectModel)CRL：证书撤销列表(CertificateRevocationList）JAR:Java归档文件(JavaArchive)LDAP：轻量级目录访问协议(Lightweight DirectoryAccess Protocol)OID：对象标识符（ObjectIdentifier）XML：可扩展标记语言(ExtensibleMarkupLanguage)5证书应用综合服务接口
5.1证书应用综合服务接口在公钥密码应用技术体系框架中的位置公钥密码应用技术体系框架由应用层、典型密码应用支撑层、通用密码应用支撑层、基础设施安全支撑平台、密码设备服务层组成。证书应用综合服务接口属于通用密码应用支撑层，是中间件，为典型密码应用支撑层和应用层提供密码服务。其功能主要包括：负责完成与密码设备的安全连接；实现基于数字证书的身份认证，从证书中获取有关信息，实现授权管理、访问控制等安全机制；负责具体与密码设备交互实现具体的密码运算；将数据按照GB/T35275要求的格式进行封装，实现数据封装格式与应用系统无关性，实现应用系统互联互通和信息共享。证书应用综合服务接口规范在公钥密码应用技术框架内的位置应遵循GM/T0094一2020的第4章。5.2证书应用综合服务接口分类
证书应用综合服务接口包括客户端服务接口和服务器端服务接口两类。它位于典型密码应用支撑层和密码设备服务层之间，既可被典型密码应用支撑层调用也可被应用层直接调用，向上层提供证书信息解析、基于数字证书身份认证、信息的机密性、完整性和不可否认性等密码服务。5.3客户端服务接口
客户端服务接口采用支持多种编程语言的COM组件和客户端常使用的JavaScript脚本语言为例描述，其适用于客户端程序调用，接口的形态包括动态库、控件、插件、扩展等。客户端服务接口一般通过调用智能密码钥匙应用接口或通用密码服务接口来实现，此类接口应符合GB/T35291或GB/T43578中的规定，主要功能包括：配置管理、证书解析、签名与验证、加密与解密数字信封、XML数据签名与验证等。5.4服务器端服务接口
服务器端服务接口采用支持多种编程语言的COM组件和服务端常使用的Java语言为例描述，其适用于服务器端程序调用，接口的形态包括COM组件、JAR包等，支持主流操作系统。服务器端服务接口一般通过调用密码设备应用接口或通用密码服务接口来实现，此类接口应符合GB/T36322或GB/T43578中的规定，功能基本与客户端服务接口相对应，主要包括：配置管理、证书解析、签名与验证、加密与解密数字信封、XML数据签名与验证、时间戳等。2
6标识和数据结构
6.1标识定义
GB/T43694—2024
本文件所使用的常量、各类算法标识和证书解析标识应符合GB/T33560的规定。
6.2数据结构定义
本文件规定的接口处理的数据分为两种类型：数据类型A：是一种基于公钥的加密或签名结构，当公钥算法为RSA时，数据的结构参见PKCS#1v1.5；当公钥算法为SM2时，数据的结构应符合GB/T35276的规定。数据类型B：是一种基于证书的加密或签名结构，当证书的公钥算法为RSA时，消息的结构参见PKCS#7；当证书的公钥算法为SM2时，消息的结构应符合GB/T35275的规定。6.3数据格式要求
本文件所涉及的数字证书格式应符合GB/T20518的规定。本文件所描述的Base64编码格式参见RFC4648中Base64Encoding部分。在没有特殊说明的情况下，本文件中字符串采用UTF-8编码，其格式参见RFC3629。本文件所定义接口返回的错误码或抛出的异常信息应符合附录A，典型部署模型可参见附录B，集成示例可参见附录C
本文件以COM组件为例进行接口描述时，所用到的数据类型说明见表1。表1COM组件数据类型说明
字符串类型，不同的开发语言应采取对应的类型定义，如：char*、CString、java.lang.String等32位整数
16位整数
布尔类型，其取值范围是TRUE和FALSE，其中TRUE表示真值，FALSE表示假值长度等于0的字符串
长度大于0的字符串
7证书应用综合服务接口定义
7.1客户端COM组件接口
7.1.1客户端COM组件接口综述
客户端COM组件接口提供配置管理、证书解析、签名与验证、加密与解密数字信封、XML数据签名与验证等功能，共包含35个接口。客户端COM组件接口列表见附录D的表D.1，7.1.27.1.36给出了接口详细定义。
7.1.2获取接口版本信息
获取接口版本信息接口定义应符合表2的规定。3
T43694—2024
返回值
表2获取接口版本信息接口定义
BSTR SOF_GetVersionO
获取接口的版本号
接口版本号(成功）
空串（失败，可通过SOF_GetLastError获取符合表A.1定义的错误代码）设置签名算法
设置签名算法接口定义应符合表3的规定表3设置签名算法接口定义
返回值
LONG SOF_SetSignMethod(LONG SignMethod)设置接口在签名和验签运算时使用的签名算法SignMethod（签名算法标识，应符合GB/T33560的规定）SOR_OK（成功）
其他（失败，返回符合表A.1定义的错误代码）获得签名算法
获得签名算法接口定义应符合表4的规定。表4
返回值
LONG SOF_GetSignMethodObzxz.net
获得接口当前使用的签名算法
当前使用的签名算法标识（成功）0(当前没有设置签名算法)
设置加密算法
获得签名算法接口定义
设置加密算法接口定义应符合表5的规定设置加密算法接口定义
返回值
LONG SOF_SetEncryptMethod(LONG EncryptMethod)设置接口进行数据加密时使用的对称算法EncryptMethod（对称加密算法标识，应符合GB/T33560的规定，本接口可支持不带附加认证数据的加解密算法）
SOR_OK（成功）
其他（失败，返回表A.1定义的错误代码）7.1.6
获得加密算法
获得加密算法接口定义应符合表6的规定表6
返回值
LONG SOF_GetEncryptMethod O
获得加密算法接口定义
获得接口当前使用的对称加解密算法无
当前使用的加密算法标识（成功）0(当前没有设置加密算法）
获得证书列表
获得证书列表接口定义应符合表7的规定。表7
返回值
BSTR SOF_GetUserList ()
取得当前已安装证书的用户列表无
获得证书列表接口定义
43694—2024
证书列表［成功，返回证书列表字符串数据，格式为：用户名1IICertID18.&.＆.用户名2|ICertID2&.＆.&，根据证书应用的策略不同得到不同的证书列表返回值。在证书列表中，用户名代表证书的通用名(CommonName），CertID是证书唯一标识，其格式由实现者自定义，宜包含容器名、应用名、设备序列号等项。通过CertID应找到唯一的签名证书、加密证书，并使用对应的用户密钥」空串（失败或当前不存在证书用户列表，可通过SOF_GetLastError获取符合表A.1定义的错误代码）导出用户签名证书
导出用户签名证书接口定义应符合表8的规定。3导出用户签名证书接口定义
返回值
BSTR SOF_ExportUserCert (BSTR CertID)根据证书唯一标识，获取Base64编码的签名证书字符串CertID(证书唯一标识）
Base64编码的签名证书字符串（成功）空串（失败，可通过SOF_GetLastError获取符合表A.1定义的错误代码）7.1.9
证书登录
证书登录接口定义应符合表9的规定。GB/T
43694—2024
证书登录接口定义
BOOL SOF_Login(BSTR CertID, BSTR PassWd)校验证书口令，进行证书认证
CertID（证书唯一标识）
PassWd（证书口令）
返回值
安全规则
TRUE（成功）
FALSE（失败，可通过SOF_GetLastError获取符合表A.1定义的错误代码）证书登录成功后，表示该证书用户已拥有私钥使用权限，即登录状态。登录状态下，可正常调用签名、解密等需要私钥使用权限的接口，获得计算结果获取证书口令剩余重试次数
获取证书口令剩余重试次数接口定义应符合表10的规定。表10获取证书口令剩余重试次数接口定义原型
返回值
LONGSOF_GetPinRetryCount(BSTR CertID)获取证书口令的剩余重试次数
CertID(证书唯一标识）
剩余口令重试次数，当重试次数小于或等于0时表示证书口令已被锁定修改证书口令
修改证书口令接口定义应符合表11的规定。表11
返回值
修改证书口令接口定义
BOOL SOF_ChangePassWd(BSTR CertID,BSTR O1dPassWd,BSTR NewPassWd)修改设备的用户认证口令
CertID(证书唯一标识）
OldPassWd（旧证书口令）
NewPassWd（新证书口令）
TRUE（成功）
FALSE（失败，可通过SOFGetLastError获取符合表A.1定义的错误代码）导出用户加密证书
导出用户加密证书接口定义应符合表12的规定。6
返回值
导出用户加密证书接口定义
BSTR SOF_ExportExChangeUserCert (BSTR CertID)根据证书唯一标识，获取Base64编码的加密（交换）证书字符串CertID(证书唯一标识)
Base64编码的加密证书字符串（成功）空串（失败，可通过SOF_GetLastError获取符合表A.1定义的错误代码）获得证书信息
获得证书信息接口定义应符合表13的规定。表13
返回值
获得证书信息接口定义
BSTR SOF_GetCertInfo(BSTR Base64Cert, SHORT Type)获取证书内指定类型的信息
Base64Cert(Base64编码的证书字符串）Type（证书解析标识，应符合GB/T33560的规定）指定类型的证书信息(成功）
空串（失败或证书中不存在该项内容）获得证书扩展信息
获得证书扩展信息接口定义应符合表14的规定。表14获得证书扩展信息接口定义原型
返回值
BSTR SOF_GetCertlnfoByOid(BSTR Base64Cert, BSTR Oid)根据OID获取证书私有扩展项信息Base64Cert(Base64编码的证书字符串）Oid（私有扩展对象ID，如“1.2.156.xxx”）证书私有扩展项OID对应的信息（成功)空串(失败或证书中不存在该私有扩展项)获得设备信息
获得设备信息接口定义应符合表15的规定。43694—2024
小提示：此标准内容仅展示完整标准里的部分截取内容，若需要完整标准请到上方自行免费下载完整标准文档。
CCS L 80
中华人民共和国国家标准
43694—2024
网络安全技术
证书应用综合服务接口规范
Cybersecurity technology-Certificate applicationintegrated service interface specification2024-04-25发布
国家市场监督管理总局
国家标准化管理委员会
2024-11-01实施
GB/T43694—2024
1范围
规范性引用文件
3术语和定义
缩略语
证书应用综合服务接口
证书应用综合服务接口在公钥密码应用技术体系框架中的位置证书应用综合服务接口分类
客户端服务接口
服务器端服务接口
标识和数据结构
标识定义
数据结构定义
数据格式要求
证书应用综合服务接口定义
客户端COM组件接口
客户端JavaScript脚本接口
服务器端COM组件接口
服务器端Java组件接口
8接口验证方法
验证环境，
验证原则。
验证场景
附录A（规范性）证书应用综合服务接口错误代码定义附录B（资料性）证书应用综合服务接口典型部署模型.附录C（资料性）证书应用综合服务接口集成示例附录D（资料性）证书应用综合服务接口汇总附录E(资料性）
参考文献
客户端JavaScript
脚本接口异步调用示例说明
GB/T43694—2024
本文件按照GB/T1.1一2020《标准化工作导则第1部分：标准化文件的结构和起草规则》的规定起草。
请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。本文件由全国网络安全标准化技术委员会(SAC/TC260)提出并归口。本文件起草单位：北京数字认证股份有限公司、博雅中科（北京)信息技术有限公司、北京奇虎科技有限公司、山东得安信息技术有限公司、中国电力科学研究院、北京信安世纪科技股份有限公司、无锡江南信息安全工程技术中心、中国电子技术标准化研究院、格尔软件股份有限公司、中电科网络安全科技股份有限公司、深圳市不动产登记中心、郑州信大捷安信息技术股份有限公司、阿里云计算有限公司、浙江九州量子信息技术股份有限公司、航天信息股份有限公司、数安时代科技股份有限公司、智巡密码（上海检测技术有限公司、中科信息安全共性技术国家工程研究中心有限公司、中国汽车工程研究院股份有限公司。
本文件主要起草人：刘伟、赵永省、夏鲁宁、李述胜、刘中、程科伟、浦雨三、张屹、张志磊、马洪富、袁中林、李智虎、焦靖伟、刘平、黄晶晶、谭武征、寇建波、颜海龙、刘献伦、刘为华、肖淑婷、张文科、杨倩媚、董亮亮、周蔚林、韩玮、高振鹏、胡建勋、刘冲、牟洁。I
1范围
网络安全技术证书应用综合服务接口规范本文件规定了面向证书应用的综合服务接口要求和定义，描述了相应验证方法。GB/T43694—2024
本文件适用于公钥密码基础设施应用技术体系下证书应用中间件和证书应用系统的开发，以及密码应用支撑平台的研制和检测。2规范性引用文件
下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单)适用于本文件。
GB/T20518
GB/T25061
GB/T35276
GB/T35291
GB/T36322
GB/T43578
信息安全技术
公钥基础设施数字证书格式
信息安全技术
XML数字签名语法与处理规范
信息安全技术
信息安全技术
信息安全技术
信息安全技术
信息安全技术
信息安全技术
信息安全技术
密码应用标识规范
SM2密码算法加密签名消息语法规范SM2密码算法使用规范
智能密码钥匙应用接口规范
密码设备应用接口规范
通用密码服务接口规范
0094一2020公钥密码应用技术体系框架规范GM/Z4001
3术语和定义
密码术语
25069、GM/Z4001界定的以及下列术语和定义适用于本文件。3.1
数字证书digital certificate
由CA签名的包含公开密钥拥有者信息、公开密钥、签发者信息、有效期以及扩展信息的一种数据结构。
注：数字证书也称公钥证书，按类别分为个人证书、机构证书和设备证书，按用途分为签名证书和加密证书［来源：GM/Z4001—2013,2.115]3.2
用户密钥userkey
存储在设备内部的用于应用密码运算的非对称密钥对。注：用户密钥包含签名密钥对和加密密钥对3.3
密钥容器keycontainer
密码设备中用于保存用户密钥的唯一性存储空间。GB/T43694—2024
4缩略语
下列缩略语适用于本文件。
B/S：浏览器/服务器(Browser/Server）CA：证书认证机构(CertificationAuthority)COM：组件对象模型(ComponentObjectModel)CRL：证书撤销列表(CertificateRevocationList）JAR:Java归档文件(JavaArchive)LDAP：轻量级目录访问协议(Lightweight DirectoryAccess Protocol)OID：对象标识符（ObjectIdentifier）XML：可扩展标记语言(ExtensibleMarkupLanguage)5证书应用综合服务接口
5.1证书应用综合服务接口在公钥密码应用技术体系框架中的位置公钥密码应用技术体系框架由应用层、典型密码应用支撑层、通用密码应用支撑层、基础设施安全支撑平台、密码设备服务层组成。证书应用综合服务接口属于通用密码应用支撑层，是中间件，为典型密码应用支撑层和应用层提供密码服务。其功能主要包括：负责完成与密码设备的安全连接；实现基于数字证书的身份认证，从证书中获取有关信息，实现授权管理、访问控制等安全机制；负责具体与密码设备交互实现具体的密码运算；将数据按照GB/T35275要求的格式进行封装，实现数据封装格式与应用系统无关性，实现应用系统互联互通和信息共享。证书应用综合服务接口规范在公钥密码应用技术框架内的位置应遵循GM/T0094一2020的第4章。5.2证书应用综合服务接口分类
证书应用综合服务接口包括客户端服务接口和服务器端服务接口两类。它位于典型密码应用支撑层和密码设备服务层之间，既可被典型密码应用支撑层调用也可被应用层直接调用，向上层提供证书信息解析、基于数字证书身份认证、信息的机密性、完整性和不可否认性等密码服务。5.3客户端服务接口
客户端服务接口采用支持多种编程语言的COM组件和客户端常使用的JavaScript脚本语言为例描述，其适用于客户端程序调用，接口的形态包括动态库、控件、插件、扩展等。客户端服务接口一般通过调用智能密码钥匙应用接口或通用密码服务接口来实现，此类接口应符合GB/T35291或GB/T43578中的规定，主要功能包括：配置管理、证书解析、签名与验证、加密与解密数字信封、XML数据签名与验证等。5.4服务器端服务接口
服务器端服务接口采用支持多种编程语言的COM组件和服务端常使用的Java语言为例描述，其适用于服务器端程序调用，接口的形态包括COM组件、JAR包等，支持主流操作系统。服务器端服务接口一般通过调用密码设备应用接口或通用密码服务接口来实现，此类接口应符合GB/T36322或GB/T43578中的规定，功能基本与客户端服务接口相对应，主要包括：配置管理、证书解析、签名与验证、加密与解密数字信封、XML数据签名与验证、时间戳等。2
6标识和数据结构
6.1标识定义
GB/T43694—2024
本文件所使用的常量、各类算法标识和证书解析标识应符合GB/T33560的规定。
6.2数据结构定义
本文件规定的接口处理的数据分为两种类型：数据类型A：是一种基于公钥的加密或签名结构，当公钥算法为RSA时，数据的结构参见PKCS#1v1.5；当公钥算法为SM2时，数据的结构应符合GB/T35276的规定。数据类型B：是一种基于证书的加密或签名结构，当证书的公钥算法为RSA时，消息的结构参见PKCS#7；当证书的公钥算法为SM2时，消息的结构应符合GB/T35275的规定。6.3数据格式要求
本文件所涉及的数字证书格式应符合GB/T20518的规定。本文件所描述的Base64编码格式参见RFC4648中Base64Encoding部分。在没有特殊说明的情况下，本文件中字符串采用UTF-8编码，其格式参见RFC3629。本文件所定义接口返回的错误码或抛出的异常信息应符合附录A，典型部署模型可参见附录B，集成示例可参见附录C
本文件以COM组件为例进行接口描述时，所用到的数据类型说明见表1。表1COM组件数据类型说明
字符串类型，不同的开发语言应采取对应的类型定义，如：char*、CString、java.lang.String等32位整数
16位整数
布尔类型，其取值范围是TRUE和FALSE，其中TRUE表示真值，FALSE表示假值长度等于0的字符串
长度大于0的字符串
7证书应用综合服务接口定义
7.1客户端COM组件接口
7.1.1客户端COM组件接口综述
客户端COM组件接口提供配置管理、证书解析、签名与验证、加密与解密数字信封、XML数据签名与验证等功能，共包含35个接口。客户端COM组件接口列表见附录D的表D.1，7.1.27.1.36给出了接口详细定义。
7.1.2获取接口版本信息
获取接口版本信息接口定义应符合表2的规定。3
T43694—2024
返回值
表2获取接口版本信息接口定义
BSTR SOF_GetVersionO
获取接口的版本号
接口版本号(成功）
空串（失败，可通过SOF_GetLastError获取符合表A.1定义的错误代码）设置签名算法
设置签名算法接口定义应符合表3的规定表3设置签名算法接口定义
返回值
LONG SOF_SetSignMethod(LONG SignMethod)设置接口在签名和验签运算时使用的签名算法SignMethod（签名算法标识，应符合GB/T33560的规定）SOR_OK（成功）
其他（失败，返回符合表A.1定义的错误代码）获得签名算法
获得签名算法接口定义应符合表4的规定。表4
返回值
LONG SOF_GetSignMethodObzxz.net
获得接口当前使用的签名算法
当前使用的签名算法标识（成功）0(当前没有设置签名算法)
设置加密算法
获得签名算法接口定义
设置加密算法接口定义应符合表5的规定设置加密算法接口定义
返回值
LONG SOF_SetEncryptMethod(LONG EncryptMethod)设置接口进行数据加密时使用的对称算法EncryptMethod（对称加密算法标识，应符合GB/T33560的规定，本接口可支持不带附加认证数据的加解密算法）
SOR_OK（成功）
其他（失败，返回表A.1定义的错误代码）7.1.6
获得加密算法
获得加密算法接口定义应符合表6的规定表6
返回值
LONG SOF_GetEncryptMethod O
获得加密算法接口定义
获得接口当前使用的对称加解密算法无
当前使用的加密算法标识（成功）0(当前没有设置加密算法）
获得证书列表
获得证书列表接口定义应符合表7的规定。表7
返回值
BSTR SOF_GetUserList ()
取得当前已安装证书的用户列表无
获得证书列表接口定义
43694—2024
证书列表［成功，返回证书列表字符串数据，格式为：用户名1IICertID18.&.＆.用户名2|ICertID2&.＆.&，根据证书应用的策略不同得到不同的证书列表返回值。在证书列表中，用户名代表证书的通用名(CommonName），CertID是证书唯一标识，其格式由实现者自定义，宜包含容器名、应用名、设备序列号等项。通过CertID应找到唯一的签名证书、加密证书，并使用对应的用户密钥」空串（失败或当前不存在证书用户列表，可通过SOF_GetLastError获取符合表A.1定义的错误代码）导出用户签名证书
导出用户签名证书接口定义应符合表8的规定。3导出用户签名证书接口定义
返回值
BSTR SOF_ExportUserCert (BSTR CertID)根据证书唯一标识，获取Base64编码的签名证书字符串CertID(证书唯一标识）
Base64编码的签名证书字符串（成功）空串（失败，可通过SOF_GetLastError获取符合表A.1定义的错误代码）7.1.9
证书登录
证书登录接口定义应符合表9的规定。GB/T
43694—2024
证书登录接口定义
BOOL SOF_Login(BSTR CertID, BSTR PassWd)校验证书口令，进行证书认证
CertID（证书唯一标识）
PassWd（证书口令）
返回值
安全规则
TRUE（成功）
FALSE（失败，可通过SOF_GetLastError获取符合表A.1定义的错误代码）证书登录成功后，表示该证书用户已拥有私钥使用权限，即登录状态。登录状态下，可正常调用签名、解密等需要私钥使用权限的接口，获得计算结果获取证书口令剩余重试次数
获取证书口令剩余重试次数接口定义应符合表10的规定。表10获取证书口令剩余重试次数接口定义原型
返回值
LONGSOF_GetPinRetryCount(BSTR CertID)获取证书口令的剩余重试次数
CertID(证书唯一标识）
剩余口令重试次数，当重试次数小于或等于0时表示证书口令已被锁定修改证书口令
修改证书口令接口定义应符合表11的规定。表11
返回值
修改证书口令接口定义
BOOL SOF_ChangePassWd(BSTR CertID,BSTR O1dPassWd,BSTR NewPassWd)修改设备的用户认证口令
CertID(证书唯一标识）
OldPassWd（旧证书口令）
NewPassWd（新证书口令）
TRUE（成功）
FALSE（失败，可通过SOFGetLastError获取符合表A.1定义的错误代码）导出用户加密证书
导出用户加密证书接口定义应符合表12的规定。6
返回值
导出用户加密证书接口定义
BSTR SOF_ExportExChangeUserCert (BSTR CertID)根据证书唯一标识，获取Base64编码的加密（交换）证书字符串CertID(证书唯一标识)
Base64编码的加密证书字符串（成功）空串（失败，可通过SOF_GetLastError获取符合表A.1定义的错误代码）获得证书信息
获得证书信息接口定义应符合表13的规定。表13
返回值
获得证书信息接口定义
BSTR SOF_GetCertInfo(BSTR Base64Cert, SHORT Type)获取证书内指定类型的信息
Base64Cert(Base64编码的证书字符串）Type（证书解析标识，应符合GB/T33560的规定）指定类型的证书信息(成功）
空串（失败或证书中不存在该项内容）获得证书扩展信息
获得证书扩展信息接口定义应符合表14的规定。表14获得证书扩展信息接口定义原型
返回值
BSTR SOF_GetCertlnfoByOid(BSTR Base64Cert, BSTR Oid)根据OID获取证书私有扩展项信息Base64Cert(Base64编码的证书字符串）Oid（私有扩展对象ID，如“1.2.156.xxx”）证书私有扩展项OID对应的信息（成功)空串(失败或证书中不存在该私有扩展项)获得设备信息
获得设备信息接口定义应符合表15的规定。43694—2024
小提示：此标准内容仅展示完整标准里的部分截取内容，若需要完整标准请到上方自行免费下载完整标准文档。