跳到主要内容

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

返回主题目录 · 官方来源

来源：GB/T 43578-2023 国家标准详情。 PDF SHA-256：f1b26ab457a36806ad60060399edf7b7aab76e9fecf9c75fb084b08ebc537d5f。 依据官方 PDF 页面图像逐页核对转写；已合并跨页内容并去除页码。原文中函数原型、参数说明及结构体之间存在的不一致按原页保留。

前言​

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

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

本文件由全国信息安全标准化技术委员会（SAC/TC 260）提出并归口。

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

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

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
CSP加密服务提供者Cryptographic Service Provider
DER可区分编码规则Distinguished Encoding Rules
ECB电子密码本Electronic Code Book
IV初始化向量initialization vector
LDAP轻量级目录访问协议Lightweight Directory Access Protocol
MAC消息鉴别码Message Authentication Code
OCSP在线证书状态协议Online Certificate Status Protocol
OID对象标识符Object Identifier
RSA非对称加密算法Rivest-Shamir-Adleman Algorithm

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

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

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

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

5.2.1 概述​

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

  1. a） 环境类函数；
  2. b） 证书类函数；
  3. c） 密码运算类函数；
  4. d） 消息类函数。

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

5.2.2 环境类函数​

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

应用程序在使用通用密码服务接口时，首先要调用初始化环境函数（SAF_Initialize）创建和初始化安全的程序空间，完成与密码设备连接和初始化工作。应用程序在调用任何密码服务函数前应确保运行环境安全，可采用白名单机制或对接入设备进行认证的方式，进行任何私钥运算之前应首先调用用户登录函数（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_COUNT64枚举出的对象数量最大值
SGD_MAX_NAME_SIZE256证书某项信息的字符串长度最大值
6.1.2.2 用户证书列表​

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

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

表2 用户证书列表

字段名称含义
certCount证书总数
CertificateDER 编码的数字证书
certificateLen数字证书的长度
containerName密钥容器名称
containerNameLen密钥容器名称的长度
keyUsage密钥用途

C 语言的数据结构定义：

