cisd/docs/plans/2026-02-28-pcie-realcard-smoke-checklist.md

PCIe 真卡联调与冒烟检查清单

1. 前置条件

• 部署环境为目标架构（与生产一致的 CPU/OS/libc）。
• 已安装厂商 .so，并可被进程访问。
• 服务配置为 JNA 真卡模式：
  • tms.crypto-card.enabled=true
  • tms.crypto-card.mode=JNA
  • tms.crypto-card.vendor-lib-path 或 tms.crypto-card.vendor-lib-name 正确
  • tms.crypto-card.strict-alg-id-validation=true（若厂商扩展算法可临时关闭）
• 已知内部接口鉴权令牌 X-Internal-Token。

2. 核心检查项（必须通过）

1. 设备与会话
   • GET /api/v1/device/crypto/device-count
   • GET /api/v1/device/crypto/device-info
   • POST /api/v1/device/crypto/self-test
2. 基础密码能力
   • 随机数：GET /api/v1/device/crypto/random?length=16
   • 摘要：POST /api/v1/device/crypto/digest
   • HMAC：POST /api/v1/device/crypto/hmac
3. 对称能力
   • 明文密钥加解密：/encrypt/plain + /decrypt/plain
   • KEK 生成与状态：/kek/generate + /kek/status
4. 主密钥状态
   • GET /api/v1/device/crypto/lmk/seed-mac

验收标准：

• ApiResponse.success == true
• ApiResponse.code == 200
• 返回长度字段与 Base64 解码长度一致
• 错误日志中无 native 崩溃/段错误

3. 高风险专项

3.1 SDFE_ImportEncKeyPair_ECC（结构体直传）

• 用最小可用样本执行导入流程。
• 成功后立即查询相关密钥状态接口验证导入结果。
• 若出现参数错误，优先检查结构体字段对齐与 unsigned long 位宽。

3.2 ECCCipher 变长字段边界

• 对不同明文长度执行 ECC 加密路径。
• 记录返回 ECCCipher.l 的最大值。
• 若接近当前上限（C_MAX_LEN），必须提升上限并复测。

3.3 算法标识白名单

• 对业务实际用到的所有 algId 跑一遍。
• 若被严格校验拦截，补充到 Gm0018AlgorithmIds 后再回归。

4. 失败排查顺序

1. 配置错误：库路径、库名、鉴权 token。
2. 运行时依赖：ldd/动态库缺失。
3. 参数编码：Base64 入参、长度字段、结构体大小。
4. 算法标识：algId 是否在白名单。
5. 厂商错误码：结合 PcieErrorMapper 与厂商文档定位。

5. 回归策略

• 每次升级以下任一项，都执行本清单：
  • JDK 版本
  • 厂商 .so 版本
  • JNA 结构体定义
  • JnaPcieCryptoService 参数转换逻辑

6. 自动化模板

• 使用脚本：scripts/pcie_realcard_smoke.sh
• 建议在联调机和预生产各执行一次，并保留日志归档。