第三章 国密算法查询接口需求分析：业务场景与功能需求归纳总结
做接口设计前，我最怕什么？不是技术选型难，而是“需求没理清楚就开写代码”。
我记得几年前接一个金融项目，客户说“随便，你们定”。结果做到一半，对方突然说要支持硬件加密机。那叫一个痛。所以这一章，咱们把国密算法查询接口的业务场景和功能需求彻底理一理。你想想看，搞清楚需求，后面代码写得才踏实。
3.1 业务场景梳理
国密算法查询接口到底会在哪些地方被调用？我自己的习惯是先画一张“业务全景图”，把常见场景列出来。
- 政务数据交换：比如电子证照、公文流转，需要对数据做SM3摘要和SM2签名。查询接口用来获取算法参数、密钥状态。
- 金融交易系统：支付报文用SM4加密，交易密码用SM3哈希。接口需要提供算法版本、密钥生命周期。
- 物联网终端：设备资源有限，查询接口要轻量，返回算法标识与最低安全等级即可。
- 第三方应用集成：外部系统调用国密API前，先查询可用的算法列表、互补模式（如SM2+SM3+SM4联用）。
- 合规审计：监管要求记录每次算法查询日志，接口需暴露查询历史与算法配置变更记录。
我的一点小经验：政务和金融场景对算法版本号非常敏感。曾经有客户因为SM2曲线参数用了不同实现导致验签失败——后来我们在查询接口里强制返回算法OID和参数标准号，才堵住这个坑。
从这些场景能看出，查询接口不只是“给一个返回值”那么简单。它还得承担起算法生命周期管理和版本协商的责任。说白了，查询结果是后续加密操作的“说明书”。
3.2 功能需求分类
把业务需求转化成功能点，我一般按三层来分：
| 需求层级 | 核心功能 | 典型输出 |
|---|---|---|
| 基础查询 | 获取支持的国密算法列表、各算法默认参数 | 算法标识、密钥长度、分组模式、初始向量要求 |
| 安全能力查询 | 查询当前环境的安全等级、可用密钥类型、硬件支持 | SM2密钥对生成状态、SM4 ECB/CBC模式、随机数源质量 |
| 审计与诊断 | 查询接口调用历史、算法配置变更记录、当前健康状态 | 时间戳、调用者IP、操作类型、返回码、异常堆栈 |
这里有个容易忽略的点：查询接口本身也要防攻击。我曾经在渗透测试里发现，某个查询接口暴露了密钥剩余天数，攻击者据此推算出密钥轮换窗口。后面我们做了脱敏处理，只返回“密钥状态：正常/即将过期/已过期”，不暴露具体天数。
3.3 接口需求详细说明
拿SM2签名验证场景举个例子。你调用签名前，得先知道三个事：
- 当前系统支持SM2哪种椭圆曲线（推荐使用
sm2p256v1）； - 签名算法是
SM2SignWithSM3还是其他模式； - 密钥ID对应的证书是否有效。
这些信息全部通过查询接口获取。我习惯把查询接口设计成无状态、幂等的RESTful GET请求，返回JSON结构。
GET /api/v1/sm/algorithm/query?type=sm2&action=sign
响应示例：
{
"code": 0,
"message": "success",
"data": {
"algorithm_id": "SM2-SM3-SIG",
"curve_name": "sm2p256v1",
"key_id": "KG-20231101",
"key_status": "active",
"key_expire": "2024-11-01T00:00:00Z",
"allowed_sign_count": 10000,
"min_security_level": 3
}
}
注意：
key_expire字段要对外暴露完整时间吗？我的建议是不要。返回相对状态（active/expiring_soon/expired），避免安全信息泄露。如果非要暴露，用加密后的令牌传递。
再强调一下参数可选性。比如查询SM4算法时，你只传type=sm4，接口返回所有支持的分组模式；如果你传了mode=ecb，只返回ECB模式的详细参数。这种渐进式查询设计，既减少响应体大小，又方便客户端做本地缓存。
3.4 非功能需求要点
功能之外，还有几个硬杠杠：
- 响应时间：99%的查询请求须在200ms内返回。我见过一个项目查询接口调用量是加密操作的10倍，慢查询直接拖垮整个系统。
- 可用性：查询接口作为前置服务，必须集群部署，故障后自动切换。我曾经遇到配置中心挂了导致所有查询返回空列表——后来加了本地缓存兜底。
- 频率控制：对同一调用方限制每秒50次，防止恶意刷库。这里要注意，正常的业务批处理也可能触发限流，所以配合令牌桶算法，允许短时突发。
- 日志完整性：所有查询请求必须记录，但不记录密钥明文。审计日志保留至少180天。
一句话总结：查询接口的稳定性直接影响后续加密操作的可用性。别把它当“小事”。我在生产上吃过亏，查询超时导致大批交易失败，血的教训。
3.5 需求分析框架图
下面这张图，帮你把上面讲的东西串起来。它展示了从业务场景到功能需求，再到接口定义和安全约束的整体关系。建议你拿它当需求文档的封面图。