B系列密码卡SDK用户手册

本文档介绍了如何使用派科信安B系列密码卡SDK，其包括源码包、文档、固件和相关工具。

本文档适用于帮助客户验证密码卡功能、性能和基于密码卡API接口二次开发。

适用范围

此手册适用于派科信安的如下PCIe密码卡：

B系列：B1、B2、B3，v2.0版本。

1 SDK介绍

B系列密码卡SDK能够帮助客户开发生产各类密码安全应用设备，提供各种算法高性能的、多任务并行处理的密码运算，可以满足应用系统数据的签名/验证、加密/解密的要求，保证传输信息的机密性、完整性和有效性，同时提供安全、完善的密钥管理机制。主要面向服务器、加密机等对算法性能要求较高的应用场景。

API接口符合《GM/T0018-2012 密码设备应用接口规范》标准接口规范，通用性好，客户产品能够平滑接入各种系统平台，满足大多数应用系统的要求，有效提高密码应用领域的算力，具有广泛的应用前景。

SDK实现算法支持

分类	算法
对称算法	AES/SM1/SM4(ECB/CBC/CFB/OFB/XTS)
非对称算法	SM2、RSA1024/2048
杂凑算法	SHA256/SM3

内核态接口

算法	模式
SM1、SM4	CBC
SM4-CBC-HMAC-SM3、SM1-CBC-HMAC-SM3
HMAC-SM3

配合密码芯片可以实现密钥生成与管理、数据加密和解密、消息鉴别码的产生和验证、数据摘要的产生和验证、数字签名的产生和验证、数字信封、用户访问权限控制、密钥备份及恢复等功能。同时提供TLS加速、IPsec加速方案的底层硬件支持，帮助客户实现高性能、高安全性的应用实现。主要面向服务器、加密机等对算法性能要求较高的应用场景，具有高性能、可编程等特性。

1.1 SDK源码包文件结构说明

SDK源码包文件结构说明

一级目录	二级目录	三级目录	说明
driver	rsp_cmdq_drv	-	Linux内核态cmdq驱动
	rsp_ctrl_drv	-	LInux内核态控制管理驱动
	rsp_kci_drv	-	Linux内核态接口驱动
	rsp_pf	-	Linux内核态PF设备驱动
	rsp_vf	-	Linux内核态VF设备驱动
lib_src	cap	-	通用CAP接口
	api	-	通用API接口
	sdf	-	SDF接口封装库
lib	-	-	存放编译成功的libsdf.so和libsdf.a库
tools	basic_tools	-	BAR空间读写工具，调试工具等
	kmt	-	管理工具
	piicoTool	-	Piico卡SDF接口应用初始化工具
include	-	-	sdf接口头文件
examples	-	-	SDF接口使用样例程序
common	ukey	-	配套ukey库

SDK整体架构中，从上到下包括SDF、CAP API、同步/异步API。其中CAP API是比较重要的一个模块，该模块包含了算法API和密钥管理API,支撑上层SDF接口。用户可基于此扩展其他密码接口。

SDK整体架构图：

1.2 SDF接口样例源码包文件结构说明

SDF接口样例源码包文件结构说明

目录/文件	说明
lib	SDF库位置目录，存放编译成功的libsdf.so和libsdf.a库
include	SDF头文件目录
examples	SDF接口样例源码目录
Makefile	测试构建脚本

SDF接口样例包括SM1、SM2、SM3、SM4、随机数算法的功能及性能测试。

2 安装与部署

演示操作在以下环境完成验证：

CPU	主机操作系统	内核版本	位数
Intel Xeon 8269CY@2.50GHz	CentOS Linux release 7.8.2003	3.10.0-1127	64bit

2.1 硬件安装

密码卡与服务器主板互连的步骤如下：

（1）顺着插槽，将密码卡的接口完全接入对应插槽中；

（2）将UKey（若选配）连接到服务器主板的USB插座上。

2.2 软件部署

2.2.1 编译软件

（1）开机上电，可以通过以下命令查看设备是否成功识别密码卡（该命令需要root权限）。

#lspci -d 1dab:7001 -vvv

说明：虚拟机pci设备号1dab:8002；PCIe带宽PCIe2.0×8（带宽需要匹配物理卡金手指、固件配置和主机适配综合得出）。

（2）首先，软件运行的依赖程序，请参考以下命令进行安装。

# 安装基础开发工具
$ yum groupinstall Development tools

# 安装内核头文件
$ yum install "kernel-devel-uname-r == $(uname -r)"

（3）使用make命令进行一键编译、安装。

# 进入 sdk 路径，执行make进行编译
$ make

# 执行make install进行安装
$ make install

