[密码学实战]GMT 0136-2024《密码应用HTTP接口规范》解析

[密码学实战]GM/T 0136-2024《密码应用HTTP接口规范》解析

国家密码管理局于2025年7月1日正式实施GM/T 0136-2024标准，该规范首次统一了密码服务的HTTP接口设计，为国产密码技术的规模化应用铺平道路。本文结合标准原文，深入剖析其技术细节并给出实战示例。

一、核心设计原则

1. RESTful架构规范

• URL前缀强制要求：所有接口路径必须以/shf/v1/开头（shf表示密码HTTP接口，v1为版本号）
• HTTP方法映射：
  • GET：查询操作（如获取算法列表）
  • POST：写操作（如加密、签名）
• 无状态设计：服务端不保存客户端上下文，每次请求需携带完整信息

2. NTV数据结构

为解决二进制数据传输问题，规范独创名称-类型-值（NTV） 结构：

{
  "Data": [
    {
      "Name": "PlainText",  // 参数名
      "Type": "Base64",     // 数据类型（Raw/Base64/Hex/DateTime）
      "Value": "SGVsbG8gV29ybGQ="  // 编码后的值
    }
  ]
}

3. 安全传输强制要求

• 必须使用TLCP协议（GB/T 38636）或等效安全传输层
• 错误响应禁止返回堆栈信息（防信息泄露）
• 支持证书双向认证

二、关键接口详解

1. 密码运算类接口

文件操作特殊处理：

• 使用FileUri代替直接上传文件（如"FileUri": "file:///data/test.txt"）
• 响应返回CallbackUri获取处理结果文件

2. 证书解析接口

POST /shf/v1/ParseCertificate HTTP/1.1
Content-Type: application/json

{
  "Data": [
    {
      "Name": "Certificate",
      "Type": "Raw",
      "Value": "-----BEGIN CERTIFICATE-----..."
    },
    {
      "Name": "Tags",
      "Type": "Raw",
      "Value": ["SGD_CERT_ISSUER", "SGD_CERT_SUBJECT"]
    }
  ]
}

响应返回指定证书字段，符合GM/T 0006标签规范。

三、安全设计精要

1. 状态码双重机制

完整错误码见标准附录B，如：

• 0x0E00000F：签名验证失败
• 0x0E000015：证书解析失败

2. 算法标识规范

四、实战示例：内部私钥签名

请求

POST /shf/v1/Sign HTTP/1.1
Content-Type: application/json

{
  "Data": [
    {"Name": "KeyId", "Type": "Raw", "Value": "9bcf0c91-f9f1-406d-ab69-d7bbc157cc06"},
    {"Name": "PlainText", "Type": "Raw", "Value": "Hello World"}
  ]
}

响应

{
  "Status": {"Code": "0", "Msg": "success"},
  "Data": [
    {
      "Name": "Signature",
      "Type": "Base64",
      "Value": "MEQCID0G9Qh91XfhqOfv4kXuIZvm45U+Y7BFbufFZDNJvJHZAiBgkdtAxzrB3J5nJD3wmiFOyVzudEt6cYl6ZLXE//4dSQ=="
    }
  ]
}

五、开发注意事项

1. 版本控制：自定义扩展接口需使用/shf/ext/前缀
2. 编码规范：
   • 默认UTF-8编码
   • 二进制数据必须使用Base64/Hex编码

结语

GM/T 0136-2024通过标准化HTTP接口，解决了三大核心问题：

1. 互操作性：不同厂商密码服务无缝对接
2. 开发效率：减少70%以上的集成成本