| 标准编号 | GM/T 0018-2023 (GM/T0018-2023) | | 中文名称 | 密码设备应用接口规范 | | 英文名称 | Interface specifications of cryptography device application | | 行业 | Chinese Industry Standard (推荐) | | 中标分类 | L80 | | 字数估计 | 85,889 | | 发布日期 | 2023-12-04 | | 实施日期 | 2024-06-01 | | 发布机构 | 国家密码管理局 | GM/T 0018-2023: 密码设备应用接口规范
ICS 35.030
CCSL80
中华人民共和国密码行业标准
代替GM/T 0018-2012
密码设备应用接口规范
2023-12-04发布
2024-06-01实施
国家密码管理局 发 布
目次
前言 Ⅲ
引言 Ⅳ
1 范围 1
2 规范性引用文件 1
3 术语和定义 1
4 缩略语 1
5 算法标识和数据结构 2
5.1 算法标识定义 2
5.2 基本数据类型定义 2
5.3 设备信息定义 2
5.4 密钥分类及存储定义 3
5.5 RSA密钥数据结构定义 4
5.6 ECC密钥数据结构定义 5
5.7 ECC加密数据结构定义 5
5.8 ECC签名数据结构定义 6
5.9 ECC密钥对保护结构定义 6
6 设备接口描述 7
6.1 密码设备应用接口在公钥密码基础设施应用技术体系框架中的位置 7
6.2 设备管理类函数 8
6.3 密钥管理类函数 11
6.4 非对称算法运算类函数 20
6.5 对称算法运算类函数 25
6.6 杂凑运算类函数 37
6.7 用户文件操作类函数 40
6.8 验证调试类函数 42
附录A(规范性) 函数返回代码定义 50
附录B(规范性) SM9算法相关数据结构和接口函数 52
附录C(规范性) VPN设备相关接口函数 69
参考文献 79
前言
本文件按照GB/T 1.1-2020《标准化工作导则 第1部分:标准化文件的结构和起草规则》的规定
起草。
本文件代替GM/T 0018-2012《密码设备应用接口规范》,与GM/T 0018-2012相比,除结构调整
和编辑性改动外,主要技术变化如下:
a) 更改了ECC密钥对保护结构(见5.9,2012年版的5.8);
b) 删除了基于RSA算法的数字信封转换和基于ECC算法的数字信封转换两个接口函数(见
2012年版的6.3.7、6.3.17);
c) 增加了多包对称加解密、多包 MAC计算和单包可鉴别加解密、多包可鉴别加解密相关的17
个接口函数(见6.5,2012年版的6.5);
d) 增加了带密钥的杂凑运算相关的3个接口函数(见6.6);
e) 增加了验证调试类函数(见6.8);
f) 删除了第7章“安全要求”(见2012年版的第7章);
g) 增加了用户标识不匹配时的错误码(见附录A);
h) 增加了SM9标识密码算法相关数据结构以及SM9标识密码算法相关的15个接口函数的定
义(见附录B);
i) 增加了计算IKE工作密钥、计算IPSEC会话密钥、计算SSL工作密钥共6个接口函数的定义
(见附录C)。
请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。
本文件由密码行业标准化技术委员会提出并归口。
本文件起草单位:中电科网络安全科技股份有限公司、无锡江南信息安全工程技术中心、四川大学、
北京国脉信安科技有限公司、格尔软件股份有限公司、北京数字认证股份有限公司、兴唐通信科技有限
公司、山东得安信息技术有限公司、三未信安科技股份有限公司、北京海泰方圆科技股份有限公司、山东
大学。
本文件主要起草人:刘平、罗俊、龚勋、李川、袁峰、李元正、徐强、郑强、李述胜、李玉峰、孔凡玉、
马洪富、高志权、徐明翼、柳增寿、蒋红宇。
引 言
本文件的目标是为公钥密码基础设施应用体系框架下的服务端密码设备制定统一的应用接口标
准,通过该接口调用密码设备,向上层提供基础密码服务。为该类密码设备的开发、使用及检测提供标
准依据和指导,有利于提高该类密码设备的产品化、标准化和系列化水平。
密码设备应用接口规范
1 范围
本文件规定了公钥密码基础设施应用技术体系下服务端密码设备应用接口的算法标识、数据结构
和接口函数。
本文件适用于服务端密码设备的研制、使用,以及基于该类密码设备的应用开发。
2 规范性引用文件
下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中,注日期的引用文
件,仅该日期对应的版本适用于本文件;不注日期的引用文件,其最新版本(包括所有的修改单)适用于
本文件。
GB/T 15852.2 信息技术 安全技术 消息鉴别码 第2部分:采用专用杂凑函数的机制
GB/T 35276 信息安全技术 SM2密码算法使用规范
GB/T 36624 信息技术 安全技术 可鉴别的加密机制
GB/T 38635(所有部分) 信息安全技术 SM9标识密码算法
GM/T 0006 密码应用标识规范
GM/T 0022 IPSecVPN技术规范
GM/T 0024 SSLVPN技术规范
GM/Z4001 密码术语
3 术语和定义
GM/Z4001界定的以及下列术语和定义适用于本文件。
3.1
用于验证私钥使用权限的口令字。
3.2
用户密钥 userkey
存储在设备内部的用于应用密码运算的非对称密钥,包含签名密钥对和加密密钥对。
4 缩略语
下列缩略语适用于本文件。
EPK 外部加密公钥(ExternalPublicKey)
5 算法标识和数据结构
5.1 算法标识定义
本文件中所使用的算法其算法标识见GM/T 0006。分组密码算法的算法标识包含其工作模式。
5.2 基本数据类型定义
本文件中的基本数据类型均为高位字节在前(Big-Endian)方式存储和交换。表1定义了基本数据
类型。
表1 基本数据类型
类型名称 描述 定义
LONG 长整数,有符号32位整数 typedefintLONG
LPSTR 8位字符串指针,字符串按照UTF8格式存储及交换 typedefCHAR*LPSTR
HANDLE 句柄,指向任意数据对象的起始地址 typedefvoid* HANDLE
5.3 设备信息定义
表2定义了设备信息。
表2 设备信息描述
字段名称
数据长度
(字节)
含义
IssuerName 40 设备生产厂商名称
DeviceName 16 设备型号
DeviceSerial 16 设备编号,包含:日期(8字符)、批次号(3字符)、流水号(5字符)
DeviceVersion 4 密码设备内部软件的版本号
StandardVersion 4 密码设备支持的接口规范版本号,本版本为2
AsymAlgAbility 8
前4字节表示支持的算法,表示方法为非对称算法标识按位或运算的结果;
后4字节表示算法的最大模长,表示方法为支持的模长按位或运算的结果
SymAlgAbility 4 所有支持的对称算法,表示方法为对称算法标识按位或运算的结果
HashAlgAbility 4 所有支持的杂凑算法,表示方法为杂凑算法标识按位或运算的结果
BufferSize 4 支持的最大文件存储空间(单位字节)
实际数据结构定义:
CHARIssuerName[40];
CHARDeviceName[16];
CHARDeviceSerial[16];
ULONG DeviceVersion;
ULONG StandardVersion;
ULONG HashAlgAbility;
ULONG BufferSize;
}DEVICEINFO;
5.4 密钥分类及存储定义
5.4.1 设备密钥与用户密钥
设备密钥只能在设备初始化时生成或安装,用户密钥通过密码设备管理工具生成或安装。
设备密钥和用户密钥存放于密钥存储区,索引号从0开始检索,每个索引号对应一个签名密钥对和
一个加密密钥对。其中,索引号为0表示设备密钥。索引号1开始表示用户密钥。表3描述了设备密
钥和用户密钥存储方式。
表3 设备密钥和用户密钥存储描述
密钥对索引号 公钥 私钥
0x00
设备签名公钥 设备签名私钥
设备加密公钥 设备加密私钥
0x01
签名公钥 签名私钥
加密公钥 加密私钥
5.4.2 密钥加密密钥
密钥加密密钥通过密码设备管理工具生成或安装,存放于密钥存储区,使用索引号从1开始。表4
描述了密钥加密密钥存储方式。
表4 密钥加密密钥存储描述
密钥索引号 密钥加密密钥
0x01 密钥加密密钥001
5.4.3 会话密钥
会话密钥使用设备接口函数生成或导入,会话密钥使用句柄检索。
5.5 RSA密钥数据结构定义
RSA密钥结构存储时顺序为从高到低,即密钥存放时从密钥结构数组的最高位开始,最高字节填
在最高位,不足位从高位向低位填充数据0。表5定义了RSA密钥数据结构。
表5 RSA密钥数据结构
公钥数据结构定义
字段名称 数据长度(字节) 含义
bits 4 模长
m RSAref_MAX_LEN 模N
e RSAref_MAX_LEN 公钥指数
私钥数据结构定义
字段名称 数据长度 含义
bits 4 模长
m RSAref_MAX_LEN 模N
e RSAref_MAX_LEN 公钥指数
d RSAref_MAX_LEN 私钥指数
prime[2] RSAref_MAX_PLEN*2 素数p和q
pexp[2] RSAref_MAX_PLEN*2 Dp和Dq
coef RSAref_MAX_PLEN 系数i
实际数据结构定义:
#defineRSAref_MAX_BITS 2048
#defineRSAref_MAX_LEN ((RSAref_MAX_BITS+7)/8)
#defineRSAref_MAX_PBITS ((RSAref_MAX_BITS+1)/2)
#defineRSAref_MAX_PLEN ((RSAref_MAX_PBITS+7)/8)
ULONG bits;
BYTEm[RSAref_MAX_LEN];
BYTEe[RSAref_MAX_LEN];
}RSArefPublicKey;
BYTEm[RSAref_MAX_LEN];
BYTEe[RSAref_MAX_LEN];
BYTEd[RSAref_MAX_LEN];
BYTEprime[2][RSAref_MAX_PLEN];
BYTEpexp[2][RSAref_MAX_PLEN];
BYTEcoef[RSAref_MAX_PLEN];
}RSArefPrivateKey;
注:RSAref_MAX_BITS的数值能根据实际支持的最大模长进行定义。
5.6 ECC密钥数据结构定义
表6定义了ECC密钥数据结构。
表6 ECC密钥数据结构
公钥数据结构定义
字段名称 数据长度(字节) 含义
bits 4 密钥位长
x ECCref_MAX_LEN 公钥x坐标
y ECCref_MAX_LEN 公钥y坐标
私钥数据结构定义
字段名称 数据长度(字节) 含义
bits 4 密钥位长
K ECCref_MAX_LEN 私钥
实际数据结构定义:
#defineECCref_MAX_BITS 512
#defineECCref_MAX_LEN ((ECCref_MAX_BITS+7)/8)
ULONG bits;
BYTEx[ECCref_MAX_LEN];
BYTEy[ECCref_MAX_LEN];
}ECCrefPublicKey;
BYTEK[ECCref_MAX_LEN];
}ECCrefPrivateKey;
5.7 ECC加密数据结构定义
表7定义了ECC加密数据结构。
表7 ECC加密数据结构
加密数据结构定义
字段名称 数据长度(字节) 含义
x ECCref_MAX_LEN X分量
y ECCref_MAX_LEN Y分量
表7 ECC加密数据结构 (续)
加密数据结构定义
字段名称 数据长度(字节) 含义
M 32 明文的杂凑值
L 4 密文数据长度
C L 密文数据
实际数据结构定义:
BYTEx[ECCref_MAX_LEN];
BYTEy[ECCref_MAX_LEN];
BYTEM[32];
ULONG L;
BYTEC[];
}ECCCipher;
5.8 ECC签名数据结构定义
表8定义了ECC签名数据结构。
表8 ECC签名数据结构
签名数据结构定义
字段名称 数据长度(字节) 含义
r ECCref_MAX_LEN 签名的r部分
s ECCref_MAX_LEN 签名的s部分
实际数据结构定义:
BYTEr[ECCref_MAX_LEN];
BYTEs[ECCref_MAX_LEN];
}ECCSignature;
5.9 ECC密钥对保护结构定义
密钥管理系统下发到设备中的ECC加密密钥对使用本结构保护,表9定义了ECC密钥对保护
结构。
表9 ECC加密密钥对保护结构参数
字段名称 数据长度(字节) 含义
Version 4 版本号,本版本为1
表9 ECC加密密钥对保护结构参数 (续)
字段名称 数据长度(字节) 含义
ulSymmAlgID 4 对称算法标识(必须为ECB模式)
ulBits 4 ECC密钥对的密钥位长
cbEncryptedPrivKey ECCref_MAX_LEN
对称算法加密的ECC私钥,ECC私钥的原文
为ECCrefPrivateKey,结构中的K,其有效长度
为原文的(ulBits+7)/8
PubKey ECCref_MAX_LEN*2+4 ECC密钥对的公钥
ECCCipherBlob
ECCref_MAX_LEN*2+32+
4+L
用保护公钥加密过的对称密钥密文结构
实际数据结构定义:
ULONGVersion;
BYTE cbEncryptedPriKey[ECCref_MAX_LEN];
}EnvelopedECCKey;
私钥密文结构中有效密文分组从0偏移量字节开始,顺序解密密文分组后将明文连接得到ECC密
钥对的私钥的明文。
6 设备接口描述
6.1 密码设备应用接口在公钥密码基础设施应用技术体系框架中的位置
在公钥密码基础设施应用技术体系框架中,密码设备服务层由密码机、密码卡、智能密码终端设备
组成,通过本文件规定的密码设备应用接口向通用密码服务层提供基础密码服务,如图1所示。
基础密码服务包括密钥生成、单一的密码运算、文件管理服务。
本文件采用C语言描述接口函数。如无特别说明,函数中参数的长度单位均为字节数。符合本文
件的密码设备应支持本文件中关于ECC算法(本文件中ECC特指SM2算法)、对称算法以及杂凑运算
的函数接口。本文件所列的所有接口函数均应能被应用系统任意调用。附录 A定义了函数返回代
码,附录B定义了SM9算法相关数据结构和接口函数,附录C定义了VPN设备相关接口函数。
产品支持SM9算法时,SM9算法相关数据结构和接口函数应符合附录B的定义。产品支持VPN
时,VPN设备相关接口函数应符合附录C的定义。
图1 密码设备应用接口在公钥密码基础设施应用技术体系框架中的位置
6.2 设备管理类函数
6.2.1 概述
设备管理类函数提供设备打开与关闭、会话创建与关闭、设备信息获取、随机数产生、私钥权限获取
与释放功能,表10列出了设备管理类函数,附录A定义了函数返回代码。
表10 设备管理类函数
函数名称 功能
SDF_OpenDevice 打开设备
SDF_CloseDevice 关闭设备
SDF_OpenSession 创建会话
SDF_CloseSession 关闭会话
SDF_GetDeviceInfo 获取设备信息
SDF_GenerateRandom 产生随机数
6.2.2 打开设备
原型: LONGSDF_OpenDevice(HANDLE*phDeviceHandle);
描述: 打开密码设备。phDeviceHandle由函数初始化并填写内容。
参数: phDeviceHandle[out] 返回的设备句柄
返回值: 0 成功
非0 失败,返回错误代码
6.2.3 关闭设备
描述: 关闭密码设备,并释放相关资源。
参数: hDeviceHandle[in] 已打开的设备句柄
返回值: 0 成功
非0 失败,返回错误代码
6.2.4 创建会话
描述: 创建与密码设备的会话。
参数: hDeviceHandle[in] 已打开的设备句柄
phSessionHandle[out] 返回与密码设备建立的新会话句柄
返回值: 0 成功
非0 失败,返回错误代码
6.2.5 关闭会话
描述: 关闭与密码设备已建立的会话,并释放相关资源。
参数: hSessionHandle[in] 与密码设备已建立的会话句柄
返回值: 0 成功
非0 失败,返回错误代码
6.2.6 获取设备信息
原型: LONGSDF_GetDeviceInfo(
描述: 获取密码设备能力描述。
参数: hSessionHandle[in] 与设备建立的会话句柄
pstDeviceInfo[out] 设备能力描述信息,内容及格式见设备信息定义
返回值: 0 成功
非0 失败,返回错误代码
6.2.7 产生随机数
原型: LONGSDF_GenerateRandom(
ULONG uiLength,
BYTE*pucRandom);
描述: 获取指定长度的随机数。
参数: hSessionHandle[in] 与设备建立的会话句柄
uiLength[in] 获取的随机数长度
pucRandom[out] 缓冲区指针,用于存放获取的随机数
返回值: 0 成功
非0 失败,返回错误代码
6.2.8 获取私钥使用权限
ULONG uiKeyIndex,
LPSTR pucPassword,
ULONG uiPwdLength);
描述: 获取密码设备内部存储的指定索引位置私钥的使用权。本文件涉及密码设备存储的密钥
对索引值的起始索引值为1,最大为n,密码设备的实际存储容量决定n值。私钥访问控
制码不少于8字节。
参数: hSessionHandle[in] 与设备建立的会话句柄
uiKeyIndex[in] 密码设备存储的密钥对的索引值
pucPassword[in] 使用私钥权限的访问控制码
uiPwdLength[in] 私钥访问控制码长度
返回值: 0 成功
非0 失败,返回错误代码
6.2.9 释放私钥使用权限
ULONG uiKeyIndex);
描述: 释放密码设备存储的指定索引位置私钥的使用授权。
参数: hSessionHandle[in] 与设备建立的会话句柄
uiKeyIndex[in] 密码设备存储的密钥对的索引值
返回值: 0 成功
非0 失败,返回错误代码
6.3 密钥管理类函数
6.3.1 概述
密钥管理类函数提供密钥的生成、销毁和导入导出功能,包括签名公钥和加密公钥的导出、会话密
钥的生成并输出、会话密钥的导入、密钥协商参数的生成并输出、会话密钥的计算以及会话密钥的销毁
函数,表11列出了密钥管理类函数,附录A定义了函数返回代码。
表11 密钥管理类函数
函数名称 功能
SDF_ExportSignPublicKey_RSA 导出RSA签名公钥
SDF_ExportEncPublicKey_RSA 导出RSA加密公钥
SDF_GenerateKeyWithIPK_RSA 生成会话密钥并用内部RSA公钥加密输出
SDF_GenerateKeyWithEPK_RSA 生成会话密钥并用外部RSA公钥加密输出
SDF_ImportKeyWithISK_RSA 导入会话密钥并用内部RSA私钥解密
SDF_ExportSignPublicKey_ECC 导出ECC签名公钥
SDF_ExportEncPublicKey_ECC 导出ECC加密公钥
SDF_GenerateKeyWithIPK_ECC 生成会话密钥并用内部ECC公钥加密输出
SDF_GenerateKeyWithEPK_ECC 生成会话密钥并用外部ECC公钥加密输出
SDF_ImportKeyWithISK_ECC 导入会话密钥并用内部ECC私钥解密
SDF_GenerateKeyWithECC 计算会话密钥
SDF_GenerateKeyWithKEK 生成会话密钥并用密钥加密密钥加密输出
表11 密钥管理类函数 (续)
函数名称 功能
SDF_ImportKeyWithKEK 导入会话密钥并用密钥加密密钥解密
SDF_DestroyKey 销毁会话密钥
6.3.2 导出RSA签名公钥
原型: LONGSDF_ExportSignPublicKey_RSA(
ULONG uiKeyIndex,
描述: 导出密码设备内部存储的指定索引位置的RSA签名公钥。
参数: hSessionHandle[in] 与设备建立的会话句柄
uiKeyIndex[in] 密码设备存储的密钥对的索引值
pucPublicKey[out] RSA公钥结构
返回值: 0 成功
非0 失败,返回错误代码
6.3.3 导出RSA加密公钥
原型: LONGSDF_ExportEncPublicKey_RSA(
ULONG uiKeyIndex,
描述: 导出密码设备内部存储的指定索引位置的RSA加密公钥。
参数: hSessionHandle[in] 与设备建立的会话句柄
uiKeyIndex[in] 密码设备存储的密钥对的索引值
pucPublicKey[out] RSA公钥结构
返回值: 0 成功
非0 失败,返回错误代码
6.3.4 生成会话密钥并用内部RSA公钥加密输出
原型: LONGSDF_GenerateKeyWithIPK_RSA(
ULONGuiIPKIndex,
ULONG*puiKeyLength,
HANDLE*phKeyHandle);
描述: 生成会话密钥并用指定索引的内部RSA加密公钥加密输出,同时返回密钥句柄。公钥加
密数据时填充方式与PKCS#1v1.5相同。
参数: hSessionHandle[in] 与设备建立的会话句柄
uiIPKIndex[in] 密码设备存储的密钥对的索引值
uiKeyBits[in] 指定产生的会话密钥长度
pucKey[out] 缓冲区指针,用于存放返回的密钥密文
puiKeyLength[out] 返回的密钥密文长度
phKeyHandle[out] 返回的密钥句柄
返回值: 0 成功
非0 失败,返回错误代码
6.3.5 生成会话密钥并用外部RSA公钥加密输出
原型: LONGSDF_GenerateKeyWithEPK_RSA(
ULONGuiKeyBits,
ULONG*puiKeyLength,
HANDLE*phKeyHandle);
描述: 生成会话密钥并用外部RSA公钥加密输出。公钥加密数据时填充方式与PKCS#1v1.5相同。
参数: hSessionHandle[in] 与设备建立的会话句柄
uiKeyBits[in] 指定产生的会话密钥长度
pucPublicKey[in] 输入的外部RSA公钥结构
pucKey[out] 缓冲区指针,用于存放返回的密钥密文
puiKeyLength[out] 返回的密钥密文长度
phKeyHandle[out] 返回的密钥句柄
返回值: 0 成功
非0 失败,返回错误代码
6.3.6 导入会话密钥并用内部RSA私钥解密
原型: LONGSDF_ImportKeyWithISK_RSA(
ULONGuiISKIndex,
HANDLE*phKeyHandle);
描述: 导入会话密钥并用内部RSA私钥解密,同时返回密钥句柄。
参数: hSessionHandle[in] 与设备建立的会话句柄
uiISKIndex[in] 密码设备存储的密钥对的索引值
pucKey[in] 缓冲区指针,用于存放输入的密钥密文
puiKeyLength[in] 输入的密钥密文长度
phKeyHandle[out] 返回的密钥句柄
返回值: 0 成功
非0 失败,返回错误代码
6.3.7 导出ECC签名公钥
原型: LONGSDF_ExportSignPublicKey_ECC(
ULONG uiKeyIndex,
描述: 导出密码设备内部存储的指定索引位置的ECC签名公钥。
参数: hSessionHandle[in] 与设备建立的会话句柄
uiKeyIndex[in] 密码设备存储的密钥对的索引值
pucPublicKey[out] ECC公钥结构
返回值: 0 成功
非0 失败,返回错误代码
6.3.8 导出ECC加密公钥
原型: LONGSDF_ExportEncPublicKey_ECC(
ULONG uiKeyIndex,
描述: 导出密码设备内部存储的指定索引位置的ECC加密公钥。
参数: hSessionHandle[in] 与设备建立的会话句柄
uiKeyIndex[in] 密码设备存储的密钥对的索引值
pucPublicKey[out] ECC公钥结构
返回值: 0 成功
非0 失败,返回错误代码
6.3.9 生成会话密钥并用内部ECC公钥加密输出
原型: LONGSDF_GenerateKeyWithIPK_ECC(
ULONGuiIPKIndex,
HANDLE*phKeyHandle);
描述: 生成会话密钥并用指定索引的内部ECC加密公钥加密输出,同时返回密钥句柄。
参数: hSessionHandle[in] 与设备建立的会话句柄
uiIPKIndex[in] 密码设备存储的密钥对的索引值
uiKeyBits[in] 指定产生的会话密钥长度
pucKey[out] 缓冲区指针,用于存放返回的密钥密文
phKeyHandle[out] 返回的密钥句柄
返回值: 0 成功
非0 失败,返回错误代码
6.3.10 生成会话密钥并用外部ECC公钥加密输出
原型: LONGSDF_GenerateKeyWithEPK_ECC(
ULONGuiKeyBits,
ECCCipher*pucKey,
HANDLE*phKeyHandle);
描述: 生成会话密钥并用外部ECC公钥加密输出,同时返回密钥句柄。
参数: hSessionHandle[in] 与设备建立的会话句柄
uiKeyBits[in] 指定产生的会话密钥长度
uiAlgID[in] 外部ECC公钥的算法标识
pucPublicKey[in] 输入的外部ECC公钥结构
pucKey[out] 缓冲区指针,用于存放返回的密钥密文
phKeyHandle[out] 返回的密钥句柄
返回值: 0 成功
非0 失败,返回错误代码
6.3.11 导入会话密钥并用内部ECC私钥解密
原型: LONGSDF_ImportKeyWithISK_ECC(
ULONGuiISKIndex,
描述: 导入会话密钥并用内部ECC加密私钥解密,同时返回密钥句柄。
参数: hSessionHandle[in] 与设备建立的会话句柄
uiISKIndex[in] 密码设备存储的密钥对的索引值
pucKey[in] 缓冲区指针,用于存放输入的密钥密文
phKeyHandle[out] 返回的密钥句柄
返回值: 0 成功
非0 失败,返回错误代码
6.3.12 生成密钥协商参数并输出
ULONGuiISKIndex,
BYTE*pucSponsorID,
HANDLE*phAgreementHandle);
描述: 使用ECC密钥协商算法,为计算会话密钥而产生协商参数,同时返回指定索引位置的
ECC公钥、临时ECC密钥对的公钥及协商句柄。协商会话密钥时,本函数首先由协商的
发起方调用。
参数: hSessionHandle[in] 与设备建立的会话句柄
uiISKIndex[in] 密码设备存储的密钥对的索引值
uiKeyBits[in] 要求协商的密钥长度
pucSponsorID[in] 参与密钥协商的发起方ID值
uiSponsorIDLength[in] 发起方ID长度
pucSponsorPublicKey[out] 返回的发起方ECC公钥结构
phAgreementHandle[out] 返回的协商句柄,用于计算协商密钥
返回值: 0 成功
非0 失败,返回错误代码
6.3.13 计算会话密钥
原型: LONGSDF_GenerateKeyWithECC(
HANDLE*phKeyHandle);
描述: 使用ECC密钥协商算法,使用自身协商句柄和响应方的协商参数计算会话密钥,同时返
回会话密钥句柄。使用SM2算法计算会话密钥的过程应符合GB/T 35276。本函数由协
商的发起方在获得响应方的协商参数后调用。会话密钥计算完成后,协商句柄被销毁,为
协商句柄分配的内存资源也被释放。
参数: hSessionHandle[in] 与设备建立的会话句柄
pucResponseID[in] 外部输入的响应方ID值
hAgreementHandle[in] 协商句柄,用于计算协商密钥
phKeyHandle[out] 返回的密钥句柄
返回值: 0 成功
非0 失败,返回错误代码
6.3.14 产生协商数据并计算会话密钥
ULONGuiISKIndex,
BYTE*pucResponseID,
BYTE*pucSponsorID,
HANDLE*phKeyHandle);
描述: 使用ECC密钥协商算法,产生协商参数并计算会话密钥,同时返回产生的协商参数和密
钥句柄。使用SM2算法计算会话密钥的过程应符合 GB/T 35276。本函数由响应方
调用。
参数: hSessionHandle[in] 与设备建立的会话句柄
uiISKIndex[in] 密码设备存储的密钥对的索引值
uiKeyBits[in] 协商后要求输出的密钥长度
pucResponseID[in] 响应方ID值
pucSponsorID[in] 发起方ID值
uiSponsorIDLength[in] 发起方ID长度
pucSponsorPublicKey[in] 外部输入的发起方ECC公钥结构
phKeyHandle[out] 返回的密钥句柄
返回值: 0 成功
非0 失败,返回错误代码
6.3.15 生成会话密钥并用密钥加密密钥加密输出
原型: LONGSDF_GenerateKeyWithKEK(
ULONG uiAlgID,
BYTE*pucKey,
ULONG*puiKeyLength,
HANDLE*phKeyHandle);
描述: 生成会话密钥并用密钥加密密钥加密输出,同时返回密钥句柄。加密模式为ECB模式。
参数: hSessionHandle[in] 与设备建立的会话句柄
uiKeyBits[in] 指定产生的会话密钥长度
uiAlgID[in] 算法标识,指定分组密码算法和工作模式
uiKEKIndex[in] 密码设备存储的密钥加密密钥的索引值
pucKey[out] 缓冲区指针,用于存放返回的密钥密文
puiKeyLength[out] 返回的密钥密文长度
phKeyHandle[out] 返回的密钥句柄
返回值: 0 成功
非0 失败,返回错误代码
6.3.16 导入会话密钥并用密钥加密密钥解密
原型: LONGSDF_ImportKeyWithKEK(
BYTE*pucKey,
HANDLE*phKeyHandle);
描述: 导入会话密钥并用密钥加密密钥解密,同时返回会话密钥句柄。加密模式为ECB模式。
参数: hSessionHandle[in] 与设备建立的会话句柄
uiAlgID[in] 算法标识,指定分组密码算法和工作模式
uiKEKIndex[in] 密码设备存储的密钥加密密钥的索引值
pucKey[in] 缓冲区指针,用于存放输入的密钥密文
uiKeyLength[in] 输入的密钥密文长度
phKeyHandle[out] 返回的密钥句柄
返回值: 0 成功
非0 失败,返回错误代码
6.3.17 销毁会话密钥
原型: LONGSDF_DestroyKey(
描述: 销毁会话密钥,并释放为密钥句柄分配的内存资源。本函数在对称算法运算完成后调用。
参数: hSessionHandle[in] 与设备建立的会话句柄
hKeyHandle[in] 输入的密钥句柄
返回值: 0 成功
非0 失败,返回错误代码
6.4 非对称算法运算类函数
6.4.1 概述
非对称算法运算类函数提供RSA公私钥运算、ECC签名验证和加密功能,表12列出了非对称算
法运算类函数,附录A定义了函数返回代码。
表12 非对称算法运算类函数
函数名称 功能
SDF_ExternalVerify_ECC 外部公钥ECC验证
SDF_InternalSign_ECC 内部私钥ECC签名
SDF_InternalVerify_......
|