备注：执行安装操作时，会自动将对应的.so动态库文件拷贝至系统/lib/目录下，应用程序如果要调用该动态库，部分系统需要执行ldconfig命令。

3 SDF接口测试

3.1 测试准备

在SDK目录下，执行make、make install，进行驱动和动态库的安装，部分系统需要执行ldconfig命令，使动态库可以被正常使用。

3.2 测试内容

3.2.1 算法正确性测试

examples目录下的std_sm1、std_sm2、std_sm3、std_sm4、std_random测试为国密算法正确性测试。可逐个执行。

3.2.2 算法性能测试

examples目录下的perf_sm14、perf_sm2、perf_sm3、perf_random为算法性能测试。

（1）perf_sm14——SM1、SM4算法性能测试

$ ./perf_sm14
PIICO EncryptCard SM1&SM4 test ....
Please input test times:10000
Please input test length:2048
Please input test threadnum (<640):32
Please input test Alog:
SM1_ECB_Encrypt--------------1
SM1_ECB_Decrypt--------------2
SM1_CBC_Encrypt--------------3
SM1_CBC_Decrypt--------------4
SM4_ECB_Encrypt--------------5
SM4_ECB_Decrypt--------------6
SM4_CBC_Encrypt--------------7
SM4_CBC_Decrypt--------------8

依次输入每线程测试循环次数、加解密数据长度、线程数、具体运算选择，执行测试后可以获得国密对称算法性能。

（2）perf_sm2——SM2算法性能测试

$ ./perf_sm2
PIICO EncryrptCard SM2 test .....
Please input test times:10000
Please input test threadnum (1~10):32
Please input test Alog:1:ECC_Enc 2:ECC_Dec: 3:ECC_Sign 4:ECC_Ver 5:ECC_Gen
Please Select:

依次输入每线程测试循环次数、线程数、具体运算选择（1、SM2加密 2、SM2解密 3、SM2签名 4、SM2验签 5、SM2密钥对生成），执行测试后可以获得SM2算法各指标性能。

（3）perf_sm3——SM3算法性能测试

$ ./perf_sm3
PIICO EncryptCard SM3 test...
Please input test times:10000
Please input test length:1536
Please input test threadnum (<640):32

依次输入每线程测试循环次数、杂凑数据长度、线程数，执行测试后可以获得SM3算法性能。

（4）perf_random——随机数性能测试

$ ./perf_random 
PIICO Random Perf test ....
Please input test times:10000
Please input test length:1536
Please input test threadnum (<640):8

依次输入每线程测试循环次数、取随机数据长度、线程数，执行测试后可以获得随机数生成性能。

3.2.3 SDF接口杂项测试

examples目录下的menu测试程序包含所有SDF接口的功能测试。

$ ./menu 
       ====================== PIICO API Test Program================= 
   Copyrigth 2023 WuXi PIICO information Technology Co.,Ltd 

                 Device Manage ------------- 2
                 key Manage ---------------- 3
                 SM2 Algo ------------------ 4
                 SM1&SM4&SM3 Algo ---------- 5
                 File Ope ------------------ 6
                 Capability test ----------- 8
                 Quit  --------------------- 0

包括设备管理类接口、密钥管理类接口、算法接口、文件接口的功能测试及单线程的性能测试。可按需测试。

4 管理工具操作指南

4.1 工具简介

密码卡管理工具可用于完成密码卡的初始化配置，包括设备管理、用户管理、密钥管理和文件管理功能；

4.1.1 运行管理工具

# 参数 1 为设备编号，范围 [1~33]
$ ./tools/bin/kmt 1
==================================================
密 管 工 具
主菜单:

*01.    设备管理
*02.    用户管理
*03.    密钥管理
*04.    文件管理
*00.    退出
==================================================

4.2 设备管理

在管理工具界面，输入1，可进入设备管理。

# ./tools/bin/kmt 1
==================================================
                    密  管  工  具
主菜单:    

*01.  设备管理          
*02.  用户管理          
*03.  密钥管理          
*04.  文件管理          
*00.  退出   
==================================================
输入选项: 1
==================================================
                    设  备  管  理
 菜单:     

*01.  获取设备信息            
*02.  获取设备状态            
*03.  获取设备配置            
*04.  设备初始化         
*05.  设置设备序列号           
*06.  设备自检          
*07.  固件升级          
*08.  恢复出厂          
*09.  固件日志等级            
*00.  退出 
==================================================
输入选项:

4.2.1 获取设备信息

==================================================
输入选项：1 
厂商名称: PIICO
设备名称: RSP10
设备序列号: 3aad1a19126e9faf
接口版本: 0x02000306
固件版本: 2.0.3.6

