ICS35.030 CCSL80 中华人民共和国密码行业标准 GM/T0136—2024 密码应用HTTP接口规范 HTTPinterfacespecificationforcryptographicapplication 2024-12-27发布 2025-07-01实施 国家密码管理局发布目 次 前言 Ⅲ ………………………………………………………………………………………………………… 引言 Ⅳ ………………………………………………………………………………………………………… 1 范围 1 ……………………………………………………………………………………………………… 2 规范性引用文件 1 ………………………………………………………………………………………… 3 术语和定义 1 ……………………………………………………………………………………………… 4 缩略语 1 …………………………………………………………………………………………………… 5 接口通则 2 ………………………………………………………………………………………………… 5.1 密码应用HTTP接口在公钥密码应用技术体系框架中的位置 2 ………………………………… 5.2 功能说明 2 …………………………………………………………………………………………… 6 接口定义 2 ………………………………………………………………………………………………… 6.1 通信协议 2 …………………………………………………………………………………………… 6.2 URL规则和请求方法 2 ……………………………………………………………………………… 6.3 数据结构 3 …………………………………………………………………………………………… 7 接口描述 4 ………………………………………………………………………………………………… 7.1 接口列表 4 …………………………………………………………………………………………… 7.2 密码运算类接口 5 …………………………………………………………………………………… 7.3 证书解析类接口 11 …………………………………………………………………………………… 附录A(规范性) NTV结构 13 …………………………………………………………………………… A.1 概述 13 ……………………………………………………………………………………………… A.2 参数名称 13 ………………………………………………………………………………………… A.3 参数类型 13 ………………………………………………………………………………………… A.4 参数值 13 …………………………………………………………………………………………… 附录B(规范性) 状态代码 15 ……………………………………………………………………………… 附录C(资料性) 接口样例 17 ……………………………………………………………………………… C.1 密码运算类接口样例 17 ……………………………………………………………………………… C.2 证书解析类接口 29 …………………………………………………………………………………… 参考文献 32 …………………………………………………………………………………………………… ⅠGM/T0136—2024前 言 本文件按照GB/T1.1—2020《标准化工作导则 第1部分:标准化文件的结构和起草规则》的规定 起草。 请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。 本文件由密码行业标准化技术委员会提出并归口。 本文件起草单位:北京信安世纪科技股份有限公司、格尔软件股份有限公司、北京国脉信安科技有 限公司、北京数字认证股份有限公司、中电科网络安全科技股份有限公司、浙江理工大学、武汉大学、 北京格尔国信科技有限公司。 本文件主要起草人:焦靖伟、汪宗斌、郑强、袁峰、黄福飞、李虹霖、王银平、赵永省、罗俊、沈剑、胡进、 罗敏、朱立通。 ⅢGM/T0136—2024引 言 密码应用接口以HTTP形式对外提供,可以显著提升开发和使用的便利性。HTTP接口简化了 开发流程,开发者可以通过标准的HTTP请求直接与密码服务交互,降低编码复杂性。由于HTTP协 议的广泛支持,接口实现了跨平台访问,能够在各种设备上灵活使用。HTTP接口与多种编程语言和 框架兼容,为开发者提供了灵活的工具选择。 密码应用HTTP接口在公钥密码基础设施支撑的前提下,向应用及系统提供各类通用的基础密码 运算服务,有利于密码服务接口产品的开发,有利于应用系统在密码服务过程中的集成和实施,有利于 各应用系统的互联互通。 ⅣGM/T0136—2024密码应用HTTP接口规范 1 范围 本文件规定了通用密码应用支撑层密码应用对外HTTPRESTful接口定义、数据结构和接口 描述。 本文件适用于多场景下密码应用对外提供HTTP服务,也适用于基础密码应用的开发和使用。 2 规范性引用文件 下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中,注日期的引用文 件,仅该日期对应的版本适用于本文件;不注日期的引用文件,其最新版本(包括所有的修改单)适用于 本文件。 GB/T7408.1—2023 日期和时间 信息交换表示法 第1部分:基本原则 GB/T17964—2021 信息安全技术 分组密码算法的工作模式 GB/T25069—2022 信息安全技术 术语 GB/T38636—2020 信息安全技术 传输层密码协议(TLCP) GB/T41389—2022 信息安全技术 SM9密码算法使用规范 GM/T0006—2023 密码应用标识规范 GM/T0009—2023 SM2密码算法使用规范 GM/T0094—2020 公钥密码应用技术体系框架规范 GM/Z4001—2013 密码术语 3 术语和定义 GB/T25069和GM/Z4001界定的以及下列术语和定义适用于本文件。 3.1 密码应用 cryptographicapplication 信息系统中利用密码技术提供数据安全保护的应用程序或服务。 注:对外可提供基础密码运算接口,涵盖消息摘要、加解密、签名验签和证书解析等,确保信息的机密性、完整性、真 实性和不可否认性。 4 缩略语 下列缩略语适用于本文件。 API:应用程序接口,简称应用接口(ApplicationProgramInterface) HTTP:超文本传输协议(HypertextTransferProtocol) JSON:JS对象标记(JavaScriptObjectNotation) NTV:名称类型值数据(Name-Type-ValueData) RESTful:表现层状态转化原则(RepresentationalStateTransfer) 1GM/T0136—2024TLCP:传输层密码协议(TransportLayerCryptographyProtocol) URL:统一资源定位符(UniformResourceLocator) 5 接口通则 5.1 密码应用HTTP接口在公钥密码应用技术体系框架中的位置 公钥密码应用技术体系框架由应用层、典型密码应用支撑层、通用密码应用支撑层、基础设施安全 支撑平台、密码设备服务层组成。密码应用HTTP接口属于通用密码应用支撑层中通用密码服务,向 典型密码服务层和应用层提供证书解析、信息的机密性、完整性和不可否认性基础密码服务,将上层应 用的密码服务请求转化为具体的基础密码操作请求,通过统一的密码设备应用接口调用相应的密码设 备实现具体的密码运算,通用密码服务在公钥密码应用技术框架内的位置应遵循GM/T0094—2020 的第4章。 5.2 功能说明 密码应用支撑层密码应用通过HTTP接口,将外部应用的密码服务请求转化为具体的基础密码操 作请求,通过统一的密码设备应用接口调用相应的密码设备实现具体的密码运算。 密码应用HTTP接口适用于各类密码产品对外提供HTTP形式的密码服务接口,涵盖签名验签、 加解密、消息杂凑、消息鉴别和证书解析等基础密码服务功能。 接口遵循RESTful架构风格,基于HTTP协议,请求和响应数据采用JSON格式,使用多个NTV 结构进行参数传递。 密码应用在设计时应确保接口遵循RESTful原则,具体包括: a) 独立的资源标识:每个具体的服务接口都应视为独立的资源,并通过特定的URL路径进行 标识; b) 接口的统一性:使用标准的HTTP方法(GET、POST等)对资源进行操作,不同的操作对应不 同的方法,保证接口的一致性和规范性; c) 接口的无状态性:服务器不保存客户端的上下文信息,每次请求都应包含完整的信息,使得密 码应用服务提供方能够独立处理每个请求; d) 统一的资源表示:采用JSON格式作为请求和响应数据的格式,通过多个NTV结构进行参数 传递,确保数据的结构化和可读性,方便不同系统之间的数据交互和解析。 6 接口定义 6.1 通信协议 密码应用HTTP接口基于HTTP协议,为保证传输安全性,应采用TLCP等协议进行传输层安全 保护。如使用TLCP,应符合GB/T38636。 6.2 URL规则和请求方法 所有请求的URL路径应以“/shf/v1/”为前缀,后跟具体的资源路径。shf表示密码应用HTTP接 口,当前版本为v1。随着本文件的修订,版本号也应相应增加。除本文件约定的接口外,自定义扩展接