GB/T 43578-2023 信息安全技术 通用密码服务接口规范

　　ICS 35. 030 CCS L 80

　　中 华 人 民 共 和 国 国 家 标 准

　　GB/T 43578—2023

　　信息安全技术 通用密码服务接口规范

　　Information securitytechnology—Universalcryptography service

　　interfacespecification

　　2023-12-28发布 2024-07-01实施

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

　　

　　发

　　

　　布

　　GB/T 43578—2023

　　目 次

　　前言 Ⅲ

　　1 范围 1

　　2 规范性引用文件 1

　　3 术语和定义 1

　　4 缩略语 1

　　5 通用密码服务接口描述 2

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

　　5. 2 通用密码服务接口组成和功能说明 2

　　6 通用密码服务接口函数定义 3

　　6. 1 算法标识和数据结构 3

　　6. 2 环境类函数 5

　　6. 3 证书类函数 8

　　6. 4 密码运算类函数 18

　　6. 5 消息类函数 44

　　7 验证方法 56

　　7. 1 验证环境 56

　　7. 2 密码服务环境操作验证 56

　　7. 3 证书类函数功能验证 57

　　7. 4 签名验签验证 60

　　7. 5 摘要计算验证 63

　　7. 6 非对称加解密验证 64

　　7. 7 对称加解密验证 65

　　7. 8 生成密钥对验证 67

　　7. 9 PKCS#7运算验证 68

　　7. 10 SM2消息类运算验证 68

　　7. 11 Base64编码验证 69

　　附录 A (资料性) 通用密码服务接口函数汇总 71

　　附录 B (规范性) SM9密码算法数据结构和接口函数 74

　　附录 C (规范性) 通用密码服务接口错误代码定义 87

　　参考文献 89

　　Ⅰ

　　GB/T 43578—2023

　　前 言

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

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

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

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

　　本文件主要起草人 :赵松 、王 银 平 、程 磊 、夏 鲁 宁 、侯 鹏 亮 、李 述 胜 、刘 平 、李 智 虎 、黄 晶 晶 、程 科 伟 、浦雨三 、马洪富 、袁中林 、许涛 、王玉林 、焦靖伟 、韩玮 、谭武征 、高振鹏 、杜志强 、肖淑婷 、梁松涛 、刘为华 、王中武 、王晨光 、张文科 、董亮亮 、李根 、路晓明 、杨倩媚 、颜海龙 。

　　Ⅲ

　　GB/T 43578—2023

　　信息安全技术 通用密码服务接口规范

　　1 范围

　　本文件规定了通用密码服务接口的数据结构 、接口描述 、函数定义要求 ,描述了相应验证方法 。

　　本文件适用于公开密钥应用技术体系下密码应用服务的开发 ,密码应用支撑平台的研制及检测 ,密码设备的应用系统的开发 。

　　2 规范性引用文件

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

　　GB/T 20518 信息安全技术 公钥基础设施数字证书格式

　　GB/T 25069 信息安全技术 术语

　　GB/T 32918. 1 信息安全技术 SM2椭圆曲线公钥密码算法 第 1部分 :总则GB/T 33560 信息安全技术 密码应用标识规范

　　GB/T 35275 信息安全技术 SM2密码算法加密签名消息语法规范

　　GB/T 35276 信息安全技术 SM2密码算法使用规范

　　GB/T 35291 信息安全技术 智能密码钥匙应用接口规范GB/T 36322 信息安全技术 密码设备应用接口规范

　　GB/T 41389 信息安全技术 SM9密码算法使用规范GM/T 0094—2020 公钥密码应用技术体系框架规范GM/Z 4001 密码术语

　　PKCS#1 RSA密码编译标准(RSA Cryptography Standard)

　　PKCS#7 密码消息语法标准(Cryptographic Message Syntax Standard)

　　3 术语和定义

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

　　密钥容器 key container

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

　　4 缩略语

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

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

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

　　1

　　GB/T 43578—2023

　　CSP:加密服务提供者(Cryptographic Service Provider)

　　DER:可区分编码规则(Distinguished Encoding Rules)

　　ECB: 电子密码本(Electronic Code Book)

　　IV:初始化向量(initialization vector)

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

　　MAC:消息鉴别码(Message Authentication Code)

　　OCSP:在线证书状态协议(Online Certificate Status Protocol)

　　OID:对象标识符(ObjectIdentifier)

　　RSA:非对称加密算法(Rivest-Shamir-Adleman Algorithm)

　　5 通用密码服务接口描述

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

