| 标准编号 | GB/T 36322-2018 (GB/T36322-2018) | | 中文名称 | 信息安全技术 密码设备应用接口规范 | | 英文名称 | Information security technology -- Cryptographic device application interface specifications | | 行业 | 国家标准 (推荐) | | 中标分类 | L80 | | 国际标准分类 | 35.040 | | 字数估计 | 42,492 | | 发布日期 | 2018-06-07 | | 实施日期 | 2019-01-01 | | 标准依据 | 国家标准公告2018年第9号 | | 发布机构 | 国家市场监督管理总局、中国国家标准化管理委员会 | GB/T 36322-2018
Information security technology--Cryptographic device application interface specifications
ICS 35.040
L80
中华人民共和国国家标准
信息安全技术
密码设备应用接口规范
2018-06-07发布
2019-01-01实施
国 家 市 场 监 督 管 理 总 局
中国国家标准化管理委员会 发 布
目次
前言 Ⅰ
引言 Ⅱ
1 范围 1
2 规范性引用文件 1
3 术语和定义 1
4 符号和缩略语 2
5 算法标识和数据结构 2
5.1 算法标识定义 2
5.2 基本数据类型定义 2
5.3 设备信息定义 3
5.4 密钥分类及存储定义 3
5.5 RSA密钥数据结构定义 4
5.6 ECC密钥数据结构定义 5
5.7 ECC加密数据结构定义 6
5.8 ECC签名数据结构定义 6
6 设备接口描述 7
6.1 密码设备应用接口在公钥密码基础设施应用技术体系框架中的位置 7
6.2 设备管理类函数 7
6.3 密钥管理类函数 9
6.4 非对称算法运算类函数 27
6.5 对称算法运算类函数 31
6.6 杂凑运算类函数 33
6.7 用户文件操作类函数 34
附录A(规范性附录) 函数返回代码定义 37
参考文献 39
前言
本标准按照GB/T 1.1-2009给出的规则起草。
请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别这些专利的责任。
本标准由全国信息安全标准化技术委员会(SAC/TC260)提出并归口。
本标准起草单位:卫士通信息产业股份有限公司、无锡江南信息安全工程技术中心、四川大学、上海
格尔软件股份有限公司、北京数字认证股份有限公司、兴唐通信科技股份有限公司、山东得安信息技术
有限公司、北京三未信安科技发展有限公司、海泰方圆科技有限公司、山东大学。
本标准主要起草人:刘平、罗俊、龚勋、李元正、徐强、郑强、李述胜、李玉峰、孔凡玉、马洪富、高志权、
徐明翼、柳增寿、蒋红宇。
引 言
本标准的目标是为公钥密码基础设施应用体系框架下的服务类密码设备制定统一的应用接口标
准,通过该接口调用密码设备,向上层提供基础密码服务。为该类密码设备的开发、使用及检测提供标
准依据和指导,有利于提高该类密码设备的产品化、标准化和系列化水平。
本标准中涉及密码算法的相关内容,按照国家有关法规实施。
信息安全技术
密码设备应用接口规范
1 范围
本标准规定了公钥密码基础设施应用技术体系下服务类密码设备的应用接口标准。
本标准适用于服务类密码设备的研制、使用,以及基于该类密码设备的应用开发,也可用于指导该
类密码设备的检测。
2 规范性引用文件
下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件,仅注日期的版本适用于本文
件。凡是不注日期的引用文件,其最新版本(包括所有的修改单)适用于本文件。
GB/T 33560 信息安全技术 密码应用标识规范
3 术语和定义
下列术语和定义适用于本文件。
3.1
算法标识 algorithmidentifier
用于对密码算法进行唯一标识的符号。
3.2
公钥密码算法
加解密使用不同密钥的密码算法。
3.3
解密 decipherment/decryption
加密过程对应的逆过程。
3.4
设备密钥 devicekeypair
存储在设备内部的用于设备管理的非对称密钥对,包含签名密钥对和加密密钥对。
3.5
加密 encipherment/encryption
对数据进行密码变换以产生密文的过程。
3.6
密钥加密密钥 keyencryptionkey
对密钥进行加密保护的密钥。
3.7
用公钥密码技术建立的普遍适用的基础设施,为用户提供证书管理和密钥管理等安全服务。
3.8
用于验证私钥使用权限的口令字。
3.9
对称密码体制
原发者和接收者均采用同一秘密密钥进行变换的密码技术(体制)。
注:加密密钥与解密密钥相同,或者一个密钥可以从另一个密钥导出的密码体制。
3.10
会话密钥 sessionkey
处于层次化密钥结构中的最低层,仅在一次会话中使用的密钥。
3.11
用户密钥 userkey
存储在设备内部的用于应用密码运算的非对称密钥,包含签名密钥对和加密密钥对。
4 符号和缩略语
下列符号和缩略语适用于本文件。
EPK 外部加密公钥(ExternalPublicKey)
ISK 内部加密私钥(InternalPrivateKey)
5 算法标识和数据结构
5.1 算法标识定义
本标准中所使用的算法其算法标识见GB/T 33560。对称加密算法的算法标识包含其工作模式。
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 密码设备支持的接口规范版本号
AsymAlgAbility 8
前4字节表示支持的算法,表示方法为非对称算法标识按位或运算的
结果;后4字节表示算法的最大模长,表示方法为支持的模长按位或运
算的结果
SymAlgAbility 4 所有支持的对称算法,表示方法为对称算法标识按位或运算的结果
HashAlgAbility 4 所有支持的杂凑算法,表示方法为杂凑算法标识按位或运算的结果
BufferSize 4 支持的最大文件存储空间(单位字节)
实际数据结构定义:
CHARIssuerName[40];
CHARDeviceName[16];
CHARDeviceSerial[16]
ULONGAsymAlgAbility[2];
ULONGSymAlgAbility;
ULONGB ufferSize;
}DEVICEINFO;
5.4 密钥分类及存储定义
5.4.1 设备密钥与用户密钥
设备密钥只能在设备初始化时生成或安装,用户密钥通过密码设备管理工具生成或安装。
设备密钥和用户密钥存放于密钥存储区,索引号从0开始检索,每个索引号对应一个签名密钥对和
一个加密密钥对。其中,索引号为0表示设备密钥。索引号1开始表示用户密钥。设备密钥和用户密
钥存储描述如表3所示。
表3 设备密钥和用户密钥存储描述
密钥对索引号 公钥 私钥
0x00
设备签名公钥 设备签名私钥
设备加密公钥 设备加密私钥
0x01
用户签名公钥 用户签名私钥
用户加密公钥 用户加密私钥
5.4.2 密钥加密密钥
密钥加密密钥通过密码设备管理工具生成或安装,密钥长度为128位,存放于密钥存储区,使用索
引号从1开始。密钥加密密钥存储描述如表4所示。
表4 密钥加密密钥存储描述
密钥索引号 密钥加密密钥
0x01 密钥加密密钥001
5.4.3 会话密钥
会话密钥使用设备接口函数生成或导入,会话密钥使用句柄检索。
5.5 RSA密钥数据结构定义
RSA密钥结构存储时顺序为从高到低,即密钥存放时从密钥结构数组的最高位开始,最高字节填
在最高位,不足位填充数据0。RSA密钥数据结构如表5所示。
表5 RSA密钥数据结构
分类 字段名称 数据长度(字节) 含义
公钥
bits 4 模长
m 256 模N
e 256 公钥指数
私钥
bits 4 模长
m 256 模N
e 256 公钥指数
d 256 私钥指数
prime[2] 128*2 素数p和q
pexp[2] 128*2 Dp和Dq
coef 128 系数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)
ULONGbits;
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;
5.6 ECC密钥数据结构定义
ECC密钥数据结构如表6所示。
表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)
ULONGbits;
BYTEx[ECCref_MAX_LEN];
BYTEy[ECCref_MAX_LEN];
}ECCrefPublicKey;
BYTEK[ECCref_MAX_LEN];
}ECCrefPrivateKey;
5.7 ECC加密数据结构定义
ECC加密数据结构如表7所示。
表7 ECC加密数据结构
字段名称 数据长度(字节) 含义
x ECCref_MAX_LEN X分量
y ECCref_MAX_LEN Y分量
M 32 明文的杂凑值
L 4 密文数据长度
C L 密文数据
实际数据结构定义:
BYTEx[ECCref_MAX_LEN];
BYTEy[ECCref_MAX_LEN];
BYTEM[32];
ULONGL;
BYTEC[1];
}ECCCipher;
5.8 ECC签名数据结构定义
ECC签名数据结构如表8所示。
表8 ECC签名数据结构
字段名称 数据长度(字节) 含义
r ECCref_MAX_LEN 签名的r部分
s ECCref_MAX_LEN 签名的s部分
实际数据结构定义:
BYTEr[ECCref_MAX_LEN];
BYTEs[ECCref_MAX_LEN];
}ECCSignature;
6 设备接口描述
6.1 密码设备应用接口在公钥密码基础设施应用技术体系框架中的位置
在公钥密码基础设施应用技术体系框架中,密码设备服务层由密码机、密码卡、智能密码终端等设
备组成,通过本标准规定的密码设备应用接口向通用密码服务层提供基础密码服务。如图1所示。
基础密码服务包括密钥生成、单一的密码运算、文件管理等的服务。
本标准采用C语言描述接口函数。如无特别说明,函数中参数的长度单位均为字节数。
图1 密码设备应用接口在公钥密码基础设施应用技术体系框架中的位置
6.2 设备管理类函数
6.2.1 概述
设备管理类函数提供设备打开与关闭、会话创建与关闭、设备信息获取、随机数产生、私钥权限获取
与释放等功能,如表9所示,各函数返回代码见附录A。
表9 设备管理类函数
函数名称 功能
SDF_OpenDevice 打开设备
SDF_CloseDevice 关闭设备
SDF_OpenSession 创建会话
SDF_CloseSession 关闭会话
SDF_GetDeviceInfo 获取设备信息
SDF_GenerateRandom 产生随机数
6.2.2 打开设备
原型: LONGSDF_OpenDevice(HANDLE*phDeviceHandle);
描述: 打开密码设备。
参数: phDeviceHandle[out] 返回的设备句柄
返回值: 0 成功
非0 失败,返回错误代码
注:phDeviceHandle由函数初始化并填写内容。
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(
BYTE*pucRandom);
描述: 获取指定长度的随机数。
参数: hSessionHandle[in] 与设备建立的会话句柄
uiLength[in] 获取的随机数长度
pucRandom[out] 缓冲区指针,用于存放获取的随机数
返回值: 0 成功
非0 失败,返回错误代码
6.2.8 获取私钥使用权限
ULONGuiKeyIndex,
ULONGuiPwdLength);
描述: 获取密码设备内部存储的指定索引私钥的使用权。
参数: hSessionHandle[in] 与设备建立的会话句柄
uiKeyIndex[in] 密码设备存储私钥的索引值
pucPassword[in] 私钥访问控制码
uiPwdLength[in] 私钥访问控制码长度,不少于8字节
返回值: 0 成功
非0 失败,返回错误代码
注:本标准涉及密码设备存储的密钥对索引值的起始索引值为1,最大为n,密码设备的实际存储容量决定n值。
6.2.9 释放私钥使用权限
ULONGuiKeyIndex);
描述: 释放密码设备存储的指定索引私钥的使用授权。
参数: hSessionHandle[in] 与设备建立的会话句柄
uiKeyIndex[in] 密码设备存储私钥索引值
返回值: 0 成功
非0 失败,返回错误代码
6.3 密钥管理类函数
6.3.1 概述
密钥管理类函数提供密钥的生成和导入导出等功能,包括签名公钥和加密公钥的导出、非对称密钥
对的产生并输出、会话密钥的生成并输出、会话密钥的导入、数字信封转换、密钥协商参数的生成并输
出、会话密钥的计算、IKE工作密钥的计算、IPSEC会话密钥的计算、SSL工作密钥的计算以及会话密
钥的销毁等函数,如表10所示,各函数返回代码见附录A。
表10 密钥管理类函数
函数名称 功能
SDF_ExportSignPublicKey_RSA 导出RSA签名公钥
SDF_ExportEncPublicKey_RSA 导出RSA加密公钥
SDF_GenerateKeyPair_RSA 产生RSA非对称密钥对并输出
SDF_GenerateKeyWithIPK_RSA 生成会话密钥并用内部RSA公钥加密输出
SDF_GenerateKeyWithEPK_RSA 生成会话密钥并用外部RSA公钥加密输出
SDF_ImportKeyWithISK_RSA 导入会话密钥并用内部RSA私钥解密
SDF_ExportSignPublicKey_ECC 导出ECC签名公钥
SDF_ExportEncPublicKey_ECC 导出ECC加密公钥
SDF_GenerateKeyPair_ECC 产生ECC非对称密钥对并输出
SDF_GenerateKeyWithIPK_ECC 生成会话密钥并用内部ECC公钥加密输出
SDF_GenerateKeyWithEPK_ECC 生成会话密钥并用外部ECC公钥加密输出
SDF_ImportKeyWithISK_ECC 导入会话密钥并用内部ECC私钥解密
SDF_GenerateKeyWithECC 计算会话密钥
SDF_GenerateKeyWithKEK 生成会话密钥并用密钥加密密钥加密输出
SDF_ImportKeyWithKEK 导入会话密钥并用密钥加密密钥解密
SDF_GenerateKeywithIKE 计算IKE工作密钥
SDF_GenerateKeywithEPK_IKE 计算IKE工作密钥并用外部ECC公钥加密输出
SDF_GenerateKeywithEPK_IPSEC 计算IPSEC会话密钥并用外部ECC公钥加密输出
SDF_GenerateKeywithSSL 计算SSL工作密钥
SDF_GenerateKeywithEPK_SSL 计算SSL工作密钥并用外部EC......
|