B系列密码卡SDK用户手册
本文档介绍了如何使用派科信安B系列密码卡SDK，其包括源码包、文档、固件和相关工具。
本文档适用于帮助客户验证密码卡功能、性能和基于密码卡API接口二次开发。
适用范围
此手册适用于派科信安的如下PCIe密码卡：
- B系列：B1、B2、B3
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接口 | |
| crypto | - | 软件密码算法中间库 | |
| sdf | - | SDF接口封装库 | |
| gmssl_engine | - | GmSSLEngine硬件适配 | |
| openssl_engine | - | OpenSSLEngine硬件适配 | |
| lib | - | - | 存放编译成功的libsdf.so和libsdf.a库 |
| tools | basic_tools | - | BAR空间读写工具，调试工具等 |
| capbenchmark | - | 接口性能测试工具 | |
| kmt | - | 管理工具 | |
| piicoTool | - | Piico卡SDF接口应用初始化工具 | |
| include | - | - | sdf接口头文件 |
| examples | - | - | SDF接口使用样例程序 |
| application | kci_test | - | kci接口测试工具 |
| nginx | asynch_mode_nginx_v0.4.0.zip | 异步支持的Nginx，用于nginx硬件加速的性能测试 | |
| Nginx_Patch | 补丁文件 | ||
| Nginx_Test | Nginx测试工具 | ||
| common | gmssl | - | GmSSL软件库 |
| openssl | - | openssl-1.1.1k软件库 | |
| script | - | 通用脚本 | |
| ukey | - | 密钥库 | |
| run_testcase | run_benchmark.sh | - | 运行benchmark测试脚本 |
| run_openssl.sh | - | 运行openssl测试脚本 | |
| run_kmt.sh | - | 运行kmt脚本 | |
| run_nginx.sh | - | 运行nginx测试场景脚本 |
SDK整体架构中，从上到下包括SDF、CAP API、同步/异步API。其中CAP API是比较重要的一个模块，该模块包含了算法API和密钥管理API,支撑上层SDF接口。用户可基于此扩展其他密码接口。
注意：我司对SDF接口和CAP API接口及以下部分做产品级维护、升级，应用层TLS加速、Nginx、IPsec等模块仅作为方案推广演示使用。
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命令。
（4）可选编译gmssl、openssl、Nginx
然后，可选编译common目录下的openssl和gmssl源码，以及application下的nginx源码。SDK编译需要用到openssl和gmssl相关头文件。SDK提供已编译好的openssl和gmssl，用户可根据自己的系统重新从源码编译。
2.2.2 密码卡登录
安装完成后，需要使用kmt工具进行用户登录。
$ ./tools/bin/kmt
==================================================
密 管 工 具
主菜单:
*01. 设备管理
*02. 用户管理
*03. 密钥管理
*04. 文件管理
*00. 退出
==================================================
输入选项: 2
==================================================
用 户 管 理
菜单:
*01. 添加用户
*02. 删除用户
*03. 登录用户
*04. 登出用户
*05. 设置用户口令
*06. 获取用户信息
*00. 退出
==================================================
输入选项: 3
请输入登陆 PIN 码: 1234567812345678
登录用户成功!
==================================================
用 户 管 理
菜单:
*01. 添加用户
*02. 删除用户
*03. 登录用户
*04. 登出用户
*05. 设置用户口令
*06. 获取用户信息
*00. 退出
==================================================
3 SDF接口测试
3.1 测试准备
（1）加载驱动
在SDK目录下，执行make、make install，进行驱动和动态库的安装，部分系统需要执行ldconfig命令，使动态库可以被正常使用。
（2）管理员登录
若未管理员登录，使用SDK目录下的kmt工具进行管理员登录。
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 工具简介
密码卡管理工具可用于完成密码卡的初始化配置，包括设备管理、用户管理、密钥管理和文件管理功能；
密码卡支持三种访问控制策略：主机端Ukey访问控制模式、口令访问控制模式、无访问控制模式。
当配置为主机端Ukey访问控制模式时，支持三个管理员Ukey和1个操作员Ukey。密码卡出厂默认配置为无访问控制模式。
4.1.1 运行管理工具
# 参数 1 为设备编号，范围 [1~33]
$ ./tools/bin/kmt 1
==================================================
密 管 工 具
主菜单:
*01. 设备管理
*02. 用户管理
*03. 密钥管理
*04. 文件管理
*00. 退出
==================================================
4.2 设备管理
# ./tools/bin/kmt 1
==================================================
密 管 工 具
主菜单:
*01. 设备管理
*02. 用户管理
*03. 密钥管理
*04. 文件管理
*00. 退出
==================================================
输入选项: 1
==================================================
设 备 管 理
菜单:
*01. 获取设备信息
*02. 获取设备状态
*03. 获取设备配置
*04. 设备初始化
*05. 固件升级
*06. 恢复出厂
*00. 退出
==================================================
输入选项:
4.2.1 获取设备信息
==================================================
输入选项：1
厂商名称: PIICO
设备名称: RSP10
设备序列号: 3aad1a19126e9faf
设备版本: 0xff010000
获取设备信息成功!
==================================================
4.2.2 获取设备状态
==================================================
输入选项：2
设备状态: 0x00000004
提交号: 0xC4B17E8A
工作主频: 500M PCIE 信息: GEN2 X8
芯片温度: 38.49 C
芯片电压: 0.99 V
板卡温度: 40.38 C
板卡电压: 12.00 V
板卡电流: 698.85 ma
错误码: 0x00000000
获取设备状态成功!
==================================================
4.2.3 获取设备配置
==================================================
输入选项：3
安全等级: 无访问控制存储容量: 30720 KB
设备数量: 32 个
管理员数量: 3 个
操作员数量: 1 个 RSA 密钥数量: 256 对 SM2 密钥数量: 256 对
对称密钥数量: 1024 个
会话密钥数量: 1024 个
文件系统容量: 64 KB
获取设备配置成功!
==================================================
4.2.4 设备初始化
设备初始化不建议采用此命令接口，可以直接使用piiTool -init命令进行初始化操作。详见初始化章节。
4.2.5 恢复出厂
恢复出厂不建议采用此命令接口，可以直接使用piiTool -factory命令进行初始化操作。详见初始化章节。
4.3 用户管理
输入选项：2
==================================================
用 户 管 理
菜单:
*01. 添加用户
*02. 删除用户
*03. 登录用户
*04. 登出用户
*05. 设置用户口令
*06. 获取用户信息
*00. 退出
==================================================
4.3.1 获取用户信息
==================================================
输入选项：6
已注册管理员数量: 0 个
已登录管理员数量: 0 个
已注册操作员数量: 0 个
已登录操作员数量: 0 个获取用户信息成功!
==================================================
4.3.2 添加用户
注意：每个 Ukey 只有一种角色，添加用户操作会清空 Ukey 信息，请确认 Ukey 信息后继续。
==================================================
输入选项：1
========================================================
! 该操作会清空当前 Ukey 内的角色信息, [0] 退出, 任意键继续;
========================================================
: 1
请插入 Ukey, 输入待增加用户类型, 1 - 管理员，2 - 操作员：1请输入待添加用户索引, 范围 [1 ~ 3]：1
请输入 16 字节 Ukey 保护口令：1234567812345678添加用户成功!
==================================================
注意：添加用户需要在 ukey 模式下，无访问控制和 pin 码访问控制都不可以添加。
4.3.3 登录用户
==================================================
输入选项：3
请插入 Ukey 并输入用户类型, 1 - 管理员，2 - 操作员：1请输入用户索引, 范围 [1 ~ 3]：1
请输入 16 字节 Ukey 保护口令：1234567812345678登录用户成功!
==================================================
4.3.4 登出用户
==================================================
输入选项：4
请输入用户类型, 1 - 管理员，2 - 操作员：1请输入用户索引, 范围 [1 ~ 3]：1
登出用户成功!
==================================================
4.3.5 删除用户
该操作需要在管理态执行；
==================================================
输入选项：2
请输入待删除用户类型, 1 - 管理员，2 - 操作员：1请输入待删除用户索引, 范围 [1 ~ 3]：1
删除用户成功!
================================================
4.3.6 设置用户口令
注意：UKey默认保护口令为1234567812345678，请妥善保管该口令，如果忘记UKey保护口令造成UKey锁死，请联系厂商进行解锁操作。
==================================================
输入选项：5
请插入 Ukey 并输入 16 字节旧 Ukey 保护口令:1234567812345678请输入 16 字节新 Ukey 保护口令:1234567812345678
请请再次输入 16 字节新 Ukey 保护口令:1234567812345678
设置用户口令成功!
==================================================
4.4 密钥管理
==================================================
密 钥 管 理
菜单:
*01. 获取密钥信息
*02. 生成用户密钥
*03. 删除用户密钥
*04. 设置私钥访问控制码
*05. 备份用户密钥
*06. 恢复用户密钥
*00. 退出
==================================================
4.4.1 查看密钥状态
==================================================
输入选项：1
请输入密钥类型：
1 - SM2 签名密钥对
2 - SM2 加密密钥对
3 - RSA 签名密钥对
4 - RSA 加密密钥对
5 - 密钥加密密钥
6 - 会话密钥
0 - 退出
: 1
SM2 签名密钥 [密钥索引 - 001] 状态 : 空闲, 长度 0 位
SM2 签名密钥 [密钥索引 - 002] 状态 : 空闲, 长度 0 位 SM2 签名密钥 [密钥索引 - 003] 状态 : 空闲, 长度 0 位 SM2 签名密钥 [密钥索引 - 004] 状态 : 空闲, 长度 0 位 SM2 签名密钥 [密钥索引 - 005] 状态 : 空闲, 长度 0 位 # 省略部分日志
获取密钥状态成功!
==================================================
4.4.2 生成密钥
==================================================
输入选项: 2
请输入密钥类型:
1 - SM2 签名密钥对
2 - SM2 加密密钥对
3 - RSA 签名密钥对
4 - RSA 加密密钥对
5 - 密钥加密密钥
0 - 退出
: 1
[0 退出] 请输入密钥索引, 范围 [1 - 256]: 1
[0 退出] 请输入密钥私钥访问控制码, 最大 16 字节: 12345678
生成用户密钥成功!
==================================================
4.4.3 设置私钥访问控制码
==================================================
输入选项: 4
请输入密钥类型:
1 - SM2 签名密钥对
2 - SM2 加密密钥对
3 - RSA 签名密钥对
4 - RSA 加密密钥对
0 - 退出
: 2
[0 退出] 请输入密钥索引, 范围 [1 - 256]: 1
请输入原私钥访问控制码:12345678原私钥访问控制码验证成功
请输入新私钥访问控制码, 最大长度 16 字节: 2345678
请再次输入新私钥访问控制码, 最大长度 16 字节:
2345678
新私钥访问控制码设置成功设置私钥访问控制码 成功!
==================================================
4.4.4 删除密钥
==================================================
输入选项: 3
请输入密钥类型:
1 - SM2 签名密钥对
2 - SM2 加密密钥对
3 - RSA 签名密钥对
4 - RSA 加密密钥对
5 - 密钥加密密钥
0 - 退出
: 1
[0 退出] 请输入密钥索引, 范围 [1 - 256]: 1
删除用户密钥成功!
==================================================
4.4.5 密钥备份
==================================================
输入选项: 5
！ 该口令不是登录口令，不能修改，如果忘记该口令，将导致本次备份无法恢复
[0 退出] 请输入备份密钥口令: 123456
请再次输入口令
！ 该口令不是登录口令，不能修改，如果忘记该口令，将导致本次备份无法恢复
[0 退出] 请输入备份密钥口令: 123456
[0 退出] 请输入保存的备份文件名: BackKey
备份数据长度: 901120 字节备份用户密钥成功!
==================================================
4.4.6 密钥恢复
==================================================
输入选项: 6
===================================================
! 如果密钥容量较大, 该操作可能会占用几分钟时间, 请等待
===================================================
！ 该口令不是登录口令，不能修改，如果忘记该口令，将导致本次备份无法恢复
[0 退出] 请输入备份密钥口令: 123456
[0 退出] 请输入保存的备份文件名: BackKey
恢复数据长度: 901120 字节
恢复用户密钥成功!
==================================================
4.5 文件管理
==================================================
文 件 管 理
菜单:
*01. 文件系统初始化
*02. 枚举文件
*03. 添加文件
*04. 删除文件
*05. 读取文件
*06. 写入文件
*00. 退出
==================================================
4.5.1 文件系统初始化
==================================================
输入选项: 1
文件系统初始化成功!
==================================================
4.5.2 枚举文件
==================================================
输入选项: 2
[01] 文件名称: 123
[02] 文件名称: 234
枚举文件成功!
==================================================
4.5.3 添加文件
==================================================
输入选项: 3
[0 退出]请输入文件名: 234
创建文件成功.添加文件成功!
==================================================
注意：添加重复名称的文件，会添加失败。
4.5.4 删除文件
==================================================
输入选项: 4
[0 退出]请输入文件名: 234
删除文件成功删除文件成功!
==================================================
4.5.5 读取文件
==================================================
输入选项: 5
[0 退出]请输入文件名: 123
请输入起始位置: 1
请输入读取长度: 9读取文件成功 12345678
读取文件成功!
==================================================
4.5.6 写入文件
==================================================
输入选项: 6
[0 退出]请输入文件名: 123
请输入起始位置: 1
请输入写入长度: 9
请输入写入数据: 12345678
写入文件成功写入文件成功!
==================================================
5 性能测试
5.1 算法性能
使用以下命令测试硬件 CAP 层接口调用的性能。参考性能请见第 4 章节技术指标和性能。
5.1.1 同步性能
CAP 层接口为用户态接口，测试前需配置用户态模式。
CAP 层接口为用户态接口，测试前需配置用户态模式。
# 运行性能测试脚本; <设备 ID> <线程数量> <同步模式>
$ ./run_testcase/run_benchmark.sh 1 128 1
SM2-KG : 305385.656250(tps),
SM2-KP : 86384.906250(tps),
SM2-ENC : 54665.718750(tps),
SM2-DEC : 65344.261719(tps),
SM2-SIGN : 266869.406250(tps),
SM2-VERIFY : 108262.195312(tps),
# 省略部分日志内容
5.1.2 异步性能
# 运行性能测试脚本; <设备 ID> <进程数量> <异步模式>
$ ./run_testcase/run_benchmark.sh 1 8 0
SM2-KG
: 305903.093750(tps),
SM2-KP : 86487.601562(tps),
SM2-ENC : 54768.097656(tps),
SM2-DEC : 65401.019531(tps),
SM2-SIGN : 268734.250000(tps),
SM2-VERIFY : 108304.867188(tps),
# 省略部分日志内容
5.2 OpenSSL 性能
OpenSSL 版本为 1.1.1K，本章节内容适用于B系列密码卡。
5.2.1 测试说明
# 测试脚本说明
$ ./run_testcase/run_openssl.sh
# 参数 1: 启用 CPU Core 数量;
# 参数 2: 算法名称:[rsa2048/sm2-encrypt/sm2-sign/ecdsa-p256/ecdh-p256]
# 参数 3: 测试类型(hw: 硬件, sw: 软件);
# 参数 4: 测试时间(秒)，取值阿拉伯数字，默认 5;
# 参数 5: 起始 CPU CoreID，默认 0 核;
5.2.2 性能参照
RSA-2048 签名
| RSA-2048 签名 | |||
|---|---|---|---|
| 模式 | 命令 | Sign/s | Verify/s |
| 软件 | ./run_testcase/run_openssl.sh 1 rsa2048 sw | 1489.8 | 40556.0 |
| 硬件 | ./run_testcase/run_openssl.sh 1 rsa2048 hw | 41768.4 | 155895.2 |
SM2 加密
| SM2 加密 | |||
|---|---|---|---|
| 模式 | 命令 | op/s | op/s |
| 软件 | ./run_testcase/run_openssl.sh 2 sm2-encrypt sw | 1236.0 | 2450.6 |
| 硬件 | ./run_testcase/run_openssl.sh 2 sm2-encrypt hw | 50681.7 | 57112.0 |
SM2 签名
| SM2签名 | |||
|---|---|---|---|
| 模式 | 命令 | Sign/s | Verify/s |
| 软件 | ./run_testcase/run_openssl.sh 4 sm2-sign sw | 4658.8 | 4679.3 |
| 硬件 | ./run_testcase/run_openssl.sh 4 sm2-sign hw | 230787.4 | 113154.8 |
ECDSA-P256 签名
| ECDSA-P256 签名 | |||
|---|---|---|---|
| 模式 | 命令 | Sign/s | Verify/s |
| 软件 | ./run_testcase/run_openssl.sh 4 ecdsa-p256 sw | 109124.0 | 42736.6 |
| 硬件 | ./run_testcase/run_openssl.sh 4 ecdsa-p256 hw | 200075.7 | 115312.4 |
ECDH-P256
| ECDH-P256 | ||
|---|---|---|
| 模式 | 命令 | op/s |
| 软件 | ./run_testcase/run_openssl.sh 2 ecdh-p256 sw | 32417.8 |
| 硬件 | ./run_testcase/run_openssl.sh 2 ecdh-p256 hw | 105191.8 |
5.3 Nginx 性能
本章节内容适用于B系列密码卡。先启用服务器，后启用客户端。
5.3.1 启用 Nginx服务
用户可根据服务器资源配置不同的参数完成 Nginx 服务部署。测试过程分为两部分，启用 Nginx 和启用压测工具：
# 终端 1 启用Nginx 服务
$ ./run_testcase/run_nginx.sh rsa-rsa 8 hw 0
# 参数 1: 测试套件(rsa-rsa/ecdhe-ecdsa/ecdhe-rsa); # 参数 2: 启用 CPU Core 数量;
# 参数 3: 测试类型(hw: 硬件, sw: 软件); # 参数 4: 起始 CPU CoreID;
5.3.2 客户端压测工具
以下过程可以在合适的测试场景下完成，本章节以本地回环测试为例，用户也可以使用其他的压测工具完成性能统计。
# 终端 2 启用 ab 测试脚本
$ ./run_testcase/run_abtest.sh localhost 8 8 0 # 参数 1: IP:Port;
# 参数 2: 启用 CPU Core 数量;
# 参数 3: 起始 CPU CoreID;
# 参数 4: 测试类型(1: 国密, 0: 国际);
5.3.3 性能参照
Nginx 性能测试建议优先完成启用 1 个 work_process 时的软硬件握手性能对比，在确认单核指标符合文档描述的情况下，逐步增加 work_process，同步查看压测程序对应 CPU Core 的占用率情况，服务端还是客户端都可能成为性能瓶颈，必要时可以使用局域网中多台服务器配合调优。
以下是 RSA-2K 的软硬件握手性能参考。
6 初始化
提示：密码卡的初始化工作，默认在出厂时完成，用户无需再次进行初始化。
特殊情况下，如需要再次重新初始化，可按照以下步骤进行：
（1） 在SDK目录下，执行make、make install，进行驱动和动态库的安装。
（2） 进入tools目录，并执行init.sh初始化脚本。
等待结果。执行命令后，需要等待几分钟等待系统自动编译部署，正确安装、部署后如下所示：
# cd tools/
# ./init.sh
! Wait Crypto Card Init ...... 118s
RSPLinuxSdk Deploy Done.
====================================================================
[T-1, FW: 1234ABCD] RSPS10-01:00.0-00 Monitor: 500M, GEN2 X1
IT: 0.00 C, IV: 0.00 V, BT: 0.00 C, BV: -1.00 V, Board Power: 0.00 W
====================================================================
注意：如果设备一直卡在 init 状态，1）请确定当前密码卡固件版本是否与 SDK 匹配；2）请尝试开启系统 IOMMU（x86 架构 intel_iommu=on iommu=pt）。
（3）sdf接口初始化
在tools/bin/目录下，使用编译出来的piicoTool工具，使用-init参数进行sdf接口初始化。
# cd tools/bin/
$ ./piicoTool -init
请输入序列号:2023040700101001
说明：需要用户输入自定义的卡序列号，长度不超过16字节。
之后程序会自动执行：
- 自动添加管理员PIN码（默认值1234567812345678），并登录
- 生成私钥使用权限码（默认值3.1415926）
- 生成内部SM2密钥对
- 生成KEK密钥
- 初始化文件系统
完成初始化后，可以使用SDF接口。
7 OpenSSL Engine
注意：我司对SDF接口和CAP API接口及以下部分做产品级维护、升级，应用层TLS加速、Nginx、IPsec等模块仅作为方案推广演示使用。
7.1 OpenSSL Engine
x84_64架构硬件平台：
#进入SKD目录
#建立环境变量
source common/script/openssl_env.sh
#编译engine
make -C lib_src/openssl_engine/
#测试engine
./common/openssl/openssl/bin/openssl engine libersp_nginx -t -c
(libersp_nginx) Reference implementation of RSP engine
[RSA, id-ecPublicKey, SM2, TLS1-PRF]
[ available ]
如需要从源码重新编译openssl，则需要执行以下步骤：
（1）先使用rm -rf common/openssl/openssl/命令清理SDK中自带的openssl程序；
（2）再使用./common/script/build_openssl.sh命令重新编译openssl程序。
注意：源码目录中自带的common/openssl/openssl为x86_64架构先的二进制程序，如果更换了硬件架构，则需要按照以上步骤重新编译openssl。
7.1 GMSSL Engine
x84_64架构硬件平台：
#进入SKD目录
#建立环境变量
source common/script/gmssl_env.sh
#编译engine
make -C lib_src/gmssl_engine/
#测试engine
./common/gmssl/gmssl/bin/gmssl engine libersp -t -c
(libersp) Reference implementation of RSP engine
[RSA, AES-128-CBC, AES-128-CTR, AES-256-CBC, AES-256-CTR, id-aes128-GCM, id-aes256-GCM, SMS4-CBC, SMS4-CTR, SMS4-GCM, SHA1, SHA256, SHA384, SHA512, SM3, MD5, id-ecPublicKey, TLS1-PRF]
[ available ]
如需要从源码重新编译gmssl，则需要执行以下步骤：
（1）先使用rm -rf common/gmssl/gmssl/命令清理SDK中自带的gmssl程序；
（2）再使用./common/script/build_gmssl.sh命令重新编译gmssl程序。
注意：源码目录中自带的common/gmssl/gmssl为x86_64架构先的二进制程序，如果更换了硬件架构，则需要按照以上步骤重新编译gmssl。
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 解决。