T/HBCCIA 0002-2023 湖北省重要网络和信息系统密码应用接口规范

ICS35.040

L80

备案号：T/HBCCIA

湖北省商用密码协会团体标准

T/HBCCIA0002—2023

湖北省重要网络和信息系统

密码应用接口规范

Cryptographicapplicationinterfacespecificationforcritical

networksandinformationsystemsinHubeiProvince

2023-12-27发布2023-12-27实施

湖北省商用密码协会发布

T/HBCCIA0002—2023

目次

前  言III

引  言IV

1范围1

2规范性引用文件1

3术语和定义2

4缩略语2

5接口概述3

6密码应用接口规范3

6.1HTTP接口规范3

6.2C接口规范31

6.3JAVA接口规范43

6.4JavaScript接口规范53

6.5Objective-C接口规范60

附录A（资料性附录）湖北省重要网络和信息系统密码应用技术指南应用和数据安全接口调用示例73

A．1指南一接口调用示例73

A．2指南二接口调用示例74

A．3指南三接口调用示例76

A．4指南四接口调用示例79

A．5指南五接口调用示例80

A．6指南六接口调用示例81

A．7指南七接口调用示例82

A．8指南八接口调用示例84

A．9指南九接口调用示例84

附录B（规范性）HTTP接口响应状态码97

I

T/HBCCIA0002—2023

前  言

本文件按照GB/T1.1-2020《标准化工作导则第1部分:标准化文件的结构和起草规则》的规定起草。

请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。

本文件由湖北省商用密码协会提出并归口。

本文件起草单位：湖北省密码管理局、武汉信安珞珈科技有限公司、武汉大学、华中科技大学、武

汉思为同飞网络技术股份有限公司、湖北东方网盾信息安全技术有限公司。

本文件起草人：胡进、闵国华、陈辉、李涛、曾军林、何德彪、彭聪、徐鹏、王婧、梅松、钟骁、

李荣。

III

T/HBCCIA0002—2023

引  言

本文件是在《湖北省重要网络和信息系统密码应用技术指南》的基础上，依托于密码模块、密码设

备、密码系统、密码服务平台等典型密码服务层相关标准规范，向上为应用层规定了统一的密码应用接

口。

本文件密码应用接口将密码模块、密码设备、密码系统、密码服务平台等各类密码产品或标准或

非标的密码服务接口转换成统一的密码服务接口，通过统一的密码服务接口向上为应用系统提供各类密

码服务。

本文件旨在推动密码在重要信息系统的合规、正确、有效应用。本文件适用于重要信息系统规划、

建设、运行各个阶段，为重要信息系统的规划设计、建设实施和运行维护过程中合规、正确、有效的应

用密码技术，保障重要信息系统安全提供指导。

IV

T/HBCCIA0002—2023

湖北省重要网络和信息系统密码应用接口规范

1范围

本文件规定了密码模块、密码设备、密码系统、密码服务平台等密码产品到上层应用之间的接口。

本文件适用于密码产品多场景、多开发语言对外提供的密码服务，也适用于密码产品的开发和使用。

2规范性引用文件

下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅注日期的版本适用于本文件，

凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。

GM/Z4001密码术语

GB/T15852信息技术安全技术消息鉴别码

GB/T25069信息安全技术术语

GB/T37092信息安全技术密码模块安全要求

GB/T32918信息安全技术SM2椭圆曲线公钥密码算法

GB/T35276信息安全技术SM2密码算法使用规范

GB/T32905信息安全技术SM3密码杂凑算法

GB/T32907信息安全技术SM4分组密码算法

GB/T38636信息安全技术传输层密码协议(TLCP)

GB/T39786信息安全技术信息系统密码应用基本要求

GM/T0005随机性检测规范

GM/T0010SM2密码算法加密签名消息语法规范

GM/T0016智能密码钥匙密码应用接口规范

GM/T0018密码设备应用接口规范

GM/T0021动态口令密码应用技术规范

GM/T0024SSLVPN技术规范

GM/T0028密码模块安全技术要求

GM/T0033时间戳接口规范

GM/T0131电子签章应用接口规范

T/HBCCIA0001湖北省重要网络和信息系统密码应用技术指南

1

T/HBCCIA0002—2023

3术语和定义

GM/Z4001、GB/T25069—2022、GB/T39786-2021、GB/T15852.2-2012等界定的以及下列术语和

定义适用于本文件。

3.1

密码服务cipherservice

基于密码技术和产品,实现密码功能,提供密码保障的行为。

3.2