　　公钥密码应用技术体系框架由应用层 、典型密码应用支撑层 、通用密码应用支撑层 、基础设施安全支撑平台 、密码设备服务层组成 。通用密码服务接口属于通用密码应用支撑层中通用密码服务 , 向典型密码服务层和应用层提供证书解析 、证书认证 、信息的机密性 、完整性和不可否认性通用密码服务 ,将上层应用的密码服务请求转化为具体的基础密码操作请求 ,通过统一的密码设备应用接口调用相应的密码设备实现具体 的 密 码 运 算 和 密 钥 操 作 , 通 用 密 码 服 务 在 公 钥 密 码 应 用 技 术 框 架 内 的 位 置 应 遵 循GM/T 0094—2020的第 4章 。

　　5.2 通用密码服务接口组成和功能说明

　　5.2. 1 概述

　　通用密码服务接 口 由以下部分组成 :

　　a) 环境类函数 ;

　　b) 证书类函数 ;

　　c) 密码运算类函数 ;

　　d) 消息类函数 。

　　通用密码服务接口函数汇总信息详见附录 A。本文件中的相关接 口 ,均采用 C语言形式定义 ,作为参考 。

　　5.2.2 环境类函数

　　环境类函数负责创建和管理程序空间中所需的各种资源 、信号 ,并确保程序空间在应用程序运行期间不会被非法访问 ,造成信息泄露 。环境类函数负责完成与密码设备的安全连接 ,确保后续的操作是在安全的程序空间中进行 。环境类函数还负责在用户与密码设备之间创建和管理应用接口句柄 。可创建两种类型的应用接口句柄 ,一类是普通用户 ,该类型的应用接口句柄标识该用户是普通用户 , 只能访问密码设备中属于自己的信息和数据 ;另一类是管理员 ,该类型的应用接口句柄标识该用户是管理员 ,管理员可管理普通用户的应用接口句柄 。

　　应用程序在使用通用密码服务接口时 ,首先要调用初始化环境函数(SAF_Initialize)创建和初始化安全的程序空间 ,完成与密码设备连接和初始化工作 。应用程序在调用任何密码服务函数前应确保运行环境安全 ,可采用白名单机制或对接入设备进行认证的方式 ,进行任何私钥运算之前应首先调用用户

　　2

　　GB/T 43578—2023

　　登录函数(SAF_Login) ,创建应用接口句柄 。 当不再调用密码服务函数时 ,应调用注销登录函数(SAF_ Logout)注销安全访问令 牌 , 防 止 密 码 设 备 被 非 法 访 问 。 在 终 止 应 用 程 序 之 前 , 应 调 用 清 除 环 境 函 数(SAF_Finalize) , 中止与密码设备的连接 ,销毁所创建的安全的程序空间 , 防止由于内存残留所带来的安全风险 。

　　5.2.3 证书类函数

　　证书类函数负责将各类数字证书设置到应用接口会话环境中 , 实现证书获取 、CRL获取 、CA 根证书设置 、用户证书验证和用户证书信息获取功能 。应用程序通过调用证书类函数 ,实现基于数字证书的身份认证 、授权管理 、访问控制安全机制 。本文件中涉及的数字证书格式应符合 GB/T 20518的规定 。

　　5.2.4 密码运算类函数

　　密码运算类函数负责与密码设备交互并实现密码运算 ,并将密码运算后的结果返回给应用程序 ,是应用程序实现数据机密性 、完整性和不可否认性等安全机制的基础 。

　　密码运算类函数提供包括 Base64编解码 、随机数生成 、密码杂凑以及各种对称和非对称密码运算等 。密码运算函数支持定长数据和不定长数据的密码运算 ,对于定长数据可直接调用相关函数进行处理 ;对于不定长数据 ,需要先创建相应的密码运算对象 ,然后调用相应的函数对数据进行持续处理 。 当数据处理完时 ,要调用相应的函数表示数据处理完 ,最后要调用相应函数销毁相应的密码运算对象 。

　　5.2.5 消息类函数

　　消息类函数的功能是将数据按照数字信封格式进行封装 ,实现应用系统互联互通和信息共享 ,使用RSA算法时遵循 PKCS #7,使用国密算法时遵循 GB/T 35275。

　　消息类函数提供了数据编解码 、签名数据编解码和数字信封编解码 ,能够非常方便应用程序实现真实性 、机密性 、完整性和不可否认性等安全措施 。

　　6 通用密码服务接口函数定义

　　6. 1 算法标识和数据结构

　　6. 1. 1 算法标识与常量定义

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

　　6. 1.2 通用密码服务接口数据结构定义和说明

　　6. 1.2. 1 常量定义

　　数据常量标识定义了常量的取值 。