支持的非对称算法: RSA_SIGN|RSA_ENC|SM2_1|SM2_2|SM2_3
支持的对称算法: AES256_ECB|AES256_CBC|AES256_CFB|AES256_OFB
               AES128_ECB|AES128_CBC|AES128_CFB|AES128_OFB|AES128_XTS
               AES192_ECB|AES192_CBC|AES192_CFB|AES192_OFB
               SM4_ECB|SM4_CBC|SM4_CFB|SM4_OFB|SM4_XTS
               SM1_ECB|SM1_CBC|SM1_CFB|SM1_OFB
支持的摘要算法: SM3|SHA256
获取设备信息成功!
==================================================

4.2.2 获取设备状态

==================================================
输入选项：2
设备状态    :DEVICE_FSM_CHECK
密钥状态    :0x00000001
提交号      :0x5E6493A5
工作主频    :500M
PCIE 信息   :GEN2 X8
芯片温度    :0.00 C
芯片电压    :0.00 V
板卡温度    :53.38 C
板卡电压    :-1.00 V
板卡电流    :607.91 ma
FS 总容量   :47 KB
FS 可用容量 :47 KB
错误码      :0x00000000

获取设备状态成功!
==================================================

4.2.3 获取设备配置

==================================================
输入选项：3
安全等级 : 无访问控制
存储容量 : 6144 KB
设备数量 : 33 个
管理员数量 : 3 个
操作员数量 : 1 个
RSA 密钥数量 : 6 对
SM2 密钥数量 : 15 对
对称密钥数量 : 1024 个
会话密钥数量 : 124 个
文件系统容量 : 64 KB

获取设备配置成功!
==================================================

4.3 用户管理

在管理工具界面，输入2，可进入用户管理。

输入选项：2
==================================================
用 户 管 理
菜单:
*01. 添加用户
*02. 删除用户
*03. 登录用户
*04. 登出用户
*05. 设置用户口令
*06. 获取用户信息
*00. 退出
==================================================

4.4 密钥管理

在管理工具界面，输入3，可进入密钥管理。

输入选项: 3
==================================================
                    密  钥  管  理                
 菜单:                                            

*01.  查看密钥状态            
*02.  生成用户密钥            
*03.  删除用户密钥            
*04.  操作私钥访问权限          
*05.  设置私钥访问控制码             
*06.  备份用户密钥            
*07.  恢复用户密钥            
*00.  退出                                          
==================================================

4.5 文件管理

在管理工具界面，输入4，可进入文件管理。

输入选项: 4
==================================================
                    文  件  管  理                
 菜单:                                            

*01.  文件系统初始化           
*02.  枚举文件          
*03.  添加文件          
*04.  删除文件          
*05.  读取文件          
*06.  写入文件          
*00.  退出

6 初始化

提示：密码卡的初始化工作，默认在出厂时完成，用户无需再次进行初始化。

特殊情况下，如需要再次重新初始化，可按照以下步骤进行：

（1）在SDK目录下，执行make、make install，进行驱动和动态库的安装。

（2）使用piicoTool命令进行初始化

在tools/bin/目录下，使用编译出来的piicoTool工具，使用-init参数进行sdf接口初始化。

# cd tools/bin/
$ ./piicoTool -init

之后程序会自动执行：

生成私钥使用权限码（默认值3.1415926）
生成内部SM2密钥对
生成KEK密钥
初始化文件系统

完成初始化后，可以使用SDF接口。

8 常见故障处理

问：缺少内核头文件，软件编译 faild

答：编译驱动时提示没有 kernel 头文件，编译不通过。此时需要使用 yum apt等工具安装指定版本。Centos 操作系统可使用以下命令安装：$ yum install "kernel-devel-uname-r == $(uname -r)"

问：调用密码卡时打开设备失败，系统未识别到密码卡

答：请确认系统是否识别到密码卡。可以使用lspci -d 1dab:7001 -vvv命令，查看信息是否含有当前密码卡的设备号，不同型号的密码卡 pci 设备号不同，如果存在，说明系统识别到密码卡；否则，未识别到密码卡，请重新插拔或者更换插槽后重试。

问：性能测试与指标有偏差

答：我司提供的性能测试结果基于Intel(R) Xeon(R) Silver 4210 CPU @ 2.20GHzCPU完成。如指标类似但实测性能和手册指标差异较大，可以从以下几个方向进行排查：

（1）检查 PCIE Link 状态是否正常；

（2）测试使用的 CPU CoreID 是否与密码卡绑定的 NUMA 相对应；

问：PCIe 信号故障

答：lspci -d 1dab:700X -vvv查看，导出日志，联系 FAE 解决。