密码服务管理平台cryptographicservicemanagementplatform

具备密码服务管理功能、平台管理功能、资源调度功能的模块。

3.3

密码资源cryptographyresources

密码物理资源或虚拟资源的集合，提供各种基础密码能力供密码服务使用。

3.4

密码设备cryptographicdevice

为密钥等秘密信息提供安全存储，并基于这些秘密信息提供密码安全服务的设备。本文件中指服务

器密码机、云服务器密码机、签名验签服务器、时间戳服务器等。

3.5

密码服务平台cipherserviceplatform

一种提供密码功能服务和密码资源管理的系统，其组成包括密码服务管理平台和密码资源，可以为

用户提供集中的密码资源管理、密码服务管理、应用接入管理、平台管理功能，为业务系统提供密码功

能服务。

3.6

密码模块cryptographicmodule

实现了密码安全功能的硬件、软件和（或）固件的集合，并且被包含在密码边界内。

注：密码模块根据其组成，可分为硬件密码模块、固件密码模块、软件密码模块以及混合密码模块。

4缩略语

HTTP:超文本传输协议（HyperTextTransferProtocol）

API:应用程序接口，简称应用接口（ApplicationProgramInterface）

JSON:JS对象标记（JavaScriptObjectNotation）

URI:统一资源标志符（UniformResourceIdentifier）

2

T/HBCCIA0002—2023

RESTful:表现层状态转化原则（RepresentationalStateTransfer）

JavaScript：是一种具有函数优先的轻量级，解释型或即时编译型的编程语言

5接口概述

密码应用接口定位为接口转换层，将密码模块、密码设备、密码系统、密码服务平台等各类密码

产品或标准或非标的密码服务接口转换成统一的密码服务接口，通过统一的密码服务接口向上为应用系

统提供各类密码服务。

密码应用接口支持HTTP、C、JAVA、JavaScript、Objective-C形式密码应用接口。

密码应用接口在密码应用技术体系框架内的位置如图1所示：

图5-1密码应用接口框架

6密码应用接口规范

6.1HTTP接口规范

本文件采用RESTful形式提供，采用httppost方式调用，入参header中Content-Type内容

为application/json，请求参数和响应参数均为JSON格式，字符编码为utf-8，请求参数放入body

中。

接口响应状态码应符合附录B的规定，接口请求及响应相关样例见附录A。

6.1.1接口定义和安全要求

通讯协议

3

T/HBCCIA0002—2023

密码应用HTTP接口基于HTTP协议，宜采用TLCP/TLS等协议进行传输层安全保护。如使用TLCP，

应符合GB/T38636。

请求方法和URL规则

支持HTTPGET、POST方法。

1）使用GET方法时，无需添加请求参数，响应体为JSON格式，HTTP消息示例如下：

GET/cipher/signHTTP/1.1

2）使用POST方法时，请求体和响应体都采用JSON格式，HTTP消息示例如下：

POST/cipher/verifyHTTP/1.1

Content-Type:application/json

{

"signedText":"aGVsbG8gd29ybGQ=",

"keyLabel":"key02"

}

注：signedText为二进制数据，采用Base64编码

数据结构

.1请求数据结构

请求通过json进行数据的传递，可兼容和扩展现有系统及平台应用。请求结构定义可参考如下

示例：

{

"signedText":"aGVsbG8gd29ybGQ=",

"keyLabel":"key02"

}

注：signedText为二进制数据，采用Base64编码

.2响应数据结构

响应体内容包含状态码、状态描述和数据三部分，分别以code，msg和data定义。code中存储

状态码，msg中存在对状态码的描述，data中传递服务端响应数据。当没有数据需要响应时，data

字段应为空。响应结构定义可参考如下示例：

{

"code":"0",

4

T/HBCCIA0002—2023

"msg":"success",

"data":{

"p7data":"1234555"

}

}

注：p7data为二进制数据，采用Base64编码

接口认证

每次请求都应携带安全访问令牌。当前支持的授权类别为：

admin，数据管理权限安全访问令牌，用于导入外部私钥，私钥迁移等接口使用；

general，一般权限安全访问令牌，用于外部公钥加密，签名，消息编码等接口使用。

接口权限划分见6.1.2节。

若采用消息鉴别码应符合GB/T15852。

6.1.2接口列表

密码应用HTTP接口见下表：

接口功能请求路径方法权限备注

密码运算类

签名/crypto/sm2/signPOSTgeneral

验签名/crypto/sm2/verifyPOSTgeneral

制作不带签名的数字信封制作/c不r带yp签to名/p的k数cs字7/信e封nc接ry口ptPOSTgeneral

