[密碼學實戰]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%以上的集成成本