　　数据常量标识的定义符合表 1 的规定 。

　　表 1 常量定义

　　常量名

　　取值

　　描述

　　SGD_MAX_COUNT

　　64

　　枚举出的对象数量最大值

　　SGD_MAX_NAME_SIZE

　　256

　　证书某项信息的字符串长度最大值

　　3

　　GB/T 43578—2023

　　6. 1.2.2 用户证书列表

　　用户证书列表定义了用户证书传递结构 。

　　用户证书列表定义符合表 2 的规定 。

　　表 2 用户证书列表

　　字段名称

　　含义

　　certCount

　　证书总数

　　Certificate

　　DER编码的数字证书

　　certificateLen

　　数字证书的长度

　　containerName

　　密钥容器名称

　　containerNameLen

　　密钥容器名称的长度

　　keyUsage

　　密钥用途

　　C语言的数据结构定义 :

　　typedef structSGD_USR_CERT_ENUMLIST_ {

　　unsigned intcertCount;

　　unsigned char * certificate[SGD_MAX_COUNT] ;

　　unsigned intcertificateLen[SGD_MAX_COUNT] ;

　　unsigned char * containerName[SGD_MAX_COUNT] ; unsigned intcontainerNameLen[SGD_MAX_COUNT] ;

　　unsigned intkeyUsage[SGD_MAX_COUNT] ; } SGD_USR_CERT_ENUMLIST;

　　6. 1.2.3 密钥容器信息列表

　　密钥容器信息列表定义了密钥容器信息 。

　　密钥容器信息列表定义符合表 3 的规定 。

　　表 3 密钥容器信息列表

　　字段名称

　　含义

　　keyPairCount

　　密钥容器信息总数

　　containerName

　　密钥容器名称

　　containerNameLen

　　密钥容器名称的长度

　　keyUsage

　　密钥用途 ,1:加密 ;2:签名 ;3:密钥交换

　　keyType

　　密钥类型 ,1:SM2;2:RSA1024(存在安全风险) ;3:RSA2048;4:RSA3072;5:RSA4096; 6:SM9 (SM9密码算法定义应符合附录 B 的规定)

　　C语言的数据结构定义 :

　　typedef structSGD_ KEYCONTAINERINFO_ENUMLIST_ { unsigned intkeyPairCount;

　　4

　　GB/T 43578—2023

　　unsigned char * containerName[SGD_MAX_COUNT] ;

　　unsigned intcontainerNameLen[SGD_MAX_COUNT] ;

　　unsigned intkeyUsage[SGD_MAX_COUNT] ;

　　unsigned intkeyType[SGD_MAX_COUNT] ; } SGD_ KEYCONTAINERINFO_ENUMLIST;

　　6.2 环境类函数

　　6.2. 1 概述

　　环境类函数负责创建和管理程序空间中所需的各种资源 、信号 ,并确保程序空间在应用程序运行期间不会被非法访问 ,造成信息泄露 。

　　6.2.2 初始化环境

　　初始化环境函数定义应符合表 4 的规定 。

　　表 4 初始化环境函数定义

　　原型

　　intSAF_Initialize(void * * phAppHandle,unsigned char* pucCfgFilePath)

　　描述

　　初始化密码服务程序空间

　　参数

　　phAppHandle[in,out](输入并返回应用接口句柄)

　　pucCfgFilePath[in](配置文件全路径名 ,配置信息自定义 ,宜包括 :密码设备类型 、密码设备动态库名称 、设备的配置文件 、应用策略等)

　　返回值

　　0(成功)

　　非 0(失败 ,返回附录 C 中表 C. 1定义的错误代码 ,应符合附录 C 的规定)

　　6.2.3 清除环境

　　清除环境函数定义应符合表 5 的规定 。

　　表 5 清除环境函数定义

　　原型

　　intSAF_Finalize(void * hAppHandle)

　　描述

　　清除应用程序空间

　　参数

　　hAppHandle[in](应用接口句柄)

　　返回值

　　0(成功)

　　非 0(失败 ,返回表 C. 1定义的错误代码 ,应符合附录 C 的规定)

　　6.2.4 获取接口版本信息

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

　　5

　　GB/T 43578—2023

　　表 6 获取接口版本信息函数定义

　　原型

　　intSAF_GetVersion(unsigned int * puiVersion)

　　描述

　　取接口对应标准的版本号

　　参数

　　puiVersion[out](版本号)

　　返回值

　　0(成功)

　　非 0(失败 ,返回表 C. 1定义的错误代码 ,应符合附录 C 的规定)

　　备注

　　版本号的格式为 0xAABBCCCC,其中 AA为主版本号 ,BB为次版本号 ,CCCC为修改号