解不带签名的数字信封/crypto/pkcs7/decryptPOSTgeneral

制作带签名的数字信封/crypto/pkcs7/signed/encryptPOSTgeneral

解带签名的数字信封/crypto/pkcs7/signed/decryptPOSTgeneral

基于杂凑算法的消息鉴别/crypto/sm3/hmacPOSTgeneral

基于块密码的消息鉴别/crypto/sm4/cmacPOSTgeneral

消息杂凑/crypto/sm3/hashPOSTgeneral

产生随机数/crypto/gen/randomPOSTgeneral

对称密钥加密/crypto/sm4/encryptPOSTgeneral

对称密钥解密/crypto/sm4/decryptPOSTgeneral

非对称加密/crypto/sm2/encryptPOSTgeneral

密钥协商/crypto/key/agreementPOSTgeneral

5

T/HBCCIA0002—2023

获取二维码/crypto/gen/QRcodePOSTgeneral

二维码扫码结果查询/crypto/get/QRcodeResultPOSTgeneral

数字证书类

证书申请/cert/applyPOSTgeneral

证书更新/cert/updatePOSTgeneral

证书吊销/cert/revokePOSTgeneral

证书冻结/cert/freezePOSTgeneral

证书解冻/cert/unfreezePOSTgeneral

证书查询/cert/queryPOSTgeneral

短信令牌类

获取短信令牌信息/otp/getSmsCardInfoPOSTgeneral

获取短信令牌编码/otp/getNewSmsCardPOSTgeneral

绑定短信令牌/otp/smsCardBindPOSTgeneral

获取短信密码/otp/getSmsPwdPOSTgeneral

解绑短信令牌/otp/smsCardUnbindPOSTgeneral

冻结短信令牌/otp/lockSmsCardPOSTgeneral

解冻短信令牌/otp/unLockSmsCardPOSTgeneral

清除短信令牌失败次数/otp/smsClearErrorCounterPOSTgeneral

验证短信密码/otp/authSmsCardPOSTgeneral

时间戳类

获取时间戳/ts/getPOSTgeneral

验证时间戳（不包含签名证书）/ts/verifyPlainPOSTgeneral

验证时间戳（包含签名证书）/ts/verifyPlainWithCertPOSTgeneral

解析时间戳/ts/parseTokenPOSTgeneral

签章类

注册签章人/seal/registerUserPOSTgeneral

申请印章/seal/applySealPOSTgeneral

获取印章详情/seal/getSealInfoPOSTgeneral

获取印章文件/seal/getSealPOSTgeneral

6

T/HBCCIA0002—2023

更新印章图片/seal/updatePhotoDataPOSTgeneral

pdf盖章/seal/pdfStampPOSTgeneral

验证pdf盖章/seal/verifyPdfStampPOSTgeneral

协同签名类

生成服务端密钥对/cipher/genenrateKeyPOSTgeneral

服务端协同签名/cipher/getSignedValPOSTgeneral

数据统计类

获取密码应用详情数据/monitor/statPOSTgeneral

6.1.3密码运算类

签名

请求路径：/crypto/sm2/sign

调用方法：POST

功能描述：提供数据进行签名服务

参数类型说明

请求参数：plainTextString必须，原文，Base64编码

subjectString必须，用于签名的私钥对应的公钥证书的主题

issuerString必须，用于签名的私钥对应的公钥证书的颁发者

digestAlgString可选，摘要算法。

为空时，采用默认配置

响应参数：codeString必须，响应代码：0-代表成功，其他数字代码详见响

应码说明

msgString必须，响应信息

datasignedDataString可选，签名后的数据，Base64编码

验签名

请求路径：/crypto/sm2/verify

调用方法：POST

功能描述：提供数据验签名服务

参数类型说明

请求参数：plainTextString必须，原文，Base64编码

7

T/HBCCIA0002—2023

signedTextString必须，签名结果

certStringraw方式时必须，用于验签名的证书，Base64编码

digestAlgString可选，摘要算法。

为空时，采用默认配置

响应参数：codeString必须，响应代码：0-代表成功，其他数字代码详见响

应码说明

msgString必须，响应信息

datasignDnString必须，参与验签名证书所含的dn

制作不带签名的数字信封

请求路径：/crypto/pkcs7/encrypt

调用方法：POST

功能描述：提供数据制作不带签名的数字信封服务

参数类型说明

请求参数：plainTextString必须，原文，Base64编码

symmAlgString必须，用于对称加密的对称算法，支持：

