[密码学实战]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=="}]
}