SafeW如何为遗留系统配置国密算法密钥接口？
功能定位：国密算法在SafeW里的角色
SafeW把国密算法视为一条「合规可审计」的加密基线，而非简单的算法替换。它将SM2密钥对、SM3摘要、SM4分组加密封装成一套「国密Provider」，供旧系统通过JCE、PKCS#11或REST三种形态调用。核心关键词「SafeW国密接口」首次出现，后续简称「国密Provider」。
相比原生OpenSSL，SafeW额外完成两件事：一是把私钥锁进手机TEE+SE，云端零留存；二是把每一次签名事件写成不可篡改的审计日志，直接输出成欧盟MiCA、美国TIA都能读的CSV模板。经验性观察：在同等CPU占用下，SM2签名耗时比ECDSA P-256长约20%，但换来的是国密合规与审计友好，对金融、政企遗留系统反而节省二次过检成本。
变更脉络：从v5.9到v6.3.0的演进
v5.9仅提供SM2静态库，需要开发者自己写JNI；v6.1把SM2/SM3/SM4打包进「RegCheck」模块，但只支持移动端本地调用；v6.3.0新增「Legacy Bridge」子进程，专门给Windows/Linux老后台用，通过本地回环HTTP+JSON转发，实现「零改造」嵌入。只要旧系统能发HTTP POST，十分钟内即可接入国密。
版本差异带来的坑：v6.2之前生成的SM2私钥是PKCS#8明文，v6.3.0默认用SM4-CBC包裹，旧系统若直接读PEM会报「invalid private key」。SafeW在升级时自动把老密钥转格式，但只保留30天，逾期需用助记词重新导入。
前置条件：软硬件与合规清单
- 手机端：Android 10+/iOS 15+，且已升级至SafeW v6.3.0（截至当前的最新版本）
- 桌面端：Windows 10 22H2、Windows Server 2016、Ubuntu 20.04 LTS以上，已安装Legacy Bridge安装包（官网→Business→Download→「Legacy Bridge (SM)」）
- 国密资质：服务端需持有国家密码管理局颁发的《商用密码产品认证证书》二级以上，或直接使用SafeW提供的白标云HSM（已内置）
- 网络：Legacy Bridge与手机必须处于同一内网段，或通过手机USB网络共享，禁用代理避免证书钉扎失效
不满足以上任一条件，RegCheck审计报告会被标记为「环境不合规」，直接触发SafeW的「强制离线」策略：所有签名接口返回403，直到重新过检。
操作路径：三步完成接口配置
Step 1 手机端生成SM2密钥对
打开SafeW→「工具箱」→「国密中心」→「生成密钥」，选择「用途：遗留系统调用」，算法默认SM2。此时会提示你「是否把私钥锁定到TEE」，选「是」。完成后出现二维码，包含证书SN与端点IP，有效期30分钟。
Step 2 桌面端启动Legacy Bridge
Windows：开始菜单→SafeW Legacy Bridge→右键「以管理员身份运行」，首次启动会弹出防火墙授权，务必勾选「专用网络」。Linux：解压后执行sudo ./sm-bridge --daemon，默认监听127.0.0.1:2626。
手机扫码后，Bridge自动写入配置：~/.safew/bridge.json（Windows路径在%ProgramData%\SafeW\bridge.json）。若扫码超时，可手动在手机端「国密中心」→「遗留系统」→「手动输入IP」填入电脑内网地址。
Step 3 旧系统发HTTP POST测试
旧系统只要支持HTTP即可，无需额外驱动。下面给出最小Python示例，验证SM2签名：
import requests, base64
payload = {
"api": "sm2_sign",
"data": "48656c6c6f", # Hex格式
"key_sn": "SM2-12345678"
}
r = requests.post("http://127.0.0.1:2626/gw", json=payload)
print(base64.b64decode(r.json()["sig"]))
若返回200且sig长度64字节，即表示链路打通。此时SafeW手机端会弹出「生物识别确认」弹窗，指纹/人脸通过后签名回传，全程私钥不离开TEE。
平台差异速查
| 平台 | 最短路径 | 注意点 |
|---|---|---|
| Android | 侧边栏→国密中心→生成密钥 | 需授予「附近设备」权限，否则USB共享网络失败 |
| iOS | 底栏→工具箱→国密中心 | 若用Lightning网线转接，需关闭「私有地址」避免IP漂移 |
| Windows Server | 开始菜单→Legacy Bridge（管理员） | 蓝屏0xD4需手动打KB600317补丁 |
| Ubuntu | ./sm-bridge --daemon | 需libssl1.1，若22.04缺失可apt install libssl1.1t |
例外与取舍：何时不该用国密接口
1. 海外业务为主：若用户集中在北美、欧盟，SM2证书默认不在浏览器信任链，需要额外植入根证书，维护成本高于直接用ECDSA P-256。
2. 高频低延迟场景：经验性观察，SM2签名+TEE弹窗确认整体耗时约600-900 ms，而传统软签ECDSA仅20 ms。交易所撮合引擎、游戏实时背包等场景会明显卡顿。
3. 纯离线环境：Legacy Bridge依赖手机在线，若机房禁止任何无线信号，则无法完成生物识别确认，只能回退到预置密钥卡，失去SafeW「私钥零导出」优势。
故障排查：签名返回403 NoPerm
- 现象：旧系统POST后返回403，手机无弹窗
- 可能原因：RegCheck发现电脑系统时间偏差＞5分钟
- 验证：在Bridge日志搜索
clock_skew字段，若值>5000即命中 - 处置：在电脑启用NTP同步，重启Bridge，再次请求即可
若日志出现cert_chain_exired，则是手机端证书已过有效期（默认1年），需在「国密中心」→「续期」里重新扫码，旧系统的key_sn会保持不动，无需改代码。
适用/不适用场景清单
| 维度 | 适用 | 不适用 |
|---|---|---|
| 行业合规 | 金融、政企、医疗等需国密过检 | 纯海外Web3游戏、NFT发行 |
| 并发量 | <200次/分钟，可接受TEE延迟 | 高频撮合、实时物联网指令 |
| 改造预算 | 零代码HTTP即可接入 | 旧系统语言无HTTP库（如COBOL） |
| 离线要求 | 可短暂离线，48h内再同步 | 长期离线、无移动设备 |
最佳实践清单（可直接贴墙）
- 上线前先在「沙盒模式」跑1000笔签名，确认无403/500再切正式
- 把Bridge监听端口从2626改成非标端口，并在防火墙限制仅旧系统IP可访问
- 每季度做一次「续期演练」，避免证书过期导致凌晨告警
- 审计CSV用Git LFS归档，保留7年，文件名带UTC时间，方便MiCA抽查
- 若业务高峰需横向扩展，可在多台电脑起Bridge，手机端用「多设备授权」把同一密钥映射到多台Bridge，负载均衡用Round-Robin即可
FAQ（结构化数据）
旧系统只支持PKCS#11，能否不用HTTP？
可以。SafeW v6.3.0的Legacy Bridge附带libsw_pkcs11.so（Windows为sw_pkcs11.dll），把驱动路径填入旧系统即可，接口仍是HTTP，只是被驱动封装成C_Login/C_Sign，无需改业务代码。
TEE弹窗失败3次被锁，如何应急？
用助记词在「设置→安全→冷恢复」里重新生成密钥对，旧key_sn即刻作废，需在旧系统配置里更新对应证书。整个过程约3分钟，RegCheck会写入「应急恢复」事件，不影响审计连续性。
Bridge日志占用磁盘暴涨，如何清理？
Linux下执行logrotate -f /etc/logrotate.d/safew-bridge，Windows在「设置→日志→归档」里勾选「保留最近30天」。切勿直接删除日志，否则RegCheck校验会报「日志缺失」。
结语与下一步
SafeW的国密接口把「合规」「零改造」「可审计」三件事打包成一条HTTP通道，对预算紧张、排期紧凑的遗留系统尤其友好。记住：先沙盒、再续期、最后归档，三步走稳，MiCA/BaFin抽查就能一次过。
下一步，建议你下载最新版本Legacy Bridge，在测试环境跑通上述Python脚本；然后把签名耗时、审计CSV大小两项指标 baseline 化，作为后续版本升级的量化依据。若需更高并发，可关注SafeWare官方白皮书《TEE并行调度模型》，但截至当前尚未发布正式版，社区仅流出经验性观察，切勿用于生产承诺。