SM4

certString必须，用于加密的证书，Base64编码

响应参数：codeString必须，响应代码：0-代表成功，其他数字代

码详见响应码说明

msgString必须，响应信息

datadigitalEnvelopeDataString必须，数字信封数据，Base64编码

解密不带签名的数字信封

请求路径：/crypto/pkcs7/decrypt

调用方法：POST

功能描述：提供数据解不带签名的数字信封服务

参数类型说明

请求参数：envelopedDataString必须，数字信封，Base64编码

响应参数：codeString必须，响应代码：0-代表成功，其他数字代码详见响

应码说明

msgString必须，响应信息

8

T/HBCCIA0002—2023

dataplaintTextString可选，解密后的原文

制作带签名的数字信封

请求路径：/crypto/pkcs7/signed/encrypt

调用方法：POST

功能描述：提供数据制作带签名的数字信封服务

参数类型说明

请求参数：plainTextString必须，原文。Base64编码

signSubjectString必须，用于签名的数字证书主题

encCertString必须，加密公钥证书，Base64编码

digestAlgString可选，摘要算法，支持：SM3

symmAlgString可选，用于对称加密的对称算法，支持：

SM4

响应参数：codeString必须，响应代码：0-代表成功，其他数字代

码详见响应码说明

msgString必须，响应信息

datadigitalEnvelopeDataString必须，数字信封数据，Base64编码

解密带签名的数字信封

请求路径：/crypto/pkcs7/signed/decrypt

调用方法：POST

功能描述：提供数据解带签名的数字信封服务

参数类型说明

请求参数：envelopedDataString必须，数字信封，Base64编码

响应参数：codeString必须，响应代码：0-代表成功，其他数字代码详见响

应码说明

msgString必须，响应信息

dataplaintTextString必须，解密后的原文

6.1.3.7基于杂凑算法的消息鉴别

请求路径：/crypto/sm3/hmac

调用方法：POST

功能描述：接入应用提供hmac运算服务

9

T/HBCCIA0002—2023

参数类型说明

请求参数：plainTextString必须，需要进行hmac运算的Base64编码

hmacAlgString必须，HmacSM3

keyIdString传入Hmac运算需要使用的密钥标签

响应参数：codeString必须，响应代码：0-代表成功，其他数字代码详见响

应码说明

msgString必须，响应信息

datahmacString可选，hmac运算之后的密文，Base64编码

基于块密码的消息鉴别

请求路径：/crypto/sm4/cmac

调用方法：POST

功能描述：提供CMAC运算服务

参数类型说明

请求参数：plainTextString必须，需要进行mac运算的Base64编码

macAlgString必须,SM4

keyIdString传入cmac运算需要使用的密钥标签

响应参数：codeString必须，响应代码：0-代表成功，其他数字代码详见响

应码说明

msgString必须，响应信息

datamacString可选，mac值，Base64编码

消息杂凑

请求路径：/crypto/sm3/hash

调用方法：POST

功能描述：提供摘要运算服务

参数类型说明

请求参数：plainTextString必须，需要进行杂凑运算的原文

digestAlgString必须,SM3

响应参数：codeString必须，响应代码：0-代表成功，其他数字代码详见响

应码说明

10

T/HBCCIA0002—2023

msgString必须，响应信息

datadigestString可选，摘要值，Base64编码

0产生随机数

请求路径：/crypto/gen/random

调用方法：POST

功能描述：生成随机数

参数类型说明

请求参数：lengthString必须，随机数字节数为:1-16000

isKeyAgreementString是否密钥协商。0：否，1：是

clientRandomString客户端随机数，密钥协商时必须

响应参数：codeString必须，响应代码：0-代表成功，其他数字代

码详见响应码说明

msgString必须，响应信息

datarandomString必须，成功返回生成的随机数，Base64编码

serverPubkeyString服务器公钥，密钥协商时必须，Base64编码

serverSignResultString服务器签名值，密钥协商时必须，Base64编

码

1密钥协商

请求路径：/crypto/key/agreement

调用方法：POST

功能描述：产生协商参数并计算会话密钥

参数类型说明

请求参数：sponsorIDString必须，发起方的ID。不大于32字节。

sponsorPubKeyString发起方的公钥，Base64编码。

sponsorTempPubKeString发起方的临时公钥，Base64编码。

y

响应参数：codeString必须，响应代码：0-代表成功，其他数字代码详见响

应码说明

11

T/HBCCIA0002—2023

msgString必须，响应信息

dataIDString响应方的ID。不大于32字节。

pubKeyS