typedef struct SGD_USR_CERT_ENUMLIST_ {
    unsigned int certCount;
    unsigned char * certificate[SGD_MAX_COUNT];
    unsigned int certificateLen[SGD_MAX_COUNT];
    unsigned char * containerName[SGD_MAX_COUNT];
    unsigned int containerNameLen[SGD_MAX_COUNT];
    unsigned int keyUsage[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 struct SGD_KEYCONTAINERINFO_ENUMLIST_ {
    unsigned int keyPairCount;
    unsigned char * containerName[SGD_MAX_COUNT];
    unsigned int containerNameLen[SGD_MAX_COUNT];
    unsigned int keyUsage[SGD_MAX_COUNT];
    unsigned int keyType[SGD_MAX_COUNT];
} SGD_KEYCONTAINERINFO_ENUMLIST;

6.2 环境类函数​

6.2.1 概述​

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

6.2.2 初始化环境​

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

表4 初始化环境函数定义

项目内容
原型int SAF_Initialize(void * * phAppHandle, unsigned char * pucCfgFilePath)
描述初始化密码服务程序空间
参数phAppHandle［in,out］（输入并返回应用接口句柄）
pucCfgFilePath［in］（配置文件全路径名，配置信息自定义，宜包括：密码设备类型、密码设备动态库名称、设备的配置文件、应用策略等）
返回值0（成功）
非0（失败，返回附录C中表C.1定义的错误代码，应符合附录C的规定）

6.2.3 清除环境​

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

表5 清除环境函数定义

项目内容
原型int SAF_Finalize(void * hAppHandle)
描述清除应用程序空间
参数hAppHandle［in］（应用接口句柄）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.2.4 获取接口版本信息​

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

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

项目内容
原型int SAF_GetVersion(unsigned int * puiVersion)
描述取接口对应标准的版本号
参数puiVersion［out］（版本号）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
备注版本号的格式为 0xAABBCCCC，其中 AA为主版本号，BB 为次版本号，CCCC 为修改号

6.2.5 用户登录​

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

表7 用户登录函数定义

项目内容
原型int SAF_Login(void * hAppHandle,unsigned int uiUsrType,unsigned char * pucContainerName,unsigned int uiContainerNameLen,unsigned char * pucPin,unsigned int uiPinLen,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的规定。

表8 修改口令函数定义

项目内容
原型int SAF_ChangePin(void * hAppHandle,unsigned int uiUsrType,unsigned char * pucContainerName,unsigned int uiContainerNameLen,unsigned char * pucOldPin,unsigned int uiOldPinLen,unsigned char * pucNewPin,unsigned int uiNewPinLen,unsigned int * puiRemainCount)
描述修改设备口令，本函数仅适用于遵循GB/T35291的客户端密码设备
参数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 注销登录函数定义

项目内容
原型int SAF_Logout(void *hAppHandle,unsigned int uiUsrType)
描述设备注销登录
参数hAppHandle［in］（应用接口句柄）
uiUsrType［in］（用户类型，当为0时表示管理员登录，为1时表示用户登录）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.3 证书类函数​

6.3.1 概述​

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

6.3.2 添加根CA证书​

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

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

项目内容
原型int SAF_AddTrustedRootCaCertificate(void * hAppHandle,unsigned char * pucCertificate,unsigned int uiCertificateLen,unsigned int uiIndex)
描述添加信任的CA 根证书
参数hAppHandle［in］（应用接口句柄）
pucCertificate［in］（DER 编码的证书）
uiCertificateLen［in］（证书长度）
uiIndex［out］（CA 根证书索引）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
备注本函数仅限于管理员使用

6.3.3 获取根CA 证书个数​

获取根CA证书个数函数定义应符合表11的规定。

表11 获取根CA证书个数函数定义

项目内容
原型int SAF_GetRootCaCertificateCount(void * hAppHandle,unsigned int * puiCount)
描述获取信任根 CA证书的个数
参数hAppHandle［in］（应用接口句柄）
puiCount［out］（信任根CA证书个数）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.3.4 获取根 CA证书​

获取根CA证书函数定义应符合表12的规定。

表12 获取根 CA证书函数定义

项目内容
原型int SAF_GetRootCaCertificate(void *hAppHandle,unsigned int uiIndex,unsigned char * pucCertificate,unsigned int * puiCertificateLen)
描述获取指定位置 CA根证书
参数hAppHandle［in］（应用接口句柄）
uiIndex［in］（根证书索引）
pucCertificate［out］（DER 编码的证书）
puiCertificateLen［in,out］（证书长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.3.5 删除根 CA证书​

删除根 CA 证书函数定义应符合表13的规定。

表13 删除根 CA证书函数定义

项目内容
原型int SAF_RemoveRootCaCertificate(void * hAppHandle,unsigned int uiIndex)
描述删除指定位置 CA根证书
参数hAppHandle［in］（应用接口句柄）
uiIndex［in］（根证书索引）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
备注本函数仅限于管理员使用

6.3.6 添加 CA证书​

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

表14 添加 CA证书函数定义

项目内容
原型int SAF_AddCaCertificate(void *hAppHandle,unsigned char * pucCertificate,unsigned int uiCertificateLen,unsigned int uiIndex)
描述添加 CA 证书
参数hAppHandle［in］（应用接口句柄）
pucCertificate［in］（DER 编码的证书）
uiCertificateLen［in］（证书长度）
uiIndex［out］（CA证书索引）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
备注本函数仅限于管理员使用

6.3.7 获取 CA证书个数​

获取 CA证书个数函数定义应符合表15 的规定。

表15 获取 CA证书个数函数定义

项目内容
原型int SAF_GetCaCertificateCount(void * hAppHandle,unsigned int * puiCount)
描述获取信任 CA 证书的个数
参数hAppHandle［in］（应用接口句柄）
puiCount［out］（信任CA证书个数）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.3.8 获取 CA证书​

获取 CA证书函数定义应符合表16 的规定。

表16 获取 CA证书函数定义

项目内容
原型int SAF_GetCaCertificate(void * hAppHandle,unsigned int uiIndex,unsigned char * pucCertificate,unsigned int * puiCertificateLen)
描述获取指定位置 CA证书
参数hAppHandle［in］（应用接口句柄）
uiIndex［in］（CA证书索引）
pucCertificate［out］（DER 编码的证书）
puiCertificateLen［in,out］（证书长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.3.9 删除CA 证书​

删除CA证书函数定义应符合表17的规定。

表17 删除 CA 证书函数定义

项目内容
原型int SAF_RemoveCaCertificate(void * hAppHandle,unsigned int uiIndex)
描述删除指定位置 CA证书
参数hAppHandle［in］（应用接口句柄）
uiIndex［in］（证书位置索引）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
备注本函数仅限于管理员使用

6.3.10 添加 CRL​

添加 CRL 函数定义应符合表18的规定。

表18 添加 CRL 函数定义

项目内容
原型int SAF_AddCrl(void * hAppHandle,unsigned char * pucDerCrl,unsigned int uiDerCrlLen)
描述添加 CRL
参数hAppHandle［in］（应用接口句柄）
pucDerCrl［in］（DER 编码的 CRL）
uiDerCrlLen［in］（DER 编码 CRL 的长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
备注本函数仅限于管理员使用

6.3.11 验证用户证书​

验证用户证书函数定义应符合表19的规定。

表 19 验证用户证书函数定义

项目内容
原型int SAF_VerifyCertificate(void * hAppHandle,unsigned char * pucUsrCertificate,unsigned int uiUsrCertificateLen)
描述验证用户证书的有效性，包括验证有效期、证书信任列表、吊销状态等
参数hAppHandle［in］（应用接口句柄）
pucUsrCertificate［in］（DER 编码的证书）
uiUsrCertificateLen［in］（证书长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.3.12 根据 CRL 文件获取用户证书注销状态​

根据 CRL 文件获取用户证书注销状态函数定义应符合表20的规定。

表20 根据CRL 文件获取用户证书注销状态函数定义

项目内容
原型int SAF_VerifyCertificateByCrl(void * hAppHandle,unsigned char * pucUsrCertificate,unsigned int uiUsrCertificateLen,unsigned char * pucDerCrl,unsigned int uiDerCrlLen,unsigned char * pucRevokeDate)
描述根据 CRL 文件验证用户证书是否被注销
参数hAppHandle［in］（应用接口句柄）
pucUsrCertificate［in］（DER 编码的证书）
uiUsrCertificateLen［in］（证书长度）
pucDerCrl［in］（DER 编码的CRL）
uiDerCrlLen［in］（CRL 长度）
pucRevokeDate［out］（若证书有效此参数不返回，若证书被注销，则返回注销日期，格式为 YYYY-MM-DD HH:MM:SS）
返回值0（成功）
非0（失败，返回附录C.1的错误代码，应符合附录C的规定）

6.3.13 根据OCSP 获取用户证书注销状态​

根据OCSP 获取用户证书注销状态函数定义应符合表21 的规定。

表21 根据OCSP 获取用户证书注销状态函数定义

项目内容
原型int SAF_GetCertificateStateByOCSP(void * hAppHandle,unsigned char * pucOcspHostURL,unsigned int uiOcspHostURLLen,unsigned char * pucUsrCertificate,unsigned int uiUsrCertificateLen,unsigned char * pucCACertificate,unsigned int uiCACertificateLen,unsigned char * pucRevokeDate)
描述从 OCSP 获取用户证书的实时状态
参数hAppHandle［in］（应用接口句柄）
pucOcspHostURL［in］（OCSP 服务的 URL）
uiOcspHostURLLen［in］（URL 长度）
pucUsrCertificate［in］（DER 编码证书）
uiUsrCertificateLen［in］（证书长度）
pucCACertificate［in］（DER 编码颁发者证书）
uiCACertificateLen［in］（颁发者证书长度）
pucRevokeDate［out］（若证书有效此参数不返回，若证书被吊销，则返回吊销日期，格式为 YYYY-MM-DD HH:MM:SS）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.3.14 通过LDAP 方式获取证书​

通过 LDAP方式获取证书函数定义应符合表22 的规定。

表22 通过 LDAP 方式获取证书函数定义

项目内容
原型int SAF_GetCertFromLdap(void * hAppHandle, char * pcLdapHostURL, unsigned int uiLdapHostURLLen, unsigned char * pucQueryDN, unsigned int uiQueryDNLen, unsigned char * pucOutCert, unsigned int * puiOutCertLen)
描述通过 LDAP 方式获取证书
参数hAppHandle［in］（应用接口句柄）
pcLdapHostURL［in］（LDAP 服务器 IP 地址）
uiLdapHostURLLen［in］（LDAP 服务器端口）
pucQueryDN［in］（需要查找的证书的查询条件）
uiQueryDNLen［in］（查询条件长度）
pucOutCert［out］（查询到的 Base64 编码的证书，如查询出多证书，则证书信息中间以“&”分割）
puiOutCertLen［in,out］（找到的证书长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.3.15 通过LDAP方式获取证书对应的CRL​

通过 LDAP 方式获取证书对应的 CRL 函数定义应符合表 23 的规定。

表23 通过 LDAP 方式获取证书对应的 CRL 函数定义

项目内容
原型int SAF_GetCrlFromLdap(void * hAppHandle, char * pcLdapHostURL, unsigned int uiLdapHostURLLen, unsigned char * pucCertificate, unsigned int uiCertificateLen, unsigned char * pucCrlData, unsigned int * puiCrlDataLen)
描述通过 LDAP 方式根据证书获取对应的 CRL
参数hAppHandle［in］（应用接口句柄）
pcLdapHostURL［in］（LDAP 服务 URL）
uiLdapHostURLLen［in］（URL 长度）
pucCertificate［in］（DER 编码的数字证书）
uiCertificateLen［in］（证书长度）
pucCrlData［out］（获取的 DER 编码的 CRL 文件）
puiCrlDataLen［in,out］（CRL 文件长度）
返回值0（成功）
非0（失败，返回表 C.1 定义的错误代码，应符合附录 C 的规定）

6.3.16 获取证书信息​

获取证书信息函数定义应符合表24的规定。

表24 获取证书信息函数定义

项目内容
原型int SAF_GetCertificateInfo(void * hAppHandle,unsigned char * pucCertificate,unsigned int uiCertificateLen,unsigned int uiInfoType,unsigned char * pucInfo,unsigned int * puiInfoLen)
描述解析证书，获取证书中的信息
参数hAppHandle［in］（应用接口句柄）
pucCertificate［in］（DER 编码的证书）
uiCertificateLen［in］（证书长度）
uiInfoType［in］（指定的证书解析标识，应符合GB/T 33560 的规定）
pucInfo［out］（获取的证书信息）
puiInfoLen［in,out］（获取的证书信息长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.3.17 获取证书扩展信息​

获取证书扩展信息函数定义应符合表25 的规定。

表25 获取证书扩展信息函数定义

项目内容
原型int SAF_GetExtTypeInfo(void * hAppHandle,unsigned char * pucDerCert,unsigned int uiDerCertLen,unsigned int uiInfoType,unsigned char * pucPriOid,unsigned int uiPriOidLen,unsigned char * pucInfo,unsigned int * puiInfoLen)
描述获取证书的扩展信息
参数hAppHandle［in］（应用接口句柄）
pucDerCert［in］（DER 格式的数字证书）
uiDerCertLen［in］（数字证书长度）
uiInfoType［in］（指定的证书扩展项解析标识，应符合GB/T 33560 的规定）
pucPriOid［in］（扩展项的OID，如果不是私有扩展项类型，该参数无效）
uiPriOidLen［in］（扩展项 OID 长度，如果不是私有扩展项类型，该参数无效）
pucInfo［out］（获取的证书信息）
puiInfoLen［in,out］（获取的证书信息长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.3.18 列举用户证书​

列举用户证书函数定义应符合表26 的规定。

表26 列举用户证书函数定义

项目内容
原型int SAF_EnumCertificates(void *hAppHandle,SGD_USR_CERT_ENUMLIST * usrCerts)
描述列举出插入当前计算机的所有密码设备内的有效证书
参数hAppHandle［in］（应用接口句柄）
usrCerts［out］（返回的用户证书列表）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
备注usrCerts 结构内的对象数据由本函数分配空间。本函数用于客户端枚举证书

6.3.19 列举用户的密钥容器信息​

列举用户的密钥容器信息函数定义应符合表27 的规定。

表27 列举用户的密钥容器信息函数定义

项目内容
原型Int SAF_EnumKeyContainerInfo(void *hAppHandle,SGD_KEYCONTAINERINFO_ENUMLIST * keyContainerInfo)
描述列举插入当前计算机的所有密码设备的密钥容器信息
参数hAppHandle［in］（应用接口句柄）
keyContainerInfo［out］（返回的密钥容器信息）
返回值SAR_OK（成功）
其他（失败）
备注keyContainerInfo 结构内的对象数据由本函数分配空间。仅在客户端使用

6.3.20 释放列举用户证书的内存​

释放列举用户证书的内存函数定义应符合表28的规定。

表28 释放列举用户证书的内存函数定义

项目内容
原型int SAF_EnumCertificatesFree(void * hAppHandle,SGD_USR_CERT_ENUMLIST * usrCerts)
描述释放 SAF_EnumCertificates 函数中分配的内存
参数hAppHandle［in］（应用接口句柄）
usrCerts［in］（证书信息）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.3.21 释放列举密钥容器信息的内存​

释放列举密钥容器信息的内存函数定义应符合表29的规定。

表29 释放列举密钥容器信息的内存函数定义

项目内容
原型int SAF_EnumkeyContainerInfoFree(void * hAppHandle,SGD_KEYCONTAINERINFO_ENUMLIST * keyContainerInfo)
描述释放 SAF_EnumKeyContainerInfo 函数中分配的内存
参数hAppHandle［in］（应用接口句柄）
keyContainerInfo［in］（密钥容器信息）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4 密码运算类函数​

6.4.1 概述​

密码运算类函数通过与密码设备交互实现具体的密码运算，并将密码运算后的结果返回给应用程序，是应用程序实现数据保密性、完整性和不可抵赖性等安全机制的基础。

6.4.2 单块 Base64 编码​

单块 Base64编码函数定义应符合表30的规定。

表30 单块 Base64 编码函数定义

项目内容
原型int SAF_Base64_Encode(unsigned char * pucInData,unsigned int uiInDataLen,unsigned char * pucOutData,unsigned int * puiOutDataLen)
描述对输入的数据进行 Base64 编码，编码格式参考 IETF RFC4648
参数pucInData［in］（编码前的数据）
uiInDataLen［in］（编码前的数据长度）
pucOutData［out］（编码后的数据）
puiOutDataLen［in,out］（编码后的数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.3 单块 Base64 解码​

单块 Base64 解码函数定义应符合表31 的规定。

表31 单块 Base64 解码函数定义

项目内容
原型int SAF_Base64_Decode(unsigned char * pucInData,unsigned int uiInDataLen,unsigned char * pucOutData,unsigned int * puiOutDataLen)
描述对输入的数据进行 Base64 解码，编码格式参考 IETF RFC4648
参数pucInData［in］（解码前的数据）
uiInDataLen［in］（解码前的数据长度）
pucOutData［out］（解码后的数据）
puiOutDataLen［in,out］（解码后的数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.4 创建 Base64 对象​

创建 Base64 对象函数定义应符合表32的规定。

表32 创建 Base64 对象函数定义

项目内容
原型int SAF_Base64_CreateBase64Obj(void * hAppHandle,void * * phBase64Obj)
描述为任意长度数据的 Base64 编解码创建 Base64 对象，编码格式参考 IETF RFC4648
参数hAppHandle［in］（应用句柄）
phBase64Obj［out］（指向创建的 Base64 对象句柄的指针）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
备注本函数与 SAF_Base64_DestroyBase64Obj，SAF_Base64_EncodeUpdate，SGD_Base64_EncodeFinal，SAF_Base64_DecodeUpdate，SAF_Base64_DecodeFinal 等函数共同使用以支持任意长度数据的 Base64 编解码

6.4.5 销毁 Base64 对象​

销毁 Base64 对象函数定义应符合表33的规定。

表33 销毁 Base64 对象函数定义

项目内容
原型int SAF_Base64_DestroyBase64Obj(void * hAppHandle,void * hBase64Obj)
描述删除 Base64 对象
参数hAppHandle［in］（应用句柄）
hBase64Obj［in］（需要删除的 Base64 对象句柄）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.6 通过 Base64 对象多块编码​

通过 Base64 对象多块编码函数定义应符合表34的规定。

表34 通过 Base64 对象多块编码函数定义

项目内容
原型int SAF_Base64_EncodeUpdate(void *hBase64Obj,unsigned char * pucInData,unsigned int uiInDataLen,unsigned char * pucOutData,unsigned int * puiOutDataLen)
描述通过 Base64 对象对数据多块 Base64 编码，编码格式参考 IETF RFC4648
参数hBase64Obj［in］（Base64 对象）
pucInData［in］（编码前的数据）
uiInDataLen［in］（编码前的数据长度）
pucOutData［out］（编码后的数据）
puiOutDataLen［in,out］（返回编码后的数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
备注编码完成后，需调用 SAF_Base64_EncodeFinal

6.4.7 通过 Base64 对象编码结束​

通过 Base64 对象编码结束函数定义应符合表35的规定。

表35 通过 Base64 对象编码结束函数定义

项目内容
原型int SAF_Base64_EncodeFinal(void * hBase64Obj,unsigned char * pucOutData,unsigned int * puiOutDataLen)
描述通过 Base64 对象对数据编码结束，编码格式参考 IETF RFC4648
参数hBase64Obj［in］（Base64 对象）
pucOutData［out］（编码后的数据）
puiOutDataLen［in,out］（返回编码后的数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.8 通过 Base64 对象多块解码​

通过 Base64 对象多块解码函数定义应符合表36 的规定。

表36 通过 Base64 对象多块解码函数定义

项目内容
原型int SAF_Base64_DecodeUpdate(void *hBase64Obj,unsigned char * pucInData,unsigned int uiInDataLen,unsigned char * pucOutData,unsigned int * puiOutDataLen)
描述通过 Base64 对象对数据多块 Base64 解码，编码格式参考 IETF RFC4648
参数hBase64Obj［in］（Base64 对象）
pucInData［in］（解码前的数据）
uiInDataLen［in］（解码前的数据长度）
pucOutData［out］（解码后的数据）
puiOutDataLen［in,out］（返回解码后的数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
备注解码完成后，需调用 SAF_Base64_DecodeFinal 结束

6.4.9 通过 Base64 对象解码结束​

通过 Base64 对象解码结束函数定义应符合表37的规定。

表37 通过 Base64 对象解码结束函数定义

项目内容
原型int SAF_Base64_DecodeFinal(void * hBase64Obj,unsigned char* pucOutData,unsigned int * puiOutDataLen)
描述通过 Base64 对象对数据解码结束，编码格式参考 IETF RFC4648
参数hBase64Obj［in］（Base64 对象）
pucOutData［out］（解码后的数据）
puiOutDataLen［in,out］（返回解码后的数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.10 生成随机数​

生成随机数函数定义应符合表38的规定。

表38 生成随机数函数定义

项目内容
原型int SAF_GenRandom(void * hAppHandle,unsigned int uiRandLen,unsigned char * pucRand)
描述生成指定长度的随机数
参数hAppHandle［in］（应用句柄）
uiRandLen［in］（随机数长度）
pucRand［out］（指定长度的随机数，内存由外部调用者分配。）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.11 HASH 运算​

HASH运算函数定义应符合表39的规定。

表39 HASH 运算函数定义

项目内容
原型int SAF_Hash(void * hAppHandle,unsigned int uiAlgoType,unsigned char * pucInData,unsigned int uiInDataLen,unsigned char * pucPublicKey,unsigned int uiPublicKeyLen,unsigned char * pucID,unsigned int uiIDLen,unsigned char * pucOutData,unsigned int * puiOutDataLen)
描述HASH 运算，对给定长度数据的 HASH运算
参数hAppHandle［in］（应用句柄）
uiAlgoType［in］（HASH算法）
pucInData［in］（输入数据）
uiInDataLen［in］（输入数据长度）
pucPublicKey［in］（签名者公钥。当 uiAlgoType 为SGD_SM3 时有效）
uiPublicKeyLen［in］（签名者公钥长度）
pucID［in］（签名者的ID 值，当 uiAlgoType 为SGD_SM3时有效）
uiIDLen［in］（签名者ID 的长度，当 uiAlgoType 为SGD_SM3时有效）
pucOutData［out］（HASH）
puiOutDataLen［out］（HASH 长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
规则当 uiAlgoType 为SGD_SM3 且 uiIDLen 不为0的情况下 pucPublicKey、pucID 有效，执行SM2算法签名预处理1和预处理2操作。计算过程应按照 GB/T 35276的要求

6.4.12 创建 HASH 对象​

创建 HASH 对象函数定义应符合表40的规定。

表40 创建 HASH 对象函数定义

项目内容
原型int SAF_CreateHashObj(void * hAppHandle,void * * phHashObj,unsigned int uiAlgorithmType unsigned char * pucPublicKey,unsigned int uiPublicKeyLen,unsigned char * pucID unsigned int uiIDLen)
描述创建 HASH 对象，对任意长度数据的 HASH运算
参数hAppHandle［in］（应用句柄）
phHashObj［out］（创建的 HASH 对象）
uiAlgorithmType［in］（HASH 算法）
pucPublicKey［in］（签名者公钥。当 uiAlgoType 为SGD_SM3时有效）
uiPublicKeyLen［in］（签名者公钥长度）
pucID［in］（签名者的ID 值，当 uiAlgoType 为SGD_SM3 时有效）
uiIDLen［in］（签名者 ID 的长度，当 uiAlgoType 为 SGD_SM3 时有效）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
规则当 uiAlgoType 为SGD_SM3 且 uiIDLen 不为0的情况下 pucPublicKey、pucID 有效，执行SM2算法签名预处理1操作。计算过程应按照 GB/T 35276的要求

6.4.13 删除 HASH 对象​

删除HASH 对象函数定义应符合表41的规定。

表41 删除 HASH 对象函数定义

项目内容
原型int SAF_DestroyHashObj(void * hAppHandle,void * hHashObj)
描述删除 HASH 对象
参数hAppHandle［in］（应用句柄）
hHashObj［in］（需要删除的 HASH 对象）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.14 通过对象进行多块 HASH 运算​

通过对象进行多块 HASH运算函数定义应符合表42 的规定。

表42 通过对象进行多块 HASH运算函数定义

项目内容
原型int SAF_HashUpdate(void * hHashObj,unsigned char * pucInData,unsigned int uiInDataLen)
描述继续 HASH 运算
参数hHashObj［in］（HASH 对象）
pucInData［in］（输入数据）
uiInDataLen［in］（输入数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
备注运算完成后，需调用 SAF_HashFinal 结束

6.4.15 结束 HASH 运算​

结束 HASH运算函数定义应符合表43的规定。

表43 结束 HASH运算函数定义

项目内容
原型int SAF_HashFinal(void * hHashObj,unsigned char * pucOutData,unsigned int * puiOutDataLen)
描述结束 HASH 运算
参数hHashObj［in］（HASH 对象）
pucOutData［out］（输出的 HASH 值）
puiOutDataLen［out］（HASH 值的长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.16 生成 RSA密钥对​

生成 RSA 密钥对函数定义应符合表44 的规定。

表44 生成 RSA 密钥对函数定义

项目内容
原型int SAF_GenRsaKeyPair(void * hAppHandle,unsigned char * pucContainerName,unsigned int uiContainerNameLen,unsigned int uiKeyBits,unsigned int uiKeyUsage,unsigned int uiExportFlag)
描述产生指定名称的密钥容器并在该密钥容器内生成 RSA 密钥对
参数hAppHandle［in］（应用接口句柄）
pucContainerName［in］（密钥容器名）
uiContainerNameLen［in］（密钥容器名长度）
uiKeyBits［in］（密钥模长）
uiKeyUsage［in］（密钥用途）
SGD_KEYUSAGE_SIGN（表示签名）
SGD_KEYUSAGE_KEYEXCHANGE（表示密钥交换（加密））
uiExportFlag［in］（1 表示生成的密钥对可导出，0表示不应导出）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
备注如果指定的密钥容器名已存在，则在该密钥容器内增加或者替换密钥对

6.4.17 获取 RSA公钥​

获取 RSA公钥函数定义应符合表45 的规定。

表45 获取 RSA公钥函数定义

项目内容
原型int SAF_GetRsaPublicKey(void *hAppHandle,unsigned char * pucContainerName,unsigned int uiContainerLen,unsigned int uiKeyUsage,unsigned char * pucPublicKey,unsigned int * puiPublicKeyLen)
描述取出符合 PKCS #1的 RSA公钥
参数hAppHandle［in］（应用接口句柄）
pucContainerName［in］（密钥容器名或密码机的密码号）
uiContainerLen［in］（密钥容器名长度）
uiKeyUsage［in］（密0钥用途）
SGD_KEYUSAGE_SIGN（表示签名）
SGD_KEYUSAGE_KEYEXCHANGE（表示加密）
pucPublicKey［out］（输出的 DER格式的公钥数据）
puiPublicKeyLen［in,out］（输出公钥数据的长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.18 RSA 签名运算​

RSA 签名运算函数定义应符合表46 的规定。

表46 RSA 签名运算函数定义

项目内容
原型int SAF_RsaSign(void * hAppHandle,unsigned char * pucContainerName,unsigned int uiContainerNameLen,unsigned int uiHashAlgorithmID,unsigned char * pucInData,,unsigned int uiInDataLen,unsigned char * pucSignData,unsigned int * puiSignDataLen)
描述按照 PKCS #1 的要求对一定长度的字符串进行签名运算
参数hAppHandle［in］（应用接口句柄）
pucContainerName［in］（密钥容器名或密钥号）
uiContainerNameLen［in］（密钥容器名长度）
uiHashAlgorithmID［in］（HASH 算法）
pucInData［in］（签名原文）
uiInDataLen［in］（签名原文的长度）
pucSignData［out］（输出的 DER 格式签名结果数据）
puiSignDataLen［in,out］（输出的签名结果数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.19 对文件进行 RSA 签名运算​

对文件进行 RSA 签名运算函数定义应符合表47 的规定。

表47 对文件进行 RSA签名运算函数定义

项目内容
原型int SAF_RsaSignFile(void *hAppHandle,unsigned char * pucContainerName,unsigned int uiContainerNameLen,unsigned int uiHashAlgorithmID,unsigned char * pucFileName,unsigned char * pucSignData,unsigned int * puiSignDataLen)
描述按照 PKCS #1的要求对指定的文件进行签名运算
参数hAppHandle［in］（应用接口句柄）
pucContainerName［in］（密钥容器名）
uiContainerNameLen［in］（密钥容器名长度）
uiHashAlgorithmID［in］（HASH 算法）
pucFileName［in］（要签名的全路径文件名）
pucSignData［out］（输出的 DER 格式的签名结果数据）
puiSignDataLen［in,out］（输出的签名结果数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
备注此函数主要用于对附件的签名，也适用于对大文件的签名

6.4.20 RSA 验证签名运算​

RSA 验证签名运算函数定义应符合表48 的规定。

表48 RSA 验证签名运算函数定义

项目内容
原型int SAF_RsaVerifySign(void * hAppHandle,unsigned int uiHashAlgorithmID,unsigned char * pucPublicKey,unsigned int uiPublicKeyLen,unsigned char * pucInData,,unsigned int uiInDataLen,unsigned char * pucSignData,unsigned int uiSignDataLen)
描述符合 PKCS #1的验证签名运算
参数hAppHandle［in］（应用句柄）
uiHashAlgorithmID［in］（HASH 算法）
pucPublicKey［in］（DER 编码的公钥）
uiPublicKeyLen［in］（DER 编码的公钥长度）
pucInData［in］（签名原文）
uiInDataLen［in］（签名原文的长度）
pucSignData［in］（DER 编码的签名数据）
uiSignDataLen［in］（签名数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.21 对文件及其签名进行 RSA验证​

对文件及其签名进行 RSA 验证函数定义应符合表49的规定。

表49 对文件及其签名进行 RSA 验证函数定义

项目内容
原型int SAF_RsaVerifySignFile(void * hAppHandle,unsigned int uiHashAlgorithmID,unsigned char * pucPublicKey,unsigned int uiPublicKeyLen,unsigned char * pucFileName,unsigned char * pucSignData,unsigned int uiSignDataLen)
描述对文件及其签名值，进行符合 PKCS ＃1 的验证签名运算
参数hAppHandle［in］（应用句柄）
uiHashAlgorithmID［in］（HASH 算法）
pucPublicKey［in］（DER 编码的公钥）
uiPublicKeyLen［in］（DER 编码的公钥长度）
pucFileName［in］（需要验证签名的文件名）
pucSignData［in］（DER 编码的签名数据）
uiSignDataLen［in］（签名数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
备注本函数用于对附件的签名进行验证，也可对大文件的签名进行验证

6.4.22 基于证书的 RSA公钥验证​

基于证书的 RSA 公钥验证函数定义应符合表50的规定。

表50 基于证书的 RSA公钥验证函数定义

项目内容
原型int SAF_VerifySignByCert(void *hAppHandle,unsigned int uiHashAlgorithmID,unsigned char *pucCertificate,unsigned int uiCertificateLen,unsigned char * pucInData,unsigned int uiInDataLen,unsigned char * pucSignData,unsigned int uiSignDataLen)
描述按照 PKCS #1的要求使用数字证书对签名值进行验证
参数hAppHandle［in］（应用句柄）
uiHashAlgorithmID［in］（HASH算法标识）
pucCertificate［in］（DER 编码的数字证书）
uiCertificateLen［in］（DER 编码的数字证书长度）
pucInData［in］（签名原文）
uiInDataLen［in］（签名原文的长度）
pucSignData［in］（DER 编码签名数据）
uiSignDataLen［in］（签名数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.23 生成SM2密钥对​

生成SM2 密钥对函数定义应符合表51 的规定。

表51 生成SM2 密钥对函数定义

项目内容
原型int SAF_GenSm2KeyPair(void * hAppHandle,unsigned char * pucContainerName,unsigned int uiContainerLen,unsigned int uiKeyBits,unsigned int uiKeyUsage,unsigned int uiExportFlag)
描述生成指定名称的密钥容器，并在该密钥容器内生成 SM2密钥对
参数hAppHandle［in］（应用接口句柄）
pucContainerName［in］（密钥容器名）
uiContainerLen［in］（密钥容器名长度）
uiKeyBits［in］（密钥模长）
uiKeyUsage［in］（密钥用途）
SGD_SM2_1（表示椭圆曲线签名）
SGD_SM2_2（表示椭圆曲线密钥交换协议）
SGD_SM2_3（表示椭圆曲线加密）
uiExportFlag［in］（1 表示生成的密钥对可导出，0表示不应导出）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.24 获取 SM2公钥​

获取 SM2公钥函数定义应符合表52的规定。

表52 获取 SM2公钥函数定义

项目内容
原型int SAF_GetSm2PublicKey(void * hAppHandle,unsigned char * pucContainerName,unsigned int uiContainerLen,unsigned int uiKeyUsage,unsigned char * pucPublicKey,unsigned int * puiPublicKeyLen)
描述取出 Sm2 公钥
参数hAppHandle［in］（应用接口句柄）
pucContainerName［in］（密钥容器名）
uiContainerLen［in］（密钥容器名长度）
uiKeyUsage［in］（密钥用途）
SGD_SM2_1（表示签名公钥）
SGD_SM2_3（表示加密公钥）
pucPublicKey［out］（输出的 DER 编码的公钥数据）
puiPublicKeyLen［in,out］（输出公钥数据的长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.25 SM2签名​

SM2 签名函数定义应符合表53的规定。

表53 SM2 签名函数定义

项目内容
原型int SAF_Sm2Sign(void * hAppHandle,unsigned char * pucContainerName,unsigned int uiContainerNameLen,unsigned int uiAlgorithmID,unsigned char * pucInData,,unsigned int uiInDataLen,unsigned char * pucSignData,unsigned int * puiSignDataLen)
描述使用 SM2私钥对数据进行签名运算
参数hAppHandle［in］（应用接口句柄）
pucContainerName［in］（密钥容器名）
uiContainerNameLen［in］（密钥容器名长度）
uiAlgorithmID［in］（签名算法标识）
pucInData［in］（签名原文）
uiInDataLen［in］（签名原文的长度）
pucSignData［out］（输出的 DER 编码的签名数据）
puiSignDataLen［in,out］（输出的签名结果数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.26 SM2验证​

SM2 验证函数定义应符合表54的规定。

表 54 SM2 验证函数定义

项目内容
原型int SAF_Sm2VerifySign(void * hAppHandle,unsigned char * pucPublicKey,unsigned int uiPublicKeyLen,unsigned int uiAlgorithmID,unsigned char * pucInData,unsigned int uiInDataLen,unsigned char * pucSignData,unsigned int uiSignDataLen)
描述利用 SM2公钥验证签名
参数hAppHandle［in］（应用句柄）
pucPublicKey［in］（DER 编码的公钥）
uiPublicKeyLen［in］（公钥长度）
uiAlgorithmID［in］（SM2 签名算法）
pucInData［in］（待验证数据）
uiInDataLen［in］（待验证数据的长度）
pucSignData［in］（DER 编码的签名数据）
uiSignDataLen［in］（签名数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.27 SM2 公钥加密​

SM2 公钥加密函数定义应符合表55的规定。

表55 SM2 公钥加密函数定义

项目内容
原型int SAF_Sm2PublicKeyEnc(void * hAppHandle,unsigned char * pucPublicKey,unsigned int uiPublicKeyLen,unsigned int uiAlgorithmID,unsigned char * pucInData,unsigned int uiInDataLen,unsigned char * pucOutData,unsigned int * puiOutDataLen)
描述SM2公钥加密运算
参数hAppHandle［in］（应用句柄）
pucPublicKey［in］（DER 编码的公钥）
uiPublicKeyLen［in］（DER 编码的公钥长度）
uiAlgorithmID［in］（SM2算法标识）
pucInData［in］（输入数据）
uiInDataLen［in］（输入数据长度）
pucOutData［out］（输出数据，DER 编码）
puiOutDataLen［in,out］（输出数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.28 基于证书的SM2公钥加密​

基于证书的SM2公钥加密函数定义应符合表56 的规定。

表56 基于证书的SM2公钥加密函数定义

项目内容
原型int SAF_Sm2PublicKeyEncByCert(void *hAppHandle,unsigned char * pucCertificate,unsigned int uiCertificateLen,unsigned int uiAlgorithmID,unsigned char * pucInData,unsigned int uiInDataLen,unsigned char * pucOutData,unsigned int * puiOutDataLen)
描述基于证书的SM2公钥加密，证书为外部导入
参数hAppHandle［in］（应用句柄）
pucCertificate［in］（DER 编码的数字证书）
uiCertificateLen［in］（数字证书长度）
uiAlgorithmID［in］（SM2算法标识）
pucInData［in］（输入数据）
uiInDataLen［in］（输入数据长度）
pucOutData［out］（输出 DER 编码的数据）
puiOutDataLen［in,out］（输出数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.29 基于证书的SM2 公钥解密​

基于证书的SM2公钥解密函数定义应符合表57 的规定。

表57 基于证书的SM2公钥解密函数定义

项目内容
原型int SAF_Sm2PublicKeyDecByCert(void * hAppHandle,unsigned char * pucCertificate,unsigned int uiAlgorithmID,unsigned char * pucInData,unsigned int uiInDataLen,unsigned char * pucOutData,unsigned int * puiOutDataLen)
描述基于证书的 SM2公钥解密
参数hAppHandle［in］（应用句柄）
pucCertificate［in］（DER 编码的数字证书）
uiAlgorithmID［in］（SM2算法标识）
pucInData［in］（输入 DER编码密文，符合 GB/T 35276 中加密数据格式的定义）
uiInDataLen［in］（输入数据长度）
pucOutData［out］（输出明文）
puiOutDataLen［in,out］（输出数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.30 基于证书的SM2公钥验证​

基于证书的SM2公钥验证函数定义应符合表58的规定。

表58 基于证书的SM2公钥验证函数定义

项目内容
原型int SAF_Sm2VerifySignByCert(void * hAppHandle,unsigned int uiAlgorithmID,unsigned char *pucCertificate,unsigned int uiCertificateLen,unsigned char * pucInData,unsigned int uiInDataLen,unsigned char * pucSignData,unsigned int uiSignDataLen)
描述基于证书的 SM2公钥验证
参数hAppHandle［in］（应用句柄）
uiAlgorithmID［in］（SM2 签名算法标识）
pucCertificate［in］（DER 编码的数字证书）
uiCertificateLen［in］（数字证书长度）
pucInData［in］（待验证数据）
uiInDataLen［in］（待验证数据的长度）
pucSignData［in］（DER 编码的签名数据）
uiSignDataLen［in］（签名数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.31 创建对称算法对象​

创建对称算法对象函数定义应符合表59的规定。

表59 创建对称算法对象函数定义

项目内容
原型int SAF_CreateSymmAlgoObj(void * hAppHandle,void * * phSymmKeyObj,unsigned char * pucContainerName,unsigned int uiContainerLen,unsigned char * pucIV,unsigned int uiIVLen,unsigned int uiEncOrDec,unsigned int uiCryptoAlgID)
描述本地产生对称算法对象
参数hAppHandle［in］（应用接口句柄）
phSymmKeyObj［out］（返回的对称算法对象）
pucContainerName［in］（密钥容器名）
uiContainerLen［in］（密钥容器名长度）
pucIV［in］（初始向量，ECB模式时此参数忽略）
uiIVLen［in］（初始向量长度，ECB模式时此参数忽略）
uiEncOrDec［in］（1加密，0解密）
uiCryptoAlgID［in］（加密算法标识）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.32 生成会话密钥并用外部公钥加密输出​

生成会话密钥并用外部公钥加密输出函数定义应符合表60的规定。

表60 生成会话密钥并用外部公钥加密输出函数定义

项目内容
原型int SAF_GenerateKeyWithEPK(void * hSymmKeyObj,unsigned char * pucPublicKey,unsigned int uiPublicKeyLen,unsigned char * pucSymmKey,unsigned int uiSymmKeyLen,void * * phKeyHandle)
描述生成会话密钥并用外部公钥加密输出
参数hSymmKeyObj［in］（对称算法对象）
pucPublicKey［in］（输入的 DER 编码的公钥数据）
uiPublicKeyLen［in］（输入公钥数据的长度）
pucSymmKey［out］（输出的加密后的会话密钥）
uiSymmKeyLen［out］（输出的加密会话密钥长度）
phKeyHandle［out］（输出会话密钥的句柄）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.33 导入加密的会话密钥​

导入加密的会话密钥函数定义应符合表61 的规定。

表61 导入加密的会话密钥函数定义

项目内容
原型int SAF_ImportEncedKey(void*hSymmKeyObj,unsigned char * pucSymmKey,unsigned int uiSymmKeyLen,void* * phKeyHandle)
描述导入加密的会话密钥，使用指定的私钥解密，产生会话密钥句柄并输出
参数hSymmKeyObj［in］（对称算法对象）
pucSymmKey［in］（输入的加密后的会话密钥）
uiSymmKeyLen［in］（输入的加密会话密钥长度）
phKeyHandle［out］（输出会话密钥的句柄）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.34 生成密钥协商参数并输出​

生成密钥协商参数并输出函数定义应符合表62的规定。

表62 生成密钥协商参数并输出函数定义

项目内容
原型int SAF_GenerateAgreementDataWithSM2(void * hSymmKeyObj,unsigned int uiISKIndex,unsigned int uiKeyBits,unsigned char * pucSponsorID,unsigned int uiSponsorIDLength,unsigned char * pucSponsorPublicKey,unsigned int * puiSponsorPublicKeyLen,unsigned char * pucSponsorTmpPublicKey,unsigned int * puiSponsorTmpPublicKeyLen,void * * phAgreementHandle)
描述使用SM2密钥协商算法，为计算会话密钥而产生协商参数，同时返回指定索引位置的SM2公钥、临时SM2密钥对的公钥及协商句柄
参数hSymmKeyObj［in］（对称算法对象）
uiISKIndex［in］（密码设备内部存储加密私钥的索引值，该私钥用于参与密钥协商）
uiKeyBits［in］（要求协商的密钥长度）
pucSponsorID［in］（参与密钥协商的发起方 ID 值）
uiSponsorIDLength［in］（发起方 ID 长度）
pucSponsorPublicKey［out］（返回的发起方 SM2 公钥）
puiSponsorPublicKeyLen［in,out］（返回的发起方 SM2 公钥长度）
pucSponsorTmpPublicKey［out］（返回的发起方临时 SM2 公钥）
puiSponsorTmpPublicKeyLen［in,out］（返回的发起方临时 SM2 公钥长度）
phAgreementHandle［out］（返回的密钥协商句柄）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
规则为协商会话密钥，协商的发起方应首先调用本函数计算协商参数。协商参数的计算过程应按照GB/T 35276 的要求

6.4.35 计算会话密钥​

计算会话密钥函数定义应符合表63 的规定。

表63 计算会话密钥函数定义

项目内容
原型int SAF_GenerateKeyWithSM2(void * hAgreementHandle,unsigned char * pucResponseID,unsigned int uiResponseIDLength,unsigned char * pucResponsePublicKey,unsigned int uiResponsePublicKeyLen,unsigned char * pucResponseTmpPublicKey,unsigned int uiResponseTmpPublicKeyLen,void * * phKeyHandle)
描述使用 SM2密钥协商算法，使用自身协商句柄和响应方的协商参数计算会话密钥，同时返回会话密钥句柄
参数hAgreementHandle［in］（密钥协商句柄）
pucResponseID［in］（外部输入的响应方 ID 值）
uiResponseIDLength［in］（外部输入的响应方 ID 长度）
pucResponsePublicKey［in］（外部输入的响应方 SM2 公钥）
uiResponsePublicKeyLen［in］（外部输入的响应方 SM2 公钥长度）
pucResponseTmpPublicKey［in］（外部输入的响应方临时 SM2 公钥）
uiResponseTmpPublicKeyLen［in］（外部输入的响应方临时 SM2 公钥长度）
phKeyHandle［out］（返回的密钥句柄）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
规则协商的发起方获得响应方的协商参数后调用本函数，计算会话密钥。会话密钥的计算过程应按照GB/T 35276 的要求

6.4.36 产生协商数据并计算会话密钥​

产生协商数据并计算会话密钥函数定义应符合表64的规定。

表64 产生协商数据并计算会话密钥函数定义

项目内容
原型int SAF_GenerateAgreementDataAndKeyWithSM2(void * hSymmKeyObj,unsigned int uiISKIndex,unsigned int uiKeyBits,unsigned char * pucResponseID,unsigned int uiResponseIDLength,unsigned char * pucSponsorID,unsigned int uiSponsorIDLength,unsigned char * pucSponsorPublicKey,unsigned int uiSponsorPublicKeyLen,unsigned char * pucSponsorTmpPublicKey,unsigned int uiSponsorTmpPublicKeyLen,unsigned char * pucResponsePublicKey,unsigned int * puiResponsePublicKeyLen,unsigned char * pucResponseTmpPublicKey unsigned int * puiResponseTmpPublicKeyLen,void * * phKeyHandle)
描述使用 SM2密钥协商算法，产生协商参数并计算会话密钥，同时返回产生的协商参数和密钥句柄
参数hSymmKeyObj［in］（对称算法对象）
uiISKIndex［in］（密码设备内部存储加密私钥的索引值，该私钥用于参与密钥协商）
uiKeyBits［in］（协商后要求输出的密钥长度）
pucResponseID［in］（响应方 ID 值）
uiResponseIDLength［in］（响应方 ID 长度）
pucSponsorID［in］（发起方 ID 值）
uiSponsorIDLength［in］（发起方 ID 长度）
pucSponsorPublicKey［in］（外部输入的发起方 SM2 公钥）
pucSponsorPublicKeyLen［in］（外部输入的发起方 SM2 公钥长度）
uiSponsorTmpPublicKey［in］（外部输入的发起方临时 SM2 公钥）
uiSponsorTmpPublicKeyLen［in］（外部输入的发起方临时 SM2 公钥长度）
pucResponsePublicKey［out］（返回的响应方 SM2 公钥）
puiResponsePublicKeyLen［in,out］（返回的响应方 SM2 公钥长度）
pucResponseTmpPublicKey［out］（返回的响应方临时 SM2 公钥）
puiResponseTmpPublicKeyLen［in,out］（返回的响应方临时 SM2 公钥长度）
phKeyHandle［out］（返回的对称算法密钥句柄）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
规则本函数由响应方调用。会话密钥的计算过程应按照 GB/T 35276 的要求

6.4.37 销毁对称算法对象​

销毁对称算法对象函数定义应符合表65的规定。

表65 销毁对称算法对象函数定义

项目内容
原型int SAF_DestroySymmAlgoObj(void * hSymmKeyObj)
描述销毁对称算法对象
参数hSymmKeyObj［in］（对称算法密钥句柄）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.38 销毁会话密钥句柄​

销毁会话密钥句柄函数定义应符合表66的规定。

表66 销毁会话密钥句柄函数定义

项目内容
原型int SAF_DestroyKeyHandle(void * hKeyHandle)
描述销毁会话密钥句柄
参数hKeyHandle［in］（会话密钥句柄）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.39 单块加密运算​

单块加密运算函数定义应符合表67 的规定。

表67 单块加密运算函数定义

项目内容
原型int SAF_SymmEncrypt(void * hKeyHandle,unsigned char * pucInData,unsigned int uiInDataLen,unsigned char * pucOutData,unsigned int * puiOutDataLen)
描述加密运算
参数hKeyHandle［in］（对称算法密钥句柄）
pucInData［in］（输入数据）
uiInDataLen［in］（输入数据长度）
pucOutData［out］（输出数据）
puiOutDataLen［in,out］（输出数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.40 多块加密运算​

多块加密运算函数定义应符合表68 的规定。

表68 多块加密运算函数定义

项目内容
原型int SAF_SymmEncryptUpdate(void * hKeyHandle,unsigned char * pucInData,unsigned int uiInDataLen,unsigned char * pucOutData,unsigned int * puiOutDataLen)
描述多块加密运算
参数hKeyHandle［in］（对称算法密钥句柄）
pucInData［in］（输入数据）
uiInDataLen［in］（输入数据长度）
pucOutData［out］（输出数据）
puiOutDataLen［in,out］（输出数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
备注运算完成后，需调用 SAF_SymmEncryptFinal结束

6.4.41 结束加密运算​

结束加密运算函数定义应符合表69 的规定。

表69 结束加密运算函数定义

项目内容
原型int SAF_SymmEncryptFinal(void * hKeyHandle,unsigned char * pucOutData,unsigned int * puiOutDataLen)
描述结束加密运算
参数hKeyHandle［in］（对称算法密钥句柄）
pucOutData［out］（输出数据）
puiOutDataLen［in,out］（输出数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.42 单块解密运算​

单块解密运算函数定义应符合表70的规定。

表70 单块解密运算函数定义

项目内容
原型int SAF_SymmDecrypt(void * hKeyHandle,unsigned char * pucInData,unsigned int uiInDataLen,unsigned char * pucOutData,unsigned int * puiOutDataLen)
描述解密运算
参数hKeyHandle［in］（对称算法密钥句柄）
pucInData［in］（输入数据）
uiInDataLen［in］（输入数据长度）
pucOutData［out］（输出数据）
puiOutDataLen［in,out］（输出数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.43 多块解密运算​

多块解密运算函数定义应符合表71 的规定。

表71 多块解密运算函数定义

项目内容
原型int SAF_SymmDecryptUpdate(void * hKeyHandle,unsigned char * pucInData,unsigned int uiInDataLen,unsigned char * pucOutData,unsigned int * puiOutDataLen)
描述继续解密运算
参数hKeyHandle［in］（对称算法密钥句柄）
pucInData［in］（输入数据）
uiInDataLen［in］（输入数据长度）
pucOutData［out］（输出数据）
puiOutDataLen［in,out］（输出数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
备注运算完成后，需调用 SAF_SymmDecryptFinal 结束

6.4.44 结束解密运算​

结束解密运算函数定义应符合表72的规定。

表72 结束解密运算函数定义

项目内容
原型int SAF_SymmDecryptFinal(void * hKeyHandle,unsigned char * pucOutData,unsigned int * puiOutDataLen)
描述结束解密运算
参数hKeyHandle［in］（对称算法密钥句柄）
pucOutData［out］（输出数据）
puiOutDataLen［in,out］（输出数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.45 单组数据消息鉴别码运算​

单组数据消息鉴别码运算函数定义应符合表73的规定。

表73 单组数据消息鉴别码运算函数定义

项目内容
原型int SAF_Mac(void * hKeyHandle,unsigned char * pucInData,unsigned int uiInDataLen,unsigned char * pucOutData,unsigned int * puiOutDataLen)
描述单组数据消息鉴别码运算
参数hKeyHandle［in］（对称算法密钥句柄）
pucInData［in］（输入数据）
uiInDataLen［in］（输入数据长度）
pucOutData［out］（输出的 MAC）
puiOutDataLen［out］（MAC 长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.4.46 多组数据消息鉴别码运算​

多组数据消息鉴别码运算函数定义应符合表74的规定。

表74 多组数据消息鉴别码运算函数定义

项目内容
原型int SAF_MacUpdate(void * hKeyHandle,unsigned char * pucInData,unsigned int * puiInDataLen)
描述继续多组数据消息鉴别码运算
参数hKeyHandle［in］（对称算法密钥句柄）
pucInData［in］（输入数据）
puiInDataLen［in］（输入数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
备注运算完成后，需调用 SAF_MacFinal 结束

6.4.47 结束消息鉴别码运算​

结束消息鉴别码运算函数定义应符合表75 的规定。

表75 结束消息鉴别码运算函数定义

项目内容
原型int SAF_MacFinal(void * hKeyHandle,unsigned char * pucOutData,unsigned int uiOutDataLen)
描述结束消息鉴别码运算
参数hKeyHandle［in］（对称算法密钥句柄）
pucOutData［out］（输出的 MAC）
uiOutDataLen［out］（MAC 长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.5 消息类函数​

6.5.1 概述​

消息类函数主要是将数据按照 PKCS#7格式进行封装，实现应用系统互联互通和信息共享。

6.5.2 编码 PKCS #7格式的带签名的数字信封数据​

编码 PKCS ＃7格式的带签名的数字信封数据函数定义应符合表76 的规定。

表76 编码 PKCS #7 格式的带签名的数字信封数据函数定义

项目内容
原型int SAF_Pkcs7_EncodeData(void * hAppHandle,unsigned char * pucSignContainerName,unsigned int uiSignContainerNameLen,unsigned int uiSignKeyUsage,unsigned char * pucSignerCertificate,unsigned int uiSignerCertificateLen,unsigned int uiDigestAlgorithms,unsigned char * pucEncCertificate,unsigned int uiEncCertificateLen,unsigned int uiSymmAlgorithm,unsigned char * pucData,unsigned int uiDataLen,unsigned char * pucDerP7Data,unsigned int * puiDerP7DataLen)
描述编码 PKCS #7格式的带签名的数字信封数据
参数hAppHandle［in］（应用接口句柄）
pucSignContainerName［in］（签名私钥的密钥容器名）
uiSignContainerNameLen［in］（签名私钥的密钥容器名长度）
uiSignKeyUsage［in］（私钥的用途）
pucSignerCertificate［in］（签名者证书）
uiSignerCertificateLen［in］（签名者证书长度）
uiDigestAlgorithms［in］（HASH 算法）
pucEncCertificate［in］（接收者证书）
uiEncCertificateLen［in］（接收者证书长度）
uiSymmAlgorithm［in］（对称算法参数）
pucData［in］（签名原文）
uiDataLen［in］（签名原文长度）
pucDerP7Data［out］（编码后的数据）
puiDerP7DataLen［in,out］（编码后的数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.5.3 解码 PKCS #7格式的带签名的数字信封数据​

解码 PKCS #7格式的带签名的数字信封数据函数定义应符合表77的规定。

表77 解码 PKCS #7格式的带签名的数字信封数据函数定义

项目内容
原型int SAF_Pkcs7_DecodeData(void * hAppHandle,unsigned char * pucDecContainerName,unsigned int uiDecContainerNameLen,unsigned int uiDecKeyUsage,unsigned char * pucDerP7Data,unsigned int uiDerP7DataLen,unsigned char * pucData,unsigned int * puiDataLen,unsigned char * pucSignerCertificate,unsigned int * puiSignerCertificateLen,unsigned int * puiDigestAlgorithms unsigned char * pucSignedData,unsigned int * puiSignedDataLen)
描述解码 PKCS ＃7格式的带签名的数字信封数据
参数hAppHandle［in］（应用接口句柄）
pucDecContainerName［in］（解密用私钥的密钥容器名）
uiDecContainerNameLen［in］（解密用私钥的密钥容器名长度）
uiDecKeyUsage［in］（解密用私钥的用途）
pucDerP7Data［in］（编码后的数据）
uiDerP7DataLen［in］（编码后的数据长度）
pucData［out］（签名原文）
puiDataLen［in,out］（签名原文长度）
pucSignerCertificate［out］（签名者证书）
puiSignerCertificateLen［in,out］（签名者证书长度）
puiDigestAlgorithms［out］（HASH 算法）
pucSignedData［out］（Base64 编码的签名值）
puiSignedDataLen［in,out］（签名值长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.5.4 编码 PKCS #7格式的签名数据​

编码 PKCS#7格式的签名数据函数定义应符合表78的规定。

表78 编码 PKCS #7 格式的签名数据函数定义

项目内容
原型int SAF_Pkcs7_EncodeSignedData(void * hAppHandle,unsigned char * pucSignContainerName,unsigned int uiSignContainerNameLen,unsigned int uiSignKeyUsage,unsigned char * pucSignerCertificate,unsigned int uiSignerCertificateLen,unsigned int uiDigestAlgorithms,unsigned char * pucData,unsigned int uiDataLen,unsigned char * pucDerP7SignedData,unsigned int * puiDerP7SignedDataLen)
描述编码 PKCS #7格式的签名数据
参数hAppHandle［in］（应用接口句柄）
pucSignContainerName［in］（签名私钥的密钥容器名）
uiSignContainerNameLen［in］（签名私钥的密钥容器名长度）
uiSignKeyUsage［in］（私钥的用途）
pucSignerCertificate［in］（签名者证书）
uiSignerCertificateLen［in］（签名者证书长度）
uiDigestAlgorithms［in］（HASH 算法）
pucData［in］（需要签名的数据）
uiDataLen［in］（需要签名的数据长度）
pucDerP7SignedData［out］（带签名值的 P7 数据）
puiDerP7SignedDataLen［in,out］（带签名值的 P7 数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.5.5 解码 PKCS ＃7格式的签名数据​

解码 PKCS #7格式的签名数据函数定义应符合表79的规定。

表79 解码 PKCS #7格式的签名数据函数定义

项目内容
原型int SAF_Pkcs7_DecodeSignedData(void * hAppHandle,unsigned char * pucDerP7SignedData,unsigned int uiDerP7SignedDataLen,unsigned char * pucSignerCertificate,unsigned int * puiSignerCertificateLen,unsigned int * puiDigestAlgorithms,unsigned char * pucData,unsigned int * puiDataLen,unsigned char * pucSign,unsigned int * puiSignLen)
描述解码 PKCS #7格式的签名数据
参数hAppHandle［in］（应用接口句柄）
pucDerP7SignedData［in］（签名后的数据）
uiDerP7SignedDataLen［in］（签名后的数据长度）
pucSignerCertificate［out］（签名者证书）
puiSignerCertificateLen［in,out］（签名者证书长度）
puiDigestAlgorithms［out］（HASH 算法）
pucData［out］（被签名的数据）
puiDataLen［in,out］（被签名的数据长度）
pucSign［out］（签名值）
puiSignLen［in,out］（签名值的长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.5.6 编码 PKCS ＃7格式的数字信封数据​

编码 PKCS #7格式的数字信封数据函数定义应符合表80的规定。

表80 编码 PKCS #7格式的数字信封数据函数定义

项目内容
原型int SAF_Pkcs7_EncodeEnvelopedData(void * hAppHandle,unsigned char * pucData,unsigned int uiDataLen,unsigned char * pucEncCertificate,unsigned int uiEncCertificateLen,unsigned int uiSymmAlgorithm,unsigned char * pucDerP7EnvelopedData,unsigned int * puiDerP7EnvelopedDataLen)
描述编码 PKCS #7格式的数字信封数据
参数hAppHandle［in］（应用接口句柄）
pucData［in］（需要做数字信封的数据）
uiDataLen［in］（需要做数字信封的数据长度）
pucEncCertificate［in］（接收者证书）
uiEncCertificateLen［in］（接收者证书长度）
uiSymmAlgorithm［in］（对称算法参数）
pucDerP7EnvelopedData［out］（编码后的数字信封数据）
puiDerP7EnvelopedDataLen［in,out］（编码后的数字信封数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.5.7 解码 PKCS ＃7格式的数字信封数据​

解码 PKCS #7格式的数字信封数据函数定义应符合表81 的规定。

表81 解码 PKCS #7格式的数字信封数据函数定义

项目内容
原型int SAF_Pkcs7_DecodeEnvelopedData(void * hAppHandle,unsigned char * pucDecContainerName,unsigned int uiDecContainerNameLen,unsigned int uiDecKeyUsage,unsigned char * pucDerP7EnvelopedData,unsigned int uiDerP7EnvelopedDataLen,unsigned char * pucData,unsigned int * puiDataLen)
描述解码 PKCS #7格式的数字信封数据
参数hAppHandle［in］（应用接口句柄）
pucDecContainerName［in］（解密用私钥的密钥容器名）
uiDecContainerNameLen［in］（解密用私钥的密钥容器名长度）
uiDecKeyUsage［in］（解密用私钥的用途）
pucDerP7EnvelopedData［in］（数字信封数据）
uiDerP7EnvelopedDataLen［in］（数字信封数据长度）
pucData［out］（解码后得到的数据原文）
puiDataLen［in,out］（解码后得到的数据原文数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.5.8 编码 PKCS #7格式的摘要数据​

编码 PKCS#7格式的摘要数据函数定义应符合表82的规定。

表82 编码 PKCS ＃7格式的摘要数据函数定义

项目内容
原型int SAF_Pkcs7_EncodeDigestedData(void * hAppHandle,unsigned int uiDigestAlgorithm,unsigned char * pucData,unsigned int puiDataLen,unsigned char * pucDerP7DigestedData,unsigned int * puiDerP7DigestedDataLen)
描述使用指定的杂凑算法计算原文的摘要，并打包成符合 PKCS ＃7摘要数据格式的数据包
参数hAppHandle［in］（应用接口句柄）
uiDigestAlgorithm［in］（杂凑算法标识）
pucData［in］（原文数据）
puiDataLen［in］（原文数据长度）
pucDerP7DigestedData［out］（符合 PKCS #7 摘要数据格式的数据包）
puiDerP7DigestedDataLen［in,out］（符合 PKCS #7 摘要数据格式的数据包长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.5.9 解码 PKCS #7格式的摘要数据​

解码 PKCS ＃7格式的摘要数据函数定义应符合表83的规定。

表83 解码 PKCS #7格式的摘要数据函数定义

项目内容
原型int SAF_Pkcs7_DecodeDigestedData(void * hAppHandle,unsigned int uiDigestAlgorithm,unsigned char * pucDerP7DigestedData,unsigned int puiDerP7DigestedDataLen,unsigned char * pucData,unsigned int * puiDataLen,unsigned char * pucDigest,unsigned int * puiDigestLen)
描述从符合 PKCS #7摘要数据格式的数据包中解析出原文及摘要值
参数hAppHandle［in］（应用接口句柄）
uiDigestAlgorithm［in］（杂凑算法标识）
pucDerP7DigestedData［in］（符合 PKCS #7 摘要数据格式的数据包）
puiDerP7DigestedDataLen［in］（符合 PKCS #7 摘要数据格式的数据包长度）
pucData［out］（原文数据）
puiDataLen［in,out］（原文数据长度）
pucDigest［out］（摘要值）
puiDigestLen［in,out］（摘要值长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.5.10 编码基于 SM2算法的带签名的数字信封数据​

编码基于SM2算法的带签名的数字信封数据函数定义应符合表84 的规定。

表84 编码基于SM2算法的带签名的数字信封数据函数定义

项目内容
原型int SAF_SM2_EncodeSignedAndEnvelopedData(void * hAppHandle,unsigned char * pucSignContainerName,unsigned int uiSignContainerNameLen,unsigned int uiSignKeyUsage,unsigned char * pucSignerCertificate,unsigned int uiSignerCertificateLen,unsigned int uiDigestAlgorithms,unsigned char * pucEncCertificate,unsigned int uiEncCertificateLen,unsigned int uiSymmAlgorithm,unsigned char * pucData,unsigned int uiDataLen,unsigned char * pucDerSignedAndEnvelopedData,unsigned int * puiDerSignedAndEnvelopedDataLen)
描述编码基于 SM2算法的带签名的数字信封数据
参数hAppHandle［in］（应用接口句柄）
pucSignContainerName［in］（签名私钥的密钥容器名）
uiSignContainerNameLen［in］（签名私钥的密钥容器名长度）
uiSignKeyUsage［in］（私钥的用途）
pucSignerCertificate［in］（签名者证书）
uiSignerCertificateLen［in］（签名者证书长度）
uiDigestAlgorithms［in］（HASH 算法）
pucEncCertificate［in］（接收者证书）
uiEncCertificateLen［in］（接收者证书长度）
uiSymmAlgorithm［in］（对称算法参数）
pucData［in］（签名原文）
uiDataLen［in］（签名原文长度）
pucDerSignedAndEnvelopedData［out］（DER 编码后的 SignedAndEnvelopedData 数字信封数据，SignedAndEnvelopedData 数据格式定义应按照 GB/T 35275 的规定）
puiDerSignedAndEnvelopedDataLen［in,out］（带签名的数字信封数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.5.11 解码基于SM2 算法的带签名的数字信封数据​

解码基于 SM2算法的带签名的数字信封数据函数定义应符合表85的规定。

表85 解码基于 SM2 算法的带签名的数字信封数据函数定义

项目内容
原型int SAF_SM2_DecodeSignedAndEnvelopedData(void * hAppHandle,unsigned char * pucDecContainerName,unsigned int uiDecContainerNameLen,unsigned int uiDecKeyUsage,unsigned char * pucDerSignedAndEnvelopedData,unsigned int uiDerSignedAndEnvelopedDataLen,unsigned char * pucData,unsigned int * puiDataLen,unsigned char * pucSignerCertificate,unsigned int * puiSignerCertificateLen,unsigned int * puiDigestAlgorithms)
描述解码基于 SM2算法的带签名的数字信封数据
参数hAppHandle［in］（应用接口句柄）
pucDecContainerName［in］（解密用私钥的密钥容器名）
uiDecContainerNameLen［in］（解密用私钥的密钥容器名长度）
uiDecKeyUsage［in］（解密用私钥的用途）
pucDerSignedAndEnvelopedData［in］（DER 编码后的 SignedAndEnvelopedData 数字信封数据，SignedAndEnvelopedData 数据格式定义应按照 GB/T 35275 的规定）
uiDerSignedAndEnvelopedDataLen［in］（编码后的带签名的数字信封数据长度）
pucData［out］（解码后得到的签名原文）
puiDataLen［in,out］（签名原文长度）
pucSignerCertificate［out］（签名者证书）
puiSignerCertificateLen［in,out］（签名者证书长度）
puiDigestAlgorithms［out］（HASH 算法标识）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.5.12 编码基于SM2 算法的签名数据​

编码基于SM2算法的签名数据函数定义应符合表86 的规定。

表86 编码基于SM2算法的签名数据函数定义

项目内容
原型int SAF_SM2_EncodeSignedData(void * hAppHandle,unsigned char * pucSignContainerName,unsigned int uiSignContainerNameLen,unsigned int uiSignKeyUsage,unsigned char * pucSignerCertificate,unsigned int uiSignerCertificateLen,unsigned int uiDigestAlgorithms,unsigned char * pucData,unsigned int uiDataLen,unsigned char * pucDerSignedData,unsigned int * puiDerSignedDataLen)
描述编码基于 SM2算法的签名数据
参数hAppHandle［in］（应用接口句柄）
pucSignContainerName［in］（签名私钥的密钥容器名）
uiSignContainerNameLen［in］（签名私钥的密钥容器名长度）
uiSignKeyUsage［in］（私钥的用途）
pucSignerCertificate［in］（签名者证书）
uiSignerCertificateLen［in］（签名者证书长度）
uiDigestAlgorithms［in］（HASH 算法标识）
pucData［in］（需要签名的数据）
uiDataLen［in］（需要签名的数据长度）
pucDerSignedData［out］（DER 编码的 SignedData 签名数据，SignedData 数据格式定义应按照 GB/T 35275 的规定）
puiDerSignedDataLen［in,out］（带签名数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.5.13 解码基于SM2 算法的签名数据​

解码基于SM2 算法的签名数据函数定义应符合表87 的规定。

表87 解码基于 SM2 算法的签名数据函数定义

项目内容
原型int SAF_SM2_DecodeSignedData(void * hAppHandle,unsigned char * pucDerSignedData,unsigned int uiDerSignedDataLen,unsigned char * pucSignerCertificate,unsigned int * puiSignerCertificateLen,unsigned int * puiDigestAlgorithms,unsigned char * pucData,unsigned int * puiDataLen,unsigned char * pucSign,unsigned int * puiSignLen)
描述解码基于 SM2 算法的签名数据
参数hAppHandle［in］（应用接口句柄）
pucDerSignedData［in］（DER 编码的 SignedData 签名数据，SignedData 数据格式定义应按照 GB/T 35275 的规定）
uiDerSignedDataLen［in］（签名数据的长度）
pucSignerCertificate［out］（DER 编码的签名者证书）
puiSignerCertificateLen［in,out］（签名者证书长度）
puiDigestAlgorithms［out］（HASH 算法标识）
pucData［out］（被签名的数据）
puiDataLen［in,out］（被签名的数据长度）
pucSign［out］（签名值）
puiSignLen［in,out］（签名值的长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.5.14 编码基于SM2 算法的数字信封​

编码基于 SM2算法的数字信封函数定义应符合表88的规定。

表88 编码基于 SM2 算法的数字信封函数定义

项目内容
原型int SAF_SM2_EncodeEnvelopedData(void * hAppHandle,unsigned char * pucData,unsigned int uiDataLen,unsigned char * pucEncCertificate,unsigned int uiEncCertificateLen,unsigned int uiSymmAlgorithm,unsigned char * pucDerEnvelopedData,unsigned int * puiDerEnvelopedDataLen)
描述编码基于 SM2 算法的数字信封数据
参数hAppHandle［in］（应用接口句柄）
pucData［in］（需要做数字信封的数据）
uiDataLen［in］（需要做数字信封的数据长度）
pucEncCertificate［in］（DER 编码的接收者证书）
uiEncCertificateLen［in］（接收者证书长度）
uiSymmAlgorithm［in］（对称算法标识）
pucDerEnvelopedData［out］（DER 编码后的 EnvelopedData 数字信封数据，EnvelopedData 数据格式定义应按照 GB/T 35275 的规定）
puiDerEnvelopedDataLen［in,out］（编码后的数字信封数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.5.15 解码基于 SM2 算法的数字信封​

解码基于SM2算法的数字信封函数定义应符合表89的规定。

表89 解码基于SM2算法的数字信封函数定义

项目内容
原型int SAF_SM2_DecodeEnvelopedData(void * hAppHandle,unsigned char * pucDecContainerName,unsigned int uiDecContainerNameLen,unsigned int uiDecKeyUsage,unsigned char * pucDerEnvelopedData,unsigned int uiDerEnvelopedDataLen,unsigned char * pucData,unsigned int * puiDataLen)
描述解码基于 SM2算法的数字信封数据
参数hAppHandle［in］（应用接口句柄）
pucDecContainerName［in］（解密用私钥的密钥容器名）
uiDecContainerNameLen［in］（解密用私钥的密钥容器名长度）
uiDecKeyUsage［in］（解密用私钥的用途）
pucDerEnvelopedData［in］（DER 编码的 EnvelopedData 数字信封数据，EnvelopedData 数据格式定义应按照 GB/T 35275 的规定）
uiDerEnvelopedDataLen［in］（数字信封数据长度）
pucData［out］（解码后得到的数据原文）
puiDataLen［in,out］（解码后得到的数据原文长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

6.5.16 解析 PKCS ＃7格式的签名数据​

解析 PKCS #7格式的签名数据函数定义应符合表90的规定。

表90 解析 PKCS ＃7格式的签名数据函数定义

项目内容
原型int SAF_Parse_Pkcs7_SignedData(void * hAppHandle,unsigned int nType,unsigned char * pucDerP7SignedData,unsigned int uiDerP7SignedDataLen,unsigned char * pucInfo,unsigned int * puiInfoLen)
描述解析 PKCS ＃7格式的签名数据
参数hAppHandle［in］（应用接口句柄）
nType［in］（解析类型，1：版本号；2：算法类型，RSA 或 SM2；3：签名原文；4：签名证书；5：签名值）
pucDerP7SignedData［in］（DER 编码后的 PKCS #7 签名数据）
uiDerP7SignedDataLen［in］（DER 编码后的 PKCS #7 签名数据长度）
pucInfo［out］（解析出来的信息）
puiInfoLen［in,out］（解析出来的信息长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）

7 验证方法​

7.1 验证环境​

接口提供方实现本文件所规定的接口，提供测试程序和测试程序源代码。接口需求方可选择使用接口提供方提供的测试程序验证接口，或自编写测试程序来验证接口。验证接口，应具备以下验证环境：

  1. a） 运行接口服务所需的操作系统及测试程序软件；
  2. b） 支持密码设备应用接口调用的密码设备；
  3. c） 支持存储证书和密钥的存储介质（如智能密码钥匙）。

7.2 密码服务环境操作验证​

7.2.1 密码服务空间验证​

密码服务空间验证步骤如下。

  1. a） 验证目的：验证通过密码服务接口是否正确创建、使用、清除密码服务空间操作。
  2. b） 验证条件：密码服务已就绪。
  3. c） 验证过程：
    1. 1） 正常情况验证：

      步骤1：调用 SAF_Initialize 初始化环境；

      步骤2：调用 SAF_GetVersion 获取接口版本信息；

      步骤3：调用 SAF_Finalize 清除环境；

      步骤4：调用 SAF_GetVersion 获取接口版本信息。

    2. 2） 异常情况验证：

      步骤1：调用 SAF_GetVersion 获取接口版本信息。

  4. d） 验证结果：
    1. 1） 正常情况验证：步骤2获取接口版本信息成功，步骤4获取接口版本信息失败返回错误码。
    2. 2） 异常情况验证：步骤1获取接口版本信息失败返回错误码。

7.2.2 用户登录验证​

用户登录验证步骤如下。

  1. a） 验证目的：验证通过密码服务接口是都正确登录用户、修改用户口令、注销登录。
  2. b） 验证条件：密码服务已就绪，密码服务空间已完成初始化。
  3. c） 验证过程：
    1. 1） 正常情况验证：

      步骤1：调用 SAF_Login 登陆用户；

      步骤2：调用 SAF_ChangePin 修改口令；

      步骤3：调用 SAF_Logout 注销登录；

      步骤4：调用SAF_ChangePin 修改口令。

    2. 2） 异常情况验证：

      步骤1：调用 SAF_ChangePin 修改口令。

  4. d） 验证结果：
    1. 1） 正常情况验证：步骤2获取接口版本信息成功，步骤4获取接口版本信息失败返回错误码。
    2. 2） 异常情况验证：步骤1获取接口版本信息失败返回错误码。

7.3 证书类函数功能验证​

7.3.1 根 CA 证书验证​

根 CA 证书验证步骤如下。

  1. a） 验证目的：验证通过密码服务接口是否正确执行根CA 证书的添加、删除操作。
  2. b） 验证条件：密码服务已就绪，密码服务空间已完成初始化。
  3. c） 验证过程：
    1. 1） 添加 CA 根证书：

      步骤1：调用 SAF_GetRootCaCertificateCount 获取 CA 根证书的个数 m；

      步骤2：调用 SAF_AddTrustedRootCaCertificate 添加 CA 根证书 rootCA1；

      步骤3：调用 SAF_GetRootCaCertificateCount 获取 CA 根证书的个数 n；

      步骤4：输入索引 n-1，调用 SAF_GetRootCaCertificateCount 获取 CA 根证书 rootCA2。

    2. 2） 删除 CA 根证书：

      步骤1：执行验证过程 a）；

      步骤2：调用 SAF_RemoveRootCaCertificate 删除指定CA根证书；

      步骤3：调用 SAF_GetRootCaCertificateCount 获取 CA 根证书的个数 n1；

      步骤4：输入位置索引 n1-1，调用 SAF_GetRootCaCertificateCount 获取已删除的CA 根证书。

  4. d） 验证结果：
    1. 1） 正常情况验证：n=m+1 且能够得到与设置相同的 CA 根证书（rootCA1 = rootCA2）。
    2. 2） 异常情况验证：n1=m 且 SAF_GetRootCaCertificateCount 返回错误码 SAR_CertNotFountErr。

7.3.2 CA 证书验证​

CA证书验证步骤如下。

  1. a） 验证目的：验证通过密码服务接口是否正确执行CA 证书的添加、删除操作。
  2. b） 验证条件：密码服务已就绪，密码服务空间已完成初始化，添加根CA证书。
  3. c） 验证过程：
    1. 1） 添加 CA 证书：

      步骤1：调用 SAF_GetCaCertificateCount 获取 CA 证书的个数 m；

      步骤2：调用 SAF_AddCaCertificate 添加 CA证书 CA1；

      步骤3：调用 SAF_GetCaCertificateCount 获取 CA 证书的个数 n；

      步骤4：输入索引 n-1，调用 SAF_GetCaCertificate 获取CA根证书。

    2. 2） 删除 CA 证书：

      步骤1：执行验证过程 a）；

      步骤2：调用 SAF_RemoveCaCertificate 删除指定CA证书；

      步骤3：调用 SAF_GetCaCertificateCount 获取 CA证书的个数 n1；

      步骤4：输入位置索引 n1-1，调用 SAF_GetCaCertificate 获取已删除的 CA 证书。

  4. d） 验证结果：
    1. 1） 正常情况验证：n=m+1 且能够得到与设置相同的CA证书（CA1=CA2）。
    2. 2） 异常情况验证：n1=m 且 SAF_GetCaCertificateCount 返回错误码 SAR_CertNotFountErr。

7.3.3 证书状态验证​

证书状态验证步骤如下。

  1. a） 验证目的：验证通过密码服务接口是否正确添加 CRL、验证用户证书、根据 CRL 文件获取用户注销状态、根据 OCSP 获取证书状态、通过 LDAP 方式获取证书、通过 LDAP 方式获取证书对应的 CRL 操作。
  2. b） 验证条件：密码服务已就绪，密码服务空间已完成初始化，添加根CA证书，添加CA证书。
  3. c） 验证过程：
    1. 1） 正常情况验证：

      步骤1：调用 SAF_AddCrl 添加 CRL；

      步骤2：调用 SAF_VerifyCertificate 验证用户证书；

      步骤3：调用 SAF_VerifyCertificateByCrl 根据 CRL 文件获取用户证书注销状态；

      步骤4：调用 SAF_GetCertificateStateByOCSP 根据 OCSP 获取用户证书注销状态；

      步骤5：调用 SAF_GetCertFromLdap 通过 LDAP 方式获取证书对应的 CRL。

    2. 2） 异常情况验证：使用非法参数调用本接口，应返回错误码。
  4. d） 验证结果：
    1. 1） 正常情况验证：待验证的证书通过CRL、OCSP、LDAP 验证证书状态。
    2. 2） 异常情况验证：可得到预期结果。

7.3.4 用户证书验证​

用户证书验证步骤如下。

  1. a） 验证目的：验证通过密码服务接口是否正确获取证书信息、获取证书扩展信息、列举用户证书、列举用户密钥容器信息、释放列举用户证书的内存、释放列举密钥容器信息的内存。
  2. b） 验证条件：密码服务已就绪，密码服务空间已完成初始化，添加根CA证书，添加CA证书。
  3. c） 验证过程：
    1. 1） 正常情况验证：

      步骤1：调用 SAF_GetCertificateInfo 获取证书信息；

      步骤2：调用 SAF_GetExtTypeInfo 获取证书扩展信息；

      步骤3：调用 SAF_EnumCertificates 列举用户证书；

      步骤4：调用 SAF_EnumKeyContainerInfo 列举用户的密钥容器信息；

      步骤5：调用 SAF_EnumCertificatesFree 释放列举用户证书的内存；

      步骤6：调用 SAF_EnumkeyContainerInfoFree 释放列举密钥容器信息的内存。

    2. 2） 异常情况验证：使用非法参数调用本接口，应返回错误码。
  4. d） 验证结果：
    1. 1） 正常情况验证：获取用户信息、扩展信息，释放用户证书、密钥容器的内存。
    2. 2） 异常情况验证：可得到预期结果。

7.4 签名验签验证​

7.4.1 RSA签名运算验证​

RSA 签名运算验证步骤如下。

  1. a） 验证目的：验证是否能正确使用预定 RSA 签名私钥，对预定数据进行数字签名，并输出签名结果。
  2. b） 验证条件：设备已就绪，环境已初始化，已列举用户证书。
  3. c） 验证过程：
    1. 1） 正常情况验证：

      步骤1：调用 SAF_Login，验证用户口令；

      步骤2：调用 SAF_RsaSign 接口，指定 SHA256 哈希算法，对预定数据进签名，返回签名结果；

      步骤3：调用 SAF_GetRsaPublicKey 接口，导出 RSA 签名公钥。

    2. 2） 异常情况验证：使用非法参数调用本接口，应返回错误码；

      用户未登录，应返回错误码；

      RSA密钥对不存在，应返回错误码。

  4. d） 验证结果：
    1. 1） 正常情况验证：用步骤3返回的签名公钥对步骤2返回的签名结果验签应成功。
    2. 2） 异常情况验证：得到预期结果。

7.4.2 RSA 验证签名运算验证​

RSA 验证签名运算验证步骤如下。

  1. a） 验证目的：验证是否能正确使用外部输入的 RSA公钥对数据进行签名验证。
  2. b） 验证条件：设备已就绪，环境已初始化，已列举用户证书，已登录。
  3. c） 验证过程：
    1. 1） 正常情况验证：

      步骤1：使用预置的 RSA 签名公钥、原文和签名值，调用 SAF_RsaVerifySign 接口；

      步骤2：调用 SAF_RsaSign接口，指定 SHA256 哈希算法，对预定数据进行签名，得到签名结果；

      步骤3：调用 SAF_GetRsaPublicKey 接口，导出 RSA 签名公钥；

      步骤4：使用步骤2的原文和签名结果、步骤3得到的签名公钥，调用SAF_RsaVerifySign接口。

    2. 2） 异常情况验证：使用非法参数调用本接口，应返回错误码。
  4. d） 验证结果：
    1. 1） 正常情况验证：待验证的 RSA 公钥和原文、签名值匹配应验签成功，不匹配应验签失败。
    2. 2） 异常情况验证：可得到预期结果。

7.4.3 基于证书的 RSA 的公钥验证​

基于证书的 RSA 的公钥验证步骤如下。

  1. a） 验证目的：验证是否能正确使用外部输入的 RSA 证书对数据进行签名验证。
  2. b） 验证条件：设备已就绪，环境已初始化，已列举用户证书，已登录。
  3. c） 验证过程：
    1. 1） 正常情况验证：

      步骤1：使用预置的 RSA 签名证书、原文和签名值，调用 SAF_VerifySignByCert 接口；

      步骤2：调用 SAF_RsaSign 接口，指定SHA256 哈希算法，对预定数据进行签名，得到签名结果；

      步骤3：使用步骤2的原文和签名结果、列举证书时取到的签名证书，调用 SAF_VerifySignByCert 接口。

    2. 2） 异常情况验证：使用非法参数调用本接口，应返回错误码。
  4. d） 验证结果：
    1. 1） 正常情况验证：待验证的 RSA 证书和原文，签名值匹配应验签成功，不匹配应验签失败。
    2. 2） 异常情况验证：可得到预期结果。

7.4.4 SM2 签名运算​

SM2 签名运算验证步骤如下。

  1. a） 验证目的：验证是否能正确使用预定 SM2签名私钥，对预定数据进行数字签名，并输出签名结果。
  2. b） 验证条件：设备已就绪，环境已初始化，已列举用户证书。
  3. c） 验证过程：
    1. 1） 正常情况验证：

      步骤1：调用 SAF_Login，验证用户口令；

      步骤2：调用SAF_Sm2Sign 接口，对预定数据进行签名，返回签名结果；

      步骤3：调用 SAF_GetSm2PublicKey 接口，导出SM2签名公钥。

    2. 2） 异常情况验证：使用非法参数调用本接口，应返回错误码；

      用户未登录，应返回错误码；

      SM2密钥对不存在，应返回错误码。

  4. d） 验证结果：
    1. 1） 正常情况验证：用步骤3返回的签名公钥对步骤2返回的签名结果验签应成功。
    2. 2） 异常情况验证：得到预期结果。

7.4.5 SM2 验证签名运算​

SM2验证签名运算验证步骤如下。

  1. a） 验证目的：验证是否能正确使用外部输入的 SM2 公钥对数据进行签名验证。
  2. b） 验证条件：设备已就绪，环境已初始化，已列举用户证书，已登录。
  3. c） 验证过程：
    1. 1） 正常情况验证：

      步骤1：使用预置的 SM2 签名公钥、原文和签名值，调用 SAF_Sm2VerifySign 接口；

      步骤2：调用 SAF_Sm2Sign 接口，对预定数据进行签名，得到签名结果；

      步骤3：调用 SAF_GetSm2PublicKey 接口，导出 SM2 签名公钥；

      步骤4：使用步骤2的原文和签名结果、步骤3得到的签名公钥，调用 SAF_Sm2VerifySign 接口。

    2. 2） 异常情况验证：使用非法参数调用本接口，应返回错误码。
  4. d） 验证结果：
    1. 1） 正常情况验证：待验证的SM2公钥和原文，签名值匹配应验签成功，不匹配应验签失败。
    2. 2） 异常情况验证：可得到预期结果。

7.4.6 基于证书的SM2公钥验证​

基于证书的SM2公钥验证步骤如下。

  1. a） 验证目的：验证是否能正确使用外部输入的 SM2 证书对数据进行签名验证。
  2. b） 验证条件：设备已就绪，环境已初始化，已列举用户证书，已登录。
  3. c） 验证过程：
    1. 1） 正常情况验证：

      步骤1：使用预置的 SM2 签名证书、原文和签名值，调用 SAF_Sm2VerifySignByCert 接口。

      步骤2：调用SAF_Sm2Sign 接口，对预定数据进行签名，得到签名结果。

      步骤3：使用步骤2的原文和签名结果、列举证书时取到的签名证书，调用 SAF_Sm2VerifySignByCert 接口。

    2. 2） 异常情况验证：使用非法参数调用本接口，应返回错误码。
  4. d） 验证结果：
    1. 1） 正常情况验证：待验证的SM2证书和原文、签名值匹配应验签成功，不匹配应验签失败。
    2. 2） 异常情况验证：可得到预期结果。

7.5 摘要计算验证​

7.5.1 单块摘要计算​

单块摘要计算验证步骤如下。

  1. a） 验证目的：验证是否能正确进行单块摘要运算。
  2. b） 验证条件：无。
  3. c） 验证过程：
    1. 1） 正常情况验证：调用 SAF_Hash 接口，对预定数据计算摘要值。
    2. 2） 异常情况验证：使用非法参数调用本接口，应返回错误码。
  4. d） 验证结果：
    1. 1） 正常情况验证：计算得到的摘要值应与预定结果一致，计算时设置 pucOutData = NULL 时，应能通过 puiOutDataLen 返回结果数据实际长度。
    2. 2） 异常情况验证：得到预期结果。

7.5.2 多块摘要计算​

多块摘要计算验证步骤如下。

  1. a） 验证目的：验证是否能正确进行多块摘要运算。
  2. b） 验证条件：初始化环境函数 SAF_Initialize 已经成功调用。
  3. c） 验证过程：
    1. 1） 正常情况验证：

      步骤1：调用 SAF_CreateHashObj 接口，创建 HASH 对象；

      步骤2：调用 SAF_HashUpdate 接口，对多块预定数据继续进行 HASH运算；

      步骤3：调用 SAF_HashFinal 接口，结束 HASH运算，得到摘要值；

      步骤4：调用 SAF_DestroyHashObj 接口，删除 HASH对象。

    2. 2） 异常情况验证：使用非法参数调用上述接口，应返回错误码。
  4. d） 验证结果：
    1. 1） 正常情况验证：步骤3中得到的摘要值应与预定结果一致，步骤3中设置 pucOutData = NULL 时，应能通过 puiOutDataLen 返回摘要结果实际长度。
    2. 2） 异常情况验证：得到预期结果。

7.6 非对称加解密验证​

7.6.1 SM2 公钥加密​

SM2公钥加密验证步骤如下。

  1. a） 验证目的：验证是否能正确采用外部 SM2 公钥对输入数据进行加密，并输出加密结果。
  2. b） 验证条件：完成环境初始化。
  3. c） 验证过程：
    1. 1） 正常情况验证：使用预定 SM2密钥对，调用SAF_Sm2PublicKeyEnc 接口，对预定原文进行加密，返回加密结果。
    2. 2） 异常情况验证：使用非法参数调用本接口，应返回错误码。
  4. d） 验证结果：
    1. 1） 正常情况验证：使用预定私钥对加密密文进行解密，得到结果与预定原文相同；加密数据格式应符合GB/T 35276 中加密数据格式的定义。
    2. 2） 异常情况验证：得到预期结果。

7.6.2 基于证书的SM2公钥加密​

基于证书的SM2公钥加密验证步骤如下。

  1. a） 验证目的：验证是否能正确采用外部证书的SM2公钥对输入数据进行加密，并输出加密结果。
  2. b） 验证条件：完成环境初始化，使用预定SM2私钥申请证书。
  3. c） 验证过程：
    1. 1） 正常情况验证：使用预定容器内调用 SAF_Sm2PublicKeyEncByCert 接口，对预定原文进行加密，返回加密结果。
    2. 2） 异常情况验证：使用非法参数调用本接口，应返回错误码。
  4. d） 验证结果：
    1. 1） 正常情况验证：使用预定私钥对加密密文进行解密，得到结果与预定原文相同。加密数据格式应符合GB/T 35276 中加密数据格式的定义。
    2. 2） 异常情况验证：得到预期结果。

7.6.3 基于证书的SM2 解密​

基于证书的SM2 解密验证步骤如下。

  1. a） 验证目的：验证是否能正确采用容器内证书标识对应私钥进行解密，并输出原文。
  2. b） 验证条件：完成环境初始化，证书标识对应私钥已存在。
  3. c） 验证过程：
    1. 1） 正常情况验证：使用预定容器内调用 SAF_Sm2PublicKeyDecByCert 接口，对预定密文进行解密，返回明文数据。
    2. 2） 异常情况验证：使用非法参数调用本接口，应返回错误码；

      解密密钥不存在，应返回错误码。

  4. d） 验证结果：
    1. 1） 正常情况验证：返回的明文数据与预定明文一致。
    2. 2） 异常情况验证：得到预期结果。

7.7 对称加解密验证​

7.7.1 单块加密​

单块加密验证步骤如下。

  1. a） 验证目的：验证是否能正确进行单块数据的加密操作。
  2. b） 验证条件：初始化环境函数 SAF_Initialize、用户登录函数 SAF_Login、创建对称算法对象 SAF_CreateSymmAlgoObj 已经成功调用，会话密钥已生成或已导入或已协商。
  3. c） 验证过程：
    1. 1） 正常情况验证：调用 SAF_SymmEncrypt 接口，对预定数据计算密文值。
    2. 2） 异常情况验证：使用非法参数调用 SAF_SymmEncrypt 接口，应返回错误码。
  4. d） 验证结果：
    1. 1） 正常情况验证：计算中得到的密文值应与预定结果一致，计算中设置 pucOutData = NULL 时，应能通过 puiOutDataLen 返回结果数据实际长度。
    2. 2） 异常情况验证：得到预期结果。

7.7.2 单块解密​

单块解密验证步骤如下。

  1. a） 验证目的：验证是否能正确进行多块数据的加密操作。
  2. b） 验证条件：初始化环境函数 SAF_Initialize、用户登录函数 SAF_Login、创建对称算法对象 SAF_CreateSymmAlgoObj 已经成功调用，会话密钥已生成或已导入或已协商。
  3. c） 验证过程：
    1. 1） 正常情况验证：

      步骤1：调用 SAF_SymmEncryptUpdate 接口，对多个预定明文数据分组进行加密，返回密文数据；

      步骤2：调用 SAF_SymmEncryptFinal 接口结束加密，得到密文数据。

    2. 2） 异常情况验证：使用非法参数调用上述接口，应返回错误码；

      不执行步骤1，直接执行步骤2应返回错误码；

  4. d） 验证结果：
    1. 1） 正常情况验证：步骤1和步骤2返回的加密密文与预定密文一致。步骤1和步骤2中设置 pucOutData = NULL 时，应能通过 puiOutDataLen 返回结果数据实际长度。
    2. 2） 异常情况验证：得到预期结果。

7.7.3 多块加密​

多块加密验证步骤如下。

  1. a） 验证目的：验证是否能正确进行单块数据解密运算。
  2. b） 验证条件：初始化环境函数 SAF_Initialize、用户登录函数 SAF_Login、创建对称算法对象 SAF_CreateSymmAlgoObj 已经成功调用，会话密钥已生成或已导入或已协商。
  3. c） 验证过程：
    1. 1） 正常情况验证：

      步骤1：调用 SAF_SymmEncryptUpdate 接口，对多个预定明文数据分组进行加密，返回密文数据；

      步骤2：调用SAF_SymmEncryptFinal 接口结束加密，得到密文数据。

    2. 2） 异常情况验证：使用非法参数调用上述接口，应返回错误码；

      不执行步骤1，直接执行步骤2应返回错误码。

  4. d） 验证结果：
    1. 1） 正常情况验证：计算中得到的密文值应与预定结果一致，计算中设置 pucOutData = NULL 时，应能通过 puiOutDataLen 返回结果数据实际长度。
    2. 2） 异常情况验证：得到预期结果。

7.7.4 多块解密​

多块解密验证步骤如下。

  1. a） 验证目的：验证是否能正确进行多块数据解密运算。
  2. b） 验证条件：初始化环境函数 SAF_Initialize、用户登录函数 SAF_Login、创建对称算法对象 SAF_CreateSymmAlgoObj 已经成功调用，会话密钥已生成或已导入或已协商。
  3. c） 验证过程：
    1. 1） 正常情况验证：

      步骤1：调用 SAF_SymmDecryptUpdate 接口，对多个预定密文数据分组进行解密，返回明文数据；

      步骤2：调用 SAF_SymmDecryptFinal 接口结束解密，得到明文数据。

    2. 2） 异常情况验证：使用非法参数调用上述接口，应返回错误码；

      不执行步骤1，直接执行步骤2应返回错误码。

  4. d） 验证结果：
    1. 1） 正常情况验证：步骤1和步骤2返回的解密明文与预定明文一致。步骤1和步骤2中设置 pucOutData = NULL 时，应能通过 puiOutDataLen 返回结果数据实际长度。
    2. 2） 异常情况验证：得到预期结果。

7.8 生成密钥对验证​

生成密钥对验证步骤如下。

  1. a） 验证目的：验证是否能正确生成符合 GB/T 35276的 SM2密钥对。
  2. b） 验证条件：无。
  3. c） 验证过程：
    1. 1） 正常情况验证：

      步骤1：调用 SAF_Initialize 接口初始化环境；

      步骤2：调用 SAF_Login 接口进行用户登录；

      步骤3：调用 SAF_GenSm2KeyPair 接口生成 SM2密钥对；

      步骤4：调用 SAF_GetSm2PublicKey 接口取出SM2公钥；

      步骤5：调用 SAF_Logout 接口注销用户登录；

      步骤6：调用 SAF_Finalize 接口清除环境。

    2. 2） 异常情况验证：步骤1、2、3中输入异常参数，应返回错误码。
  4. d） 验证结果：
    1. 1） 正常情况验证：取出的SM2公钥内容应为 GB/T 35276 定义的SM2PublicKey，采用 ASN.1 DER 编码后进行 Base64 编码；公钥内容经验证有效，验证方法应按照 GB/T 32918.1定义公钥内容验证。
    2. 2） 异常情况验证：得到预期结果。

7.9 PKCS#7运算验证​

7.9.1 编码 PKCS＃7格式的带签名的数据签名信封​

编码 PKCS#7格式的带签名的数据签名信封验证步骤如下。

  1. a） 验证目的：验证是否能正确进行 PKCS #7格式的带签名的数字信封编码运算。
  2. b） 验证条件：无。
  3. c） 验证过程：
    1. 1） 正常情况验证：调用SAF_Pkcs7_EncodeData 接口，对预定数据进行 PKCS ＃7格式的带签名的数字信封编码运算。
    2. 2） 异常情况验证：使用非法参数调用本接口，应返回错误码。
  4. d） 验证结果：
    1. 1） 正常情况验证：计算得到的结果值应与预定结果一致。
    2. 2） 异常情况验证：得到预期结果。

7.9.2 解码 PKCS#7格式的带签名的数据签名信封​

解码 PKCS#7格式的带签名的数据签名信封验证步骤如下。

  1. a） 验证目的：验证是否能正确进行 PKCS ＃7格式的带签名的数字信封解码运算。
  2. b） 验证条件：无。
  3. c） 验证过程：
    1. 1） 正常情况验证：调用 SAF_Pkcs7_DecodeData 接口，对预定数据进行 PKCS ＃7格式的带签名的数字信封解码运算。
    2. 2） 异常情况验证：使用非法参数调用本接口，应返回错误码。
  4. d） 验证结果：
    1. 1） 正常情况验证：计算得到的结果值应与预定结果一致。
    2. 2） 异常情况验证：得到预期结果。

7.10 SM2消息类运算验证​

7.10.1 编码基于SM2算法的带签名的数字信封​

编码基于 SM2算法的带签名的数字信封验证步骤如下。

  1. a） 验证目的：验证是否能正确进行 SM2算法的带签名的数字信封编码运算。
  2. b） 验证条件：无。
  3. c） 验证过程：
    1. 1） 正常情况验证：调用 SAF_SM2_EncodeSignedAndEnvelopedData 接口，对预定数据进行 SM2 的带签名的数字信封编码运算。
    2. 2） 异常情况验证：使用非法参数调用本接口，应返回错误码。
  4. d） 验证结果：
    1. 1） 正常情况验证：计算得到的结果值应与预定结果一致。
    2. 2） 异常情况验证：得到预期结果。

7.10.2 解码基于SM2 算法的带签名的数据信封​

解码基于SM2算法的带签名的数据信封验证步骤如下。

  1. a） 验证目的：验证是否能正确进行基于 SM2算法的带签名的数字信封解码运算。
  2. b） 验证条件：无。
  3. c） 验证过程：
    1. 1） 正常情况验证：调用 SAF_SM2_DecodeSignedAndEnvelopedData 接口，对预定数据进行进行基于 SM2算法的带签名的数字信封解码运算。
    2. 2） 异常情况验证：使用非法参数调用本接口，应返回错误码。
  4. d） 验证结果：
    1. 1） 正常情况验证：计算得到的结果值应与预定结果一致。
    2. 2） 异常情况验证：得到预期结果。

7.11 Base64 编码验证​

7.11.1 创建 Base64 对象​

创建 Base64 对象验证步骤如下。

  1. a） 验证目的：验证是否能正确创建 Base 对象。
  2. b） 验证条件：无。
  3. c） 验证过程：
    1. 1） 正常情况验证：调用 SAF_Base64_CreateBase64Obj 接口，为任意长度数据的 Base64 编解码创建 Base64 对象。
    2. 2） 异常情况验证：使用非法参数调用本接口，应返回错误码。
  4. d） 验证结果：
    1. 1） 正常情况验证：计算得到的结果值应与预定结果一致。
    2. 2） 异常情况验证：得到预期结果。

7.11.2 Base64 编码​

Base64 编码验证步骤如下。

  1. a） 验证目的：验证是否能正确进行 Base64 编码。
  2. b） 验证条件：正确创建 Base64 对象。
  3. c） 验证过程：
    1. 1） 正常情况验证：调用 SAF_Base64_Encode 接口，对预定数据进行 Base64编码运算。
    2. 2） 异常情况验证：使用非法参数调用本接口，应返回错误码。
  4. d） 验证结果：
    1. 1） 正常情况验证：计算得到的结果值应与预定结果一致。
    2. 2） 异常情况验证：得到预期结果。

7.11.3 Base64 解码​

Base64 解码验证步骤如下。

  1. a） 验证目的：验证是否能正确进行 Base64 解码。
  2. b） 验证条件：正确创建 Base64 对象。
  3. c） 验证过程：
    1. 1） 正常情况验证：调用 SAF_Base64_Decode 接口，对预定数据进行Base64 编码运算。
    2. 2） 异常情况验证：使用非法参数调用本接口，应返回错误码。
  4. d） 验证结果：
    1. 1） 正常情况验证：计算得到的结果值应与预定结果一致。
    2. 2） 异常情况验证：得到预期结果。

附录 A（资料性）​

通用密码服务接口函数汇总​

本附录对第 6 章定义的通用密码服务接口函数进行汇总，见表 A.1。

表A.1 通用密码服务接口函数汇总

类别序号章节号接口名称功能
环境类16.2.2SAF_Initialize初始化环境
环境类26.2.3SAF_Finalize清除环境
环境类36.2.4SAF_GetVersion获取接口版本信息
环境类46.2.5SAF_Login用户登录
环境类56.2.6SAF_ChangePin修改口令
环境类66.2.7SAF_Logout注销登录
证书类76.3.2SAF_AddTrustedRootCaCertificate添加根 CA 证书
证书类86.3.3SAF_GetRootCaCertificateCount获取根 CA 证书个数
证书类96.3.4SAF_GetRootCaCertificate获取根 CA 证书
证书类106.3.5SAF_RemoveRootCaCertificate删除根 CA 证书
证书类116.3.6SAF_AddCaCertificate添加 CA 证书
证书类126.3.7SAF_GetCaCertificateCount获取 CA 证书个数
证书类136.3.8SAF_GetCaCertificate获取 CA 证书
证书类146.3.9SAF_RemoveCaCertificate删除 CA 证书
证书类156.3.10SAF_AddCrl添加 CRL
证书类166.3.11SAF_VerifyCertificate验证用户证书
证书类176.3.12SAF_VerifyCertificateByCrl根据 CRL 文件获取用户证书注销状态
证书类186.3.13SAF_GetCertificateStateByOCSP根据 OCSP 获取用户证书注销状态
证书类196.3.14SAF_GetCertificateFromLdap通过 LDAP 方式获取证书
证书类206.3.15SAF_GetCrlFromLdap通过 LDAP 方式获取证书对应的 CRL
证书类216.3.16SAF_GetCertificateInfo取证书信息
证书类226.3.17SAF_GetExtTypeInfo取证书扩展信息
证书类236.3.18SAF_EnumCertificates列举用户证书
证书类246.3.19SAF_EnumKeyContainerInfo列举用户的密钥容器信息
证书类256.3.20SAF_EnumCertificatesFree释放列举用户证书的内存
证书类266.3.21SAF_EnumkeyContainerInfoFree释放列举密钥容器信息的内存
密码运算类276.4.2SAF_Base64_Encode单块 Base64 编码
密码运算类286.4.3SAF_Base64_Decode单块 Base64 解码
密码运算类296.4.4SAF_Base64_CreateBase64Obj创建 Base64 对象
密码运算类306.4.5SAF_Base64_DestroyBase64Obj销毁 Base64 对象
密码运算类316.4.6SAF_Base64_EncodeUpdate通过 Base64 对象多块编码
密码运算类326.4.7SAF_Base64_EncodeFinal通过 Base64 对象编码结束
密码运算类336.4.8SAF_Base64_DecodeUpdate通过 Base64 对象多块解码
密码运算类346.4.9SAF_Base64_DecodeFinal通过 Base64 对象解码结束
密码运算类356.4.10SAF_GenRandom生成随机数
密码运算类366.4.11SAF_HashHASH 运算
密码运算类376.4.12SAF_CreateHashObj创建 HASH 对象
密码运算类386.4.13SAF_DestroyHashObj删除 HASH 对象
密码运算类396.4.14SAF_HashUpdate通过对象进行多块 HASH 运算
密码运算类406.4.15SAF_HashFinal结束 HASH 运算
密码运算类416.4.16SAF_GenRsaKeyPair生成 RSA 密钥对
密码运算类426.4.17SAF_GetRsaPublicKey获取 RSA 公钥
密码运算类436.4.18SAF_RsaSignRSA 签名运算
密码运算类446.4.19SAF_RsaSignFile对文件进行 RSA 签名运算
密码运算类456.4.20SAF_RsaVerifySignRSA 验证签名运算
密码运算类466.4.21SAF_RsaVerifySignFile对文件及其签名进行 RSA 验证
密码运算类476.4.22SAF_VerifySignByCert基于证书的 RSA 公钥验证
密码运算类486.4.23SAF_GenSm2KeyPair生成 SM2 密钥对
密码运算类496.4.24SAF_GetSm2PublicKey获取 SM2 公钥
密码运算类506.4.25SAF_Sm2SignSM2 签名
密码运算类516.4.26SAF_Sm2VerifySignSM2 验证
密码运算类526.4.27SAF_Sm2PublicKeyEncSM2 公钥加密
密码运算类536.4.28SAF_Sm2PublicKeyEncByCert基于证书的 SM2 公钥加密
密码运算类546.4.29SAF_Sm2PublicKeyDecByCert基于证书的 SM2 公钥解密
密码运算类556.4.30SAF_Sm2VerifySignByCert基于证书的 SM2 公钥验证
密码运算类566.4.31SAF_CreateSymmAlgoObj创建对称算法对象
密码运算类576.4.32SAF_GenerateKeyWithEPK生成会话密钥并用外部公钥加密输出
密码运算类586.4.33SAF_ImportEncedKey导入加密的会话密钥
密码运算类596.4.34SAF_GenerateAgreementDataWithSM2生成密钥协商参数并输出
密码运算类606.4.35SAF_GenerateKeyWithSM2计算会话密钥
密码运算类616.4.36SAF_GenerateAgreementDataAndKeyWithSM2产生协商数据并计算会话密钥
密码运算类626.4.37SAF_DestroySymmAlgoObj销毁对称算法对象
密码运算类636.4.38SAF_DestroyKeyHandle销毁会话密钥句柄
密码运算类646.4.39SAF_SymmEncrypt单块加密运算
密码运算类656.4.40SAF_SymmEncryptUpdate多块加密运算
密码运算类666.4.41SAF_SymmEncryptFinal结束加密运算
密码运算类676.4.42SAF_SymmDecrypt单块解密运算
密码运算类686.4.43SAF_SymmDecryptUpdate多块解密运算
密码运算类696.4.44SAF_SymmDecryptFinal结束解密运算
密码运算类706.4.45SAF_Mac单组数据消息鉴别码运算
密码运算类716.4.46SAF_MacUpdate多组数据消息鉴别码运算
密码运算类726.4.47SAF_MacFinal结束消息鉴别码运算
消息类736.5.2SAF_Pkcs7_EncodeData编码 PKCS #7 格式的带签名的数字信封数据
消息类746.5.3SAF_Pkcs7_DecodeData解码 PKCS #7 格式的带签名的数字信封数据
消息类756.5.4SAF_Pkcs7_EncodeSignedData编码 PKCS #7 格式的签名数据
消息类766.5.5SAF_Pkcs7_DecodeSignedData解码 PKCS #7 格式的签名数据
消息类776.5.6SAF_Pkcs7_EncodeEnvelopedData编码 PKCS #7 格式的数字信封数据
消息类786.5.7SAF_Pkcs7_DecodeEnvelopedData解码 PKCS #7 格式的数字信封数据
消息类796.5.8SAF_Pkcs7_EncodeDigestedData编码 PKCS #7 格式的摘要数据
消息类806.5.9SAF_Pkcs7_DecodeDigestedData解码 PKCS #7 格式的摘要数据
消息类816.5.10SAF_SM2_EncodeSignedAndEnvelopedData编码基于 SM2 算法的带签名的数字信封数据
消息类826.5.11SAF_SM2_DecodeSignedAndEnvelopedData解码基于 SM2 算法的带签名的数字信封数据
消息类836.5.12SAF_SM2_EncodeSignedData编码基于 SM2 算法的签名数据
消息类846.5.13SAF_SM2_DecodeSignedData解码基于 SM2 算法的签名数据
消息类856.5.14SAF_SM2_EncodeEnvelopedData编码基于 SM2 算法的数字信封
消息类866.5.15SAF_SM2_DecodeEnvelopedData解码基于 SM2 算法的数字信封
消息类876.5.16SAF_Parse_Pkcs7_SignedData解析 PKCS #7 格式的签名数据

附录 B（规范性）​

SM9 密码算法数据结构和接口函数​

B.1 SM9 算法相关数据结构​

B.1.1 SM9 主私钥数据结构​

SM9 主私钥数据结构应符合表 B.1 的规定。

表B.1 SM9主私钥数据结构

字段名称数据长度（字节）含义
bits4模数的实际位长度
sSM9ref_MAX_LEN主私钥

C 语言的数据结构定义：

#define SM9ref_MAX_BITS 256
#define SM9ref_MAX_LEN ((SM9ref_MAX_BITS + 7) / 8)
typedef struct SM9refMasterPrivateKey_st
{
    ULONG bits;
    BYTE s[SM9ref_MAX_LEN];
} SM9MasterPrivateKey;

备注：SM9 主私钥类型用于 SM9 签名主私钥和 SM9 加密主私钥。

B.1.2 SM9 签名主公钥数据结构​

SM9 签名主公钥数据结构应符合表 B.2 的规定。

表B.2 SM9 签名主公钥数据结构

字段名称数据长度（字节）含义
bits4模数的实际位长度
xaSM9ref_MAX_LEN曲线上点 X坐标高维
xbSM9ref_MAX_LEN曲线上点 X 坐标低维
yaSM9ref_MAX_LEN曲线上点 Y 坐标高维
ybSM9ref_MAX_LEN曲线上点 Y 坐标低维

C 语言的数据结构定义：

typedef struct SM9refSignMasterPublicKey_st
{
    ULONG bits;
    BYTE xa[SM9ref_MAX_LEN];
    BYTE xb[SM9ref_MAX_LEN];
    BYTE ya[SM9ref_MAX_LEN];
    BYTE yb[SM9ref_MAX_LEN];
} SM9SignMasterPublicKey;
B.1.3 SM9 加密主公钥数据结构​

SM9 加密主公钥数据结构应符合表 B.3 的规定。

表B.3 SM9加密主公钥数据结构

字段名称数据长度（字节）含义
bits4模数的实际位长度
xSM9ref_MAX_LEN曲线上点 X 坐标
ySM9ref_MAX_LEN曲线上点 Y 坐标

C 语言的数据结构定义：

typedef struct SM9refEncMasterPublicKey_st
{
    ULONG bits;
    BYTE x[SM9ref_MAX_LEN];
    BYTE y[SM9ref_MAX_LEN];
} SM9EncMasterPublicKey;
B.1.4 SM9 用户签名私钥数据结构​

SM9 用户签名私钥数据结构应符合表 B.4 的规定。

表B.4 SM9用户签名私钥数据结构

字段名称数据长度（字节）含义
bits4模数的实际位长度
xSM9ref_MAX_LEN曲线上点 X 坐标
ySM9ref_MAX_LEN曲线上点 Y 坐标

C 语言的数据结构定义：

typedef struct SM9refSignUserPrivateKey_st
{
    ULONG bits;
    BYTE x[SM9ref_MAX_LEN];
    BYTE y[SM9ref_MAX_LEN];
} SM9SignUserPrivateKey;
B.1.5 SM9 用户加密私钥数据结构​

SM9 用户加密私钥数据结构应符合表 B.5 的规定。

表B.5 SM9用户加密私钥数据结构

字段名称数据长度（字节）含义
bits4模数的实际位长度
xaSM9ref_MAX_LEN曲线上点 X坐标高维
xbSM9ref_MAX_LEN曲线上点 X 坐标低维
yaSM9ref_MAX_LEN曲线上点 Y 坐标高维
ybSM9ref_MAX_LEN曲线上点 Y 坐标低维

C 语言的数据结构定义：

typedef struct SM9refEncUserPrivateKey_st
{
    ULONG bits;
    BYTE xa[SM9ref_MAX_LEN];
    BYTE xb[SM9ref_MAX_LEN];
    BYTE ya[SM9ref_MAX_LEN];
    BYTE yb[SM9ref_MAX_LEN];
} SM9EncUserPrivateKey;
B.1.6 SM9 加密数据结构​

SM9 加密数据结构应符合表 B.6 的规定。

表 B.6 SM9加密数据结构

字段名称数据长度（字节）含义
EncType4SM9 加密算法机
xSM9ref_MAX_LEN椭圆曲线上点 X 坐标
ySM9ref_MAX_LEN椭圆曲线上点 Y 坐标
h32MAC 值
L4密文数据长度
CL密文数据

C 语言的数据结构定义：

typedef struct SM9refCipher_st
{
    ULONG encType;
    BYTE x[SM9ref_MAX_LEN];
    BYTE y[SM9ref_MAX_LEN];
    BYTE h[32];
    ULONG L;
    BYTE C[1]
} SM9Cipher;
B.1.7 SM9 签名数据结构​

SM9 签名数据结构应符合表 B.7 的规定。

表B.7 SM9签名数据结构

字段名称数据长度（字节）含义
hSM9ref_MAX_LEN签名结果的H部分
xSM9ref_MAX_LEN曲线上点的 X 坐标
ySM9ref_MAX_LEN曲线上点的 Y 坐标

C 语言的数据结构定义：

typedef struct SM9refSignature_st
{
    BYTE h[SM9ref_MAX_LEN];
    BYTE x[SM9ref_MAX_LEN];
    BYTE y[SM9ref_MAX_LEN];
} SM9Signature;
B.1.8 SM9 密钥封装数据结构​

SM9 密钥封装数据结构应符合表 B.8 的规定。

表 B.8 SM9密钥封装数据结构

字段名称数据长度（字节）含义
xSM9ref_MAX_LEN封装的交换密文曲线上点 X 坐标
ySM9ref_MAX_LEN封装的交换密文曲线上点 Y 坐标

C 语言的数据结构定义：

typedef struct SM9refKeyPackage_st
{
    BYTE x[SM9ref_MAX_LEN];
    BYTE y[SM9ref_MAX_LEN];
} SM9KeyPackage;
B.1.9 SM9 用户加密密钥对保护结构​

SM9 用户加密密钥对保护结构应符合表 B.9 的规定。

表B.9 SM9用户加密密钥对保护结构

字段名称数据长度（字节）含义
version4版本号
ulSymmAlgID4对称算法标识，限定 ECB 模式
bits4用户加密密钥对的密钥位长
encryptedPriKeySM9ref_MAX_LEN * 4对称算法加密的密文，加密的原文为：SM9EncUserPrivateKey 结构体中除去长度的剩余部分
encMasterPubKeySM9EncMastPublicKey 类型KGC 的加密主公钥
tmpMasterPubKeySM9EncMastPublicKey 类型产生对称密钥的密钥封装数据的主公钥
userIDLen4用户标识长度
userID1024用户标识，实际有效长度为 userIDLen
keyLen4对称密钥比特位数
keyPackageSM9KeyPackage 类型加密用户加密私钥的对称密钥的密钥封装数据

C 语言的数据结构定义：

typedef struct SM9refEncEnvelopedKey_st
{
    ULONG version;
    ULONG ulSymmAlgID;
    ULONG bits;
    BYTE encryptedPriKey[SM9ref_MAX_LEN * 4];
    SM9EncMastPublicKey encMastPubKey;
    SM9EncMastPublicKey tmpMastPubKey;
    ULONG userIDLen;
    BYTE userID[256];
    ULONG keyLen;
    SM9KeyPackage keyPackage;
} SM9EncEnvelopedKey;
B.1.10 SM9 用户签名密钥对保护结构​

SM9 用户签名密钥对保护结构应符合表 B.10 的规定。

表B.10 SM9用户签名密钥对保护结构C语言的数据结构定义

字段名称数据长度（字节）含义
version4版本号
ulSymmAlgID4对称算法标识，限定 ECB 模式
bits4用户加密密钥对的密钥位长
encryptedPriKeySM9ref_MAX_LEN * 2对称算法加密的密文，加密的原文为：SM9SignUserPrivateKey 结构体中除去长度的剩余部分
signMasterPubKeySM9SignMastPublicKey 类型KGC 的签名主公钥
tmpMasterPubKeySM9EncMastPublicKey 类型产生对称密钥的密钥封装数据的主公钥
userIDLen4用户标识长度
userID256用户标识，实际有效长度为 userIDLen
keyLen4对称密钥比特位数
keyPackageSM9KeyPackage类型加密用户加密私钥的对称密钥的密钥封装数据
typedef struct SM9refSignEnvelopedKey_st
{
    ULONG version;
    ULONG ulSymmAlgID; // 对称算法标识，限定 ECB 模式
    ULONG bits;
    BYTE encryptedPriKey[SM9ref_MAX_LEN * 4];
    SM9SignMastPublicKey signMastPubKey;
    SM9EncMastPublicKey tmpMastPubKey;
    ULONG userIDLen;
    BYTE userID[256];
    ULONG keyLen; SM9KeyPackage keyPackage;
} SM9SignEnvelopedKey;

B.2 SM9 算法接口函数​

B.2.1 导入 SM9 主公钥​

导入 SM9 主公钥的函数定义应符合表 B.11 的规定。

表B.11 导入SM9主公钥的函数定义

项目内容
原型int SAF_ImportSM9MasterPublicKey(void * hAppHandle, unsigned int uiKeyIndex, unsigned int uiKeyType, unsigned char * pucMasterPublickKey, unsigned int uiMasterPublickKeyLen)
描述导入 SM9 主公钥到指定索引
参数hAppHandle[in]（应用接口句柄）
uiKeyIndex[in]（主公钥导入索引）
uiKeyType[in]（主公钥类型：1：签名主公钥；2：加密主公钥）
pucMasterPublickKey[in]（DER 编码的主公钥数据）
uiMasterPublickKeyLen[in]（DER 编码的主公钥数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
B.2.2 导入 SM9 用户密钥对​

导入 SM9 用户密钥对的函数定义应符合表 B.12 的规定。

表B.12 导入SM9用户密钥对的函数定义

项目内容
原型int SAF_ImportSM9UserKey(void * hAppHandle, unsigned char * pucContainerName, unsigned int uiContainerLen, unsigned int uiKeyType, unsigned char * pUserKey, unsigned int uiUserKeyLen);
描述导入SM9用户标识和密钥到指定密钥容器
参数hAppHandle[in]（应用接口句柄）
pucContainerName[in]（密钥容器名）
uiContainerLen[in]（密钥容器名长度）
uiKeyType[in]（用户密钥保护结构类型：1：签名密钥密钥封装保护结构；2：签名密钥数字信封保护结构；3：加密密钥密钥封装保护结构；4：加密密钥数字信封保护结构）
pUserKey[in]（DER 编码的用户密钥保护结构数据）
uiUserKeyLen[in]（DER 编码的用户密钥保护结构数据长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
B.2.3 SM9 签名​

SM9 签名的函数定义应符合表 B.13 的规定。

表 B.13 SM9签名的函数定义

项目内容
原型int SAF_SM9Sign(void * hAppHandle, unsigned char * pucContainerName, unsigned int uiContainerLen, unsigned int uiMasterPublicKeyIndex, unsigned char * pucData, unsigned int uiDataLength, unsigned char * pucSignData, unsigned int * puiSignDataLen);
规则使用 SM9签名私钥对数据进行签名运算，SM9运算过程应遵循 GB/T 41389
参数hAppHandle[in]（应用接口句柄）
pucContainerName[in]（密钥容器名）
uiContainerLen[in]（密钥容器名长度）
uiMasterPublicKeyIndex[in]（签名主公钥的索引值）
pucData[in]（待签名数据的 SM3 杂凑值）
uiDataLength[in]（待签名数据的 SM3 杂凑值长度，值为 32）
pucSignData[out]（缓冲区指针，输出为 DER 编码的签名值数据）
puiSignDataLen[in,out]（输入为签名值数据缓冲区长度，输出为签名值数据实际长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
B.2.4 SM9 签名验证​

SM9 签名验证的函数定义应符合表 B.14 的规定。

表B.14 SM9 签名验证的函数定义

项目内容
原型int SAF_SM9Verify(void * hAppHandle, unsigned int uiMasterPublicKeyIndex, unsigned char * pucUserID, unsigned int uiUserIDLen, unsigned char * pucData, unsigned int uiDataLength, unsigned char * pucSignData, unsigned int uiSignDataLen);
规则使用SM9用户标识和签名主公钥对数据进行签名验证运算，SM9运算过程应遵循 GB/T 41389
参数hAppHandle[in]（应用接口句柄）
uiMasterPublicKeyIndex[in]（签名主公钥的索引值）
pucUserID[in]（DER 编码的用户标识数据）
uiUserIDLen[in]（DER 编码的用户标识数据长度）
pucData[in]（被签名数据的 SM3 杂凑值）
uiDataLength[in]（被签名数据的 SM3 杂凑值长度，值为 32）
pucSignData[in]（DER 编码的签名值数据）
uiSignDataLen[in]（DER 编码的签名值数据长度）
返回值0（成功，签名验证通过）
非 0（失败，返回表 C.1 定义的错误代码，应符合附录 C 的规定）
B.2.5 SM9 密钥封装​

SM9 密钥封装的函数定义应符合表 B.15 的规定。

表 B.15 SM9密钥封装的函数定义

项目内容
原型int SAF_SM9KeyEncapsulate(void * hSymmKeyObj, unsigned int uiMasterPublicKeyIndex, unsigned char * pucUserID, unsigned int uiUserIDLen, unsigned int uiKeyBits unsigned char * pucKeyPackage unsigned int * pulKeyPackageLen, void * * phKeyHandle);
规则使用SM9用户标识和签名主公钥进行密钥封装运算，SM9运算过程应遵循 GB/T 41389
参数hSymmKeyObj[in]（对称算法对象）
uiMasterPublicKeyIndex[in]（加密主公钥的索引值）
pucUserID[in]（DER 编码的用户标识数据）
uiUserIDLen[in]（DER 编码的用户标识数据长度）
uiKeyBits[in]（封装密钥的位长度）
pucKeyPackage[out]（缓冲区指针，输出 DER 编码的密钥封装数据）
pulKeyPackageLen[in,out]（输入为密钥封装数据缓冲区长度，输出为 DER 编码的密钥封装数据实际长度）
phKeyHandle[out]（输出会话密钥的句柄）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
B.2.6 SM9 密钥解封装​

SM9 密钥解封装的函数定义应符合表 B.16 的规定。

表B.16 SM9 密钥解封装的函数定义

项目内容
原型int SAF_SM9KeyDecapsulate(void * hSymmKeyObj, unsigned int uiKeyBits unsigned char * pucKeyPackage unsigned int ulKeyPackageLen, void * * phKeyHandle);
规则使用 SM9用户密钥进行密钥解封装运算，SM9运算过程应遵循 GB/T 41389
参数hSymmKeyObj[in]（对称算法对象）
pucUserID[in]（DER 编码的用户标识数据）
uiUserIDLen[in]（DER 编码的用户标识数据长度）
uiKeyBits[in]（封装密钥的位长度）
pucKeyPackage[in]（DER 编码的密钥封装数据）
ulKeyPackageLen[in]（DER 编码的密钥封装数据长度）
phKeyHandle[out]（输出会话密钥的句柄）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
B.2.7 SM9 加密​

SM9 加密的函数定义应符合表 B.17 的规定。

表 B.17 SM9 加密的函数定义

项目内容
原型int SAF_SM9Encrypt(void * hAppHandle, unsigned int uiMasterPublicKeyIndex, unsigned char * pucUserID, unsigned int uiUserIDLen, unsigned int ulAlgID, unsigned char * pIV, unsigned int ulIVLen, unsigned char * pucData, unsigned int uiDataLength, unsigned char * pucEncData, unsigned int * pulEncDataLen);
规则使用SM9用户标识对数据进行加密运算，SM9运算过程应遵循GB/T 41389
参数hAppHandle[in]（应用接口句柄）
uiMasterKeyIndex[in]（加密主公钥的索引值）
pucUserID[in]（DER 编码的用户标识数据）
uiUserIDLen[in]（DER 编码的用户标识数据长度）
ulAlgID[in]（SM9 加密算法标识）
pIV[in]（IV 数据，若为 NULL，则由密码设备产生）
ulIVLen[in]（IV 数据长度）
pucData[in]（待加密数据）
uiDataLength[in]（待加密数据长度）
pucEncData[out]（缓冲区指针，用于存放输出 DER 编码的密文数据）
pulEncDataLen[in,out]（输入为缓冲区长度，输出为 DER 编码的密文数据实际长度）
返回值0（成功）
非 0（失败，返回表 C.1 定义的错误代码，应符合附录 C 的规定）
B.2.8 SM9 解密​

SM9 解密的函数定义应符合表 B.18 的规定。

表 B.18 SM9 解密的函数定义

项目内容
原型int SAF_SM9Decrypt(void * hAppHandle, unsigned char * pucContainerName, unsigned int uiContainerLen, unsigned char * pucEncData, unsigned int ulEncDataLen, unsigned char * pucData, unsigned int * puiDataLength);
规则使用 SM9用户加密密钥对（包括用户私钥和用户标识）对数据进行解密运算，SM9运算过程应遵循 GB/T 41389
参数hAppHandle[in]（应用接口句柄）
pucContainerName[in]（密钥容器名）
uiContainerLen[in]（密钥容器名长度）
pucEncData[in]（DER 编码的密文数据）
ulEncDataLen[in]（DER 编码的密文数据长度）
pucData[out]（缓冲区指针，用于存放解密数据）
puiDataLength[in,out]（输入为缓冲区长度，输出为解密数据实际长度）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
B.2.9 生成密钥协商参数并输出​

生成密钥协商参数并输出的函数定义应符合表 B.19 的规定。

表B.19 生成密钥协商参数并输出的函数定义

项目内容
原型int SAF_SM9GenerateAgreementData(void * hSymmKeyObj, unsigned int uiMasterPublicKeyIndex, unsigned int uiKeyBits, unsigned char * pucResponsorID, unsigned int uiResponsorIDLen, unsigned char * pucSponsorTmpPublicKey, unsigned int * puiSponsorTmpPublicKeyLen, void * * phAgreementHandle);
规则使用SM9密钥协商算法，为计算会话密钥而产生协商参数，同时返回发起方临时 SM9密钥对的公钥及协商句柄，SM9运算过程应遵循GB/T 41389。为协商会话密钥，协商的发起方应首先调用本函数计算会话密钥
参数hSymmKeyObj[in]（对称算法对象）
uiMasterKeyIndex[in]（加密主公钥的索引值）
uiKeyBits[in]（要求协商的密钥长度）
pucResponsorID[in]（DER 编码的响应方标识）
uiResponsorIDLen[in]（DER 编码的响应方标识长度）
pucSponsorTmpPublicKey[out]（缓冲区指针，用于保存返回的 DER 编码的发起方临时公钥）
puiSponsorTmpPublicKeyLen[in,out]（输入为缓冲区长度，输出为返回的 DER 编码的发起方临时公钥实际长度）
phAgreementHandle[out]（返回的密钥协商句柄）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
B.2.10 计算会话密钥​

计算会话密钥的函数定义应符合表 B.20 的规定。

表B.20 计算会话密钥的函数定义

项目内容
原型int SAF_SM9GenerateKey(void * hAgreementHandle, unsigned char * pucResponseTmpPublicKey, unsigned int uiResponseTmpPublicKeyLen, void * * phKeyHandle);
规则使用 SM9密钥协商算法，使用自身协商句柄和响应方的协商参数计算会话密钥，同时返回会话密钥句柄，SM9运算过程应遵循 GB/T 41389
参数hAgreementHandle[in]（密钥协商句柄）
pucResponseTmpPublicKey[in]（外部输入的 DER 编码的响应方临时公钥）
uiResponseTmpPublicKeyLen[in]（外部输入的 DER 编码的响应方临时公钥长度）
phKeyHandle[out]（返回的密钥句柄）
返回值0（成功）
非 0（失败，返回表 C.1 定义的错误代码，应符合附录 C 的规定）
备注协商的发起方获得响应方的协商参数后调用本函数，计算会话密钥
B.2.11 产生协商数据并计算会话密钥​

产生协商数据并计算会话密钥的函数定义应符合表 B.21 的规定。

表 B.21 产生协商数据并计算会话密钥的函数定义

项目内容
原型int SAF_SM9GenerateAgreementDataAndKey(void * hSymmKeyObj, unsigned int uiMasterPublicKeyIndex, unsigned int uiKeyBits, unsigned char * pucSponsorID, unsigned int uiSponsorIDLength, unsigned char * pucSponsorTmpPublicKey, unsigned int * puiSponsorTmpPublicKeyLen, unsigned char * pucResponseTmpPublicKey, unsigned int uiResponseTmpPublicKeyLen, void * * phKeyHandle);
规则使用 SM9密钥协商算法，产生协商参数并计算会话密钥，同时返回产生的协商参数和密钥句柄，SM9运算过程应遵循 GB/T 41389
参数hSymmKeyObj[in]（对称算法对象）
uiMasterKeyIndex[in]（加密主公钥的索引值）
uiKeyBits[in]（要求协商的密钥长度）
pucSponsorID[in]（DER 编码的发起方标识）
uiSponsorIDLength[in]（DER 编码的发起方标识长度）
pucSponsorTmpPublicKey[in]（外部输入的 DER 编码的发起方临时公钥）
puiSponsorTmpPublicKeyLen[in]（外部输入的 DER 编码的发起方临时公钥长度）
pucResponseTmpPublicKey[in]（缓冲区指针，用于保存返回的 DER 编码的响应方临时公钥）
uiResponseTmpPublicKeyLen[in,out]（输入为缓冲区长度，输出为返回的 DER 编码的响应方临时公钥实际长度）
phKeyHandle[out]（返回的密钥句柄）
返回值0（成功）
非0（失败，返回表C.1定义的错误代码，应符合附录C的规定）
备注本函数由响应方调用

附录 C（规范性）​

通用密码服务接口错误代码定义​

通用密码服务接口错误代码定义见表 C.1。

表C.1 错误代码定义

宏描述预定义值说明
SAR_OK0成功
SAR_UnknownErr0X02000001异常错误
SAR_NotSupportYetErr0X02000002不支持的服务
SAR_FileErr0X02000003文件操作错误
SAR_ProviderTypeErr0X02000004服务提供者参数类型错误
SAR_LoadProviderErr0X02000005导入服务提供者接口错误
SAR_LoadDevMngApiErr0X02000006导入设备管理接口错误
SAR_AlgoTypeErr0X02000007算法类型错误
SAR_NameLenErr0X02000008名称长度错误
SAR_KeyUsageErr0X02000009密钥用途错误
SAR_ModulusLenErr0X02000010模的长度错误
SAR_NotInitializeErr0X02000011未初始化
SAR_ObjErr0X02000012对象错误
SAR_MemoryErr0X02000100内存错误
SAR_TimeoutErr0X02000101超时
SAR_IndataLenErr0X02000200输入数据长度错误
SAR_IndataErr0X02000201输入数据错误
SAR_GenRandErr0X02000300生成随机数错误
SAR_HashObjErr0X02000301HASH 对象错
SAR_HashErr0X02000302HASH 运算错误
SAR_GenRsaKeyErr0X02000303产生 RSA 密钥错
SAR_RsaModulusLenErr0X02000304RSA 密钥模长错误
SAR_CspImprtPubKeyErr0X02000305CSP 服务导入公钥错误
SAR_RsaEncErr0X02000306RSA 加密错误
SAR_RSGDecErr0X02000307RSA 解密错误
SAR_HashNotEqualErr0X02000308HASH 值不相等
SAR_KeyNotFountErr0X02000309密钥未发现
SAR_CertNotFountErr0X02000310证书未发现
SAR_NotExportErr0X02000311对象未导出
SAR_CertNotYetValidErr0X02000317证书未生效
SAR_CertHasExpiredErr0X02000318证书已过期
SAR_CertVerifyErr0X02000319证书验证错误
SAR_CertEncodeErr0X02000320证书编码错误
SAR_DecryptPadErr0X02000400解密时做补丁错误
SAR_MacLenErr0X02000401MAC 长度错误
SAR_KeyInfoTypeErr0X02000402密钥类型错误
SAR_NotLogin0X02000403没有进行登录认证
SAR_KeyCompromise0X02000404证书被吊销原因：密钥泄露
SAR_CACompromise0X02000405证书被吊销原因：CA 泄露
SAR_AffiliationChanged0X02000406证书被吊销原因：隶属关系已修改
SAR_Superseded0X02000407证书被吊销原因：被替代
SAR_CessationOfOperation0X02000408证书被吊销原因：被终止
SAR_CertificateHold0X02000409证书被吊销原因：证书挂起
SAR_PrivilegeWithdrawn0X02000410证书被吊销原因：证书特权被撤销
SAR_Sm9MasterKeyErr0X02000500SM9 主密钥错误
SAR_Sm9UserKeyErr0X02000501SM9 用户密钥错误
SAR_Sm9VerifyErr0X02000502SM9 签名验证失败
SAR_Sm9KeyExchangeErr0X02000503SM9 密钥协商失败
SAR_Sm9DecapsulateErr0X02000504SM9 密钥解封装失败
SAR_Sm9DecErr0X02000505SM9 解密失败

参考文献​

  • [1] GB 15851 信息技术 安全技术 带消息恢复的数字签名方案
  • [2] GB/T 17903.1 信息技术 安全技术 抗抵赖 第 1 部分：概述
  • [3] GB/T 17903.2 信息技术 安全技术 抗抵赖 第 2 部分：使用对称技术的机制
  • [4] GB/T 17903.3 信息技术 安全技术 抗抵赖 第 3 部分：使用非对称技术的机制
  • [5] GB/T 17964.1 信息技术 安全技术 加密算法 第 1 部分：概述
  • [6] GB/T 17964.2 信息技术 安全技术 加密算法 第 2 部分：非对称加密
  • [7] GB/T 17964.3 信息技术 安全技术 加密算法 第 3 部分：对称加密
  • [8] GB/T 18238.1 信息技术 安全技术 散列函数 第 1 部分：概述
  • [9] GB/T 18238.2 信息技术 安全技术 散列函数 第 2 部分：采用 n 位块密码的散列函数
  • [10] GB/T 18238.3 信息技术 安全技术 散列函数 第 3 部分：专用散列函数
  • [11] GB/T 19713 信息技术 安全技术 公钥基础设施 在线证书状态协议
  • [12] GB/T 19771 信息技术 安全技术 公钥基础设施 PKI 组件最小互操作规范
  • [13] GB/T 38635.1 信息安全技术 SM9 标识密码算法 第 1 部分：总则
  • [14] GB/T 38635.2 信息安全技术 SM9 标识密码算法 第 2 部分：算法
  • [15] ISO/IEC 8825-1:2021 Information technology—ASN.1 encoding rules—Part 1: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)
  • [16] IETF RFC1777 Lightweight Directory Access Protocol
  • [17] IETF RFC2459 Internet X.509 Public Key Infrastructure Certificate and CRL Profile
  • [18] IETF RFC2560 X.509 Internet Public Key Infrastructure Online Certificate Status Protocol
  • [19] IETF RFC2587 Internet X.509 Public Key Infrastructure LDAPv2 Schema
  • [20] IETF RFC3647 Internet X.509 Public Key Infrastructure Certificate Policy and Certification Practices Framework
  • [21] IETF RFC4648 The Base16, Base32, and Base64 Data Encodings
  • [22] PKCS #11 Cryptographic Token Interface Standard
  • [23] RFC 2560 X.509 互联网公开密钥基础设施在线证书状态协议—OCSP
  • [24] RFC 2459 X.509 互联网公开密钥基础设施证书和 CRL 轮廓
  • [25] RSA Security Public-Key Cryptography Standards (PKCS)