[密码学实战]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. 密码运算类接口

接口功能	请求路径	方法	核心参数示例
内部私钥签名	/shf/v1/Sign	POST	KeyId, PlainText
外部公钥加密	/shf/v1/EncryptByExternalPublicKey	POST	PublicKey, PlainText
对称密钥解密	/shf/v1/Decrypt	POST	KeyId, CipherText, IV

文件操作特殊处理：

• 使用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. 状态码双重机制

层级	示例	说明
HTTP状态码	401	身份认证失败
业务状态码	0x0E000005	请求参数错误（十六进制）

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

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

2. 算法标识规范

算法类型	标准标识示例
SM2签名	1.2.156.10197.1.501
SM4-CBC	SGD_SM4_CBC
SM3哈希	SGD_SM3

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

请求

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%以上的集成成本