　　6.2.5 用户登录

　　用户登录函数定义应符合表 7 的规定 。

　　表 7 用户登录函数定义

　　原型

　　intSAF_Login (

　　void * hAppHandle,

　　unsigned intuiUsrType,

　　unsigned char * pucContainerName, unsigned intuiContainerNameLen,

　　unsigned char * pucPin,

　　unsigned intuiPinLen,

　　unsigned int * puiRemainCount)

　　描述

　　用户登录密码设备 ,建立安全令牌

　　参数

　　hAppHandle[in](应用接口句柄)

　　uiUsrType[in](用户类型 , 当为 0 时表示管理员登录 ,为 1 时表示用户登录)

　　pucContainerName[in][密钥容器名(或多个参数的拼接值 ,多个参数时用 # # #拼接) 或密钥检索号]

　　uiContainerNameLen[in](密钥容器名或密钥检索号的长度)

　　pucPin[in](设备口令)

　　uiPinLen[in](设备口令长度)

　　puiRemainCount[out](口令剩余重试次数)

　　返回值

　　0(成功)

　　非 0(失败 ,返回表 C. 1定义的错误代码 ,应符合附录 C 的规定)

　　规则

　　在服务器端使用加密机或加密卡时 ,加 密 机 或 加 密 卡 应 遵 循 GB/T 36322或 GB/T 35291,对 遵 循GB/T 35291的设备 ,pucContainerName用于标识指定的密钥容器名或多个参数的拼接值 ,对遵循

　　GB/T 36322的设备 ,pucContainerName用于标识密码设备内部的密钥位置

　　6.2.6 修改口令

　　修改口令函数定义应符合表 8 的规定 。

　　6

　　GB/T 43578—2023

　　表 8 修改口令函数定义

　　原型

　　intSAF_ChangePin (

　　void * hAppHandle,

　　unsigned intuiUsrType,

　　unsigned char * pucContainerName, unsigned intuiContainerNameLen,

　　unsigned char * pucOldPin,

　　unsigned intuiOldPinLen,

　　unsigned char * pucNewPin,

　　unsigned intuiNewPinLen,

　　unsigned int * puiRemainCount)

　　描述

　　修改设备口令 ,本函数仅适用于遵循 GB/T 35291的客户端密码设备

　　参数

　　hAppHandle[in](应用接口句柄)

　　uiUsrType[in](用户类型 , 当为 0 时表示管理员登录 ,为 1 时表示用户登录)

　　pucContainerName[in](密钥容器名或密钥检索号)

　　uiContainerNameLen[in](密钥容器名或密钥检索号的长度)

　　pucOldPin[in](设备当前口令)

　　uiOldPinLen[in](设备当前口令长度)

　　pucNewPin[in](设备新口令)

　　uiNewPinLen[in](设备新口令长度)

　　puiRemainCount[out](口令剩余重试次数)

　　返回值

　　0(成功)

　　非 0(失败 ,返回表 C. 1定义的错误代码 ,应符合附录 C 的规定)

　　6.2.7 注销登录

　　注销登录函数定义应符合表 9 的规定 。

　　表 9 注销登录函数定义

　　原型

　　intSAF_Logout(

　　void * hAppHandle,

　　unsigned intuiUsrType)

　　描述

　　设备注销登录

　　参数

　　hAppHandle[in](应用接口句柄)

　　uiUsrType[in](用户类型 , 当为 0 时表示管理员登录 ,为 1 时表示用户登录)

　　返回值

　　0(成功)

　　非 0(失败 ,返回表 C. 1定义的错误代码 ,应符合附录 C 的规定)

　　7

　　GB/T 43578—2023

　　6.3 证书类函数

　　6.3. 1 概述

　　证书类函数设置各类数字证书到应用接口会话环境中 、验证用户证书和获取数字证书或 CRL, 提供包括证书获取 、CRL获取 、CA根证书设置 、用户证书验证和用户证书信息获取等一系列具体函数 。

　　6.3.2 添加根 CA证书

　　添加根 CA证书函数定义应符合表 10的规定 。

　　表 10 添加根 CA证书函数定义

　　原型

　　intSAF_AddTrustedRootCaCertificate(

　　void * hAppHandle,

　　unsigned char * pucCertificate,

　　unsigned intuiCertificateLen,

　　unsigned intuiIndex)

　　描述

　　添加信任的 CA根证书

　　参数

　　hAppHandle[in](应用接口句柄)

　　pucCertificate[in](DER编码的证书)

　　uiCertificateLen[in](证书长度)

　　uiIndex[out](CA根证书索引)