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

湖北省商用密码协会团体标准2023-12-27发布IT/HBCCIA0002—2023 2规范性引用文件 3术语和定义 4缩略语 5接口概述 6密码应用接口规范 6.1HTTP接口规范 36.2C接口规范 316.3JAVA接口规范 436.4JavaScript接口规范 536.5Objective-C接口规范 60附录A（资料性附录）湖北省重要网络和信息系统密码应用技术指南应用和数据安全接口调用示例 73A．1指南一接口调用示例 A．2指南二接口调用示例 A．3指南三接口调用示例 A．4指南四接口调用示例 A．5指南五接口调用示例 80A．6指南六接口调用示例 81A．7指南七接口调用示例 82A．8指南八接口调用示例 84A．9指南九接口调用示例 84附录B（规范性）HTTP接口响应状态码 T/HBCCIA0002—2023T/HBCCIA0002—2023本文件按照GB/T1.1-2020《标准化工作导则第1部分:标准化文件的结构和起草规则》的规定起草。请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。本文件由湖北省商用密码协会提出并归口。本文件起草单位：湖北省密码管理局、武汉信安珞珈科技有限公司、武汉大学、华中科技大学、武汉思为同飞网络技术股份有限公司、湖北东方网盾信息安全技术有限公司。本文件起草人：胡进、闵国华、陈辉、李涛、曾军林、何德彪、彭聪、徐鹏、王婧、梅松、钟骁、李荣。T/HBCCIA0002—2023本文件是在《湖北省重要网络和信息系统密码应用技术指南》的基础上，依托于密码模块、密码设备、密码系统、密码服务平台等典型密码服务层相关标准规范，向上为应用层规定了统一的密码应用接本文件密码应用接口将密码模块、密码设备、密码系统、密码服务平台等各类密码产品或标准或非标的密码服务接口转换成统一的密码服务接口，通过统一的密码服务接口向上为应用系统提供各类密码服务。本文件旨在推动密码在重要信息系统的合规、正确、有效应用。本文件适用于重要信息系统规划、建设、运行各个阶段，为重要信息系统的规划设计、建设实施和运行维护过程中合规、正确、有效的应用密码技术，保障重要信息系统安全提供指导。1T/HBCCIA0002—2023湖北省重要网络和信息系统密码应用接口规范本文件规定了密码模块、密码设备、密码系统、密码服务平台等密码产品到上层应用之间的接口。本文件适用于密码产品多场景、多开发语言对外提供的密码服务，也适用于密码产品的开发和使用。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湖北省重要网络和信息系统密码应用技术指南2T/HBCCIA0002—20233术语和定义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）3T/HBCCIA0002—2023RESTful:表现层状态转化原则（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接口定义和安全要求通讯协议4T/HBCCIA0002—2023密码应用HTTP接口基于HTTP协议，宜采用TLCP/TLS等协议进行传输层安全保护。如使用TLCP，应符合GB/T38636。请求方法和URL规则支持HTTPGET、POST方法。1）使用GET方法时，无需添加请求参数，响应体为JSON格式，HTTP消息示例如下：GET/cipher/signHTTP/1.12）使用POST方法时，请求体和响应体都采用JSON格式，HTTP消息示例如下：POST/cipher/verifyHTTP/1.1Content-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",T/HBCCIA0002—2023"msg":"success","p7data":"1234555"注：p7data为二进制数据，采用Base64编码接口认证每次请求都应携带安全访问令牌。当前支持的授权类别为：ladmin，数据管理权限安全访问令牌，用于导入外部私钥，私钥迁移等接口使用；lgeneral，一般权限安全访问令牌，用于外部公钥加密，签名，消息编码等接口使用。接口权限划分见6.1.2节。若采用消息鉴别码应符合GB/T15852。6.1.2接口列表密码应用HTTP接口见下表：/crypto/sm2/sign/crypto/sm2/verify/crypto/pkcs7/encrypt/crypto/pkcs7/decrypt/crypto/pkcs7/signed/encrypt/crypto/pkcs7/signed/decrypt/crypto/sm3/hmac/crypto/sm4/cmac/crypto/sm3/hash/crypto/gen/random/crypto/sm4/encrypt/crypto/sm4/decrypt/crypto/sm2/encrypt/crypto/key/agreements6T/HBCCIA0002—2023/crypto/gen/QRcode/crypto/get/QRcodeResult/cert/apply/cert/update/cert/revoke/cert/freeze/cert/unfreeze/cert/query/otp/getSmsCardInfo/otp/getNewSmsCard/otp/smsCardBind/otp/getSmsPwd/otp/smsCardUnbind/otp/lockSmsCard/otp/unLockSmsCard/otp/smsClearErrorCounter/otp/authSmsCard/ts/get/ts/verifyPlain/ts/verifyPlainWithCert/ts/parseToken/seal/registerUser/seal/applySeal/seal/getSealInfo/seal/getSealT/HBCCIA0002—2023/seal/updatePhotoData/seal/pdfStamp/seal/verifyPdfStamp/cipher/genenrateKey/cipher/getSignedVal/monitor/stat6.1.3密码运算类签名请求路径：/crypto/sm2/sign调用方法：POST功能描述：提供数据进行签名服务参数类型说明请求参数：plainTextString必须，原文，Base64编码subjectString必须，用于签名的私钥对应的公钥证书的主题issuerString必须，用于签名的私钥对应的公钥证书的颁发者digestAlgString可选，摘要算法。为空时，采用默认配置响应参数：codeString必须，响应代码：0-代表成功，其他数字代码详见响应码说明msgString必须，响应信息datasignedDataString可选，签名后的数据，Base64编码验签名请求路径：/crypto/sm2/verify调用方法：POST功能描述：提供数据验签名服务参数类型说明请求参数：plainTextString必须，原文，Base64编码8T/HBCCIA0002—2023signedTextString必须，签名结果certStringraw方式时必须，用于验签名的证书，Base64编码digestAlgString可选，摘要算法。为空时，采用默认配置响应参数：codeString必须，响应代码：0-代表成功，其他数字代码详见响应码说明msgString必须，响应信息datasignDnString必须，参与验签名证书所含的dn制作不带签名的数字信封请求路径：/crypto/pkcs7/encrypt调用方法：POST功能描述：提供数据制作不带签名的数字信封服务参数类型说明请求参数：plainTextString必须，原文，Base64编码symmAlgString必须，用于对称加密的对称算法，支持：SM4certString必须，用于加密的证书，Base64编码响应参数：codeString必须，响应代码：0-代表成功，其他数字代码详见响应码说明msgString必须，响应信息datadigitalEnvelopeDataString必须，数字信封数据，Base64编码解密不带签名的数字信封请求路径：/crypto/pkcs7/decrypt调用方法：POST功能描述：提供数据解不带签名的数字信封服务参数类型说明请求参数：envelopedDataString必须，数字信封，Base64编码响应参数：codeString必须，响应代码：0-代表成功，其他数字代码详见响应码说明msgString必须，响应信息T/HBCCIA0002—2023dataplaintTextString可选，解密后的原文制作带签名的数字信封请求路径：/crypto/pkcs7/signed/encrypt调用方法：POST功能描述：提供数据制作带签名的数字信封服务参数类型说明请求参数：plainTextString必须，原文。Base64编码signSubjectString必须，用于签名的数字证书主题encCertString必须，加密公钥证书，Base64编码digestAlgString可选，摘要算法，支持：SM3symmAlgString可选，用于对称加密的对称算法，支持：SM4响应参数：codeString必须，响应代码：0-代表成功，其他数字代码详见响应码说明msgString必须，响应信息datadigitalEnvelopeDataString必须，数字信封数据，Base64编码解密带签名的数字信封请求路径：/crypto/pkcs7/signed/decrypt调用方法：POST功能描述：提供数据解带签名的数字信封服务参数类型说明请求参数：envelopedDataString必须，数字信封，Base64编码响应参数：codeString必须，响应代码：0-代表成功，其他数字代码详见响应码说明msgString必须，响应信息dataplaintTextString必须，解密后的原文基于杂凑算法的消息鉴别请求路径：/crypto/sm3/hmac调用方法：POST功能描述：接入应用提供hmac运算服务T/HBCCIA0002—2023参数类型说明请求参数：plainTextString必须，需要进行hmac运算的Base64编码hmacAlgString必须，HmacSM3String传入Hmac运算需要使用的密钥标签响应参数：codeString必须，响应代码：0-代表成功，其他数字代码详见响应码说明msgString必须，响应信息datahmacString可选，hmac运算之后的密文，Base64编码基于块密码的消息鉴别请求路径：/crypto/sm4/cmac调用方法：POST功能描述：提供CMAC运算服务参数类型说明请求参数：plainTextString必须，需要进行mac运算的Base64编码macAlgString必须,SM4String传入cmac运算需要使用的密钥标签响应参数：codeString必须，响应代码：0-代表成功，其他数字代码详见响应码说明msgString必须，响应信息datamacString可选，mac值，Base64编码消息杂凑请求路径：/crypto/sm3/hash调用方法：POST功能描述：提供摘要运算服务参数类型说明请求参数：plainTextString必须，需要进行杂凑运算的原文digestAlgString必须,SM3响应参数：codeString必须，响应代码：0-代表成功，其他数字代码详见响应码说明T/HBCCIA0002—2023msgString必须，响应信息datadigestString可选，摘要值，Base64编码0产生随机数请求路径：/crypto/gen/random调用方法：POST功能描述：生成随机数参数类型说明请求参数：lengthString必须，随机数字节数为:1-16000isKeyAgreementString是否密钥协商。0：否，1：是clientRandomString客户端随机数，密钥协商时必须响应参数：codeString必须，响应代码：0-代表成功，其他数字代码详见响应码说明msgString必须，响应信息datarandomString必须，成功返回生成的随机数，Base64编码serverPubkeyString服务器公钥，密钥协商时必须，Base64编码serverSignResultString服务器签名值，密钥协商时必须，Base64编码1密钥协商请求路径：/crypto/key/agreement调用方法：POST功能描述：产生协商参数并计算会话密钥参数类型说明请求参数：sponsorIDString必须，发起方的ID。不大于32字节。sponsorPubKeyString发起方的公钥，Base64编码。sponsorTempPubKeyString发起方的临时公钥，Base64编码。响应参数：codeString必须，响应代码：0-代表成功，其他数字代码详见响应码说明T/HBCCIA0002—2023msgString必须，响应信息dataString响应方的ID。不大于32字节。pubKeyString响应方的公钥，Base64编码。tempPubKeyString响应方的临时公钥，Base64编码。2对称密钥加密请求路径：/crypto/sm4/encrypt/调用方法：POST功能描述：提供采用内部密钥进行对称加密的服务参数类型说明请求参数：plainTextString必须，原文.Base64编码String必须，对称密钥的标识String必须，初始向量，如果填充模式包含CBC，则iv值必填。当keyId对应密钥为SM4密钥时，iv为Base64编码后字符串，解码后为16字节modeAndPaddingString填充和模式，支持/ECB/PKCS7Padding,/CBC/PKCS7Padding,/ECB/PKCS5Padding,/CBC/PKCS5Padding响应参数：codeString必须，响应代码：0-代表成功，其他数字代码详见响应码说明msgString必须，响应信息dataencrypedDataString必须，对称加密后的数据，使用Base64编码3对称密钥解密请求路径：/crypto/sm4/decrypt调用方法：POST功能描述：提供使用内部密钥进行对称解密的服务参数类型说明请求参数：encryptedDataString必须，加密以后的密文，Base64编码String必须，对称密钥的标识String可选，初始向量，如果填充模式包含CBC，则iv值必填。当keyId对应密钥为SM4密钥时，iv为Base64字符串，解码后为16字节T/HBCCIA0002—2023modeAndPaddingString必须，填充和模式，支持/ECB/PKCS7Padding,/CBC/PKCS7Padding,/ECB/PKCS5Padding,/CBC/PKCS5PaddingcodeString必须，响应代码：0-代表成功，其他数字代码详见响应码说明msgString必须，响应信息dataplainTextString必须，加密前的原文，使用Base64编码4非对称加密请求路径：/crypto/sm2/encrypt调用方法：POST功能描述：提供数据非对称加密接口参数类型说明请求参数：plainTextString必须，原文，Base64编码subjectString可选，加密证书DN，与pubKey二选一pubKeyString可选，公钥Base64信息，与subject二选一modeAndPaddingString可选，使用SM2算法时可不填，支持/ECB/PKCS1Padding,/ECB/NoPadding响应参codeString必须，响应代码：0-代表成功，其他数字代码详见响应码说明msgString必须，响应信息dataEncryptedDataString非对称加密后的结果，使用Base64编码5获取二维码请求路径：/crypto/gen/QRcode调用方法：POST功能描述：提供二维码生成功能参数类型说明请求参数：randomString待生成二维码的数据响应参codeString必须，响应代码：0-代表成功，其他数字代码详见响应码说明T/HBCCIA0002—2023msgString必须，响应信息dataqrcodeImageString二维码图片，Base64编码6二维码扫码结果查询请求路径：/crypto/get/QRcodeResult调用方法：POST功能描述：提供二维码扫码是否完成结果查询参数类型说明请求参数：randomString二维码唯一标识响应参codeString必须，响应代码：0-代表成功，其他数字代码详见响应码说明msgString必须，响应信息datalogintimeString二维码验证完成时间6.1.4数字证书类证书申请请求路径：/cert/apply调用方法：POST功能描述：申请证书参数类型说明请求参数：validDaysString可选，证书有效期(天）为空时，取系统默认值365天注意：如果系统默认值超出根证有效期，将会申请失败。不使用该参数时请注意默认值是否超出根证有效期。p10String必填，证书请求P10，P10需要去掉头尾和换行符响应参数：codeString返回结果代码msgString返回结果说明datap7dataString证书内容。Base64编码证书更新请求路径：/cert/update调用方法：POSTT/HBCCIA0002—2023功能描述：更新证书参数类型说明请求参数：String可选，证书序列号，与证书DN值同时存在时，与subjectDn以且的关系存在subjectDnString可选，证书DN值如果输入，则必须包含CN项，CN项不超过47个字符，整个DN不超过100个字符validDaysString可选，证书有效期(天）为空时，取系统默认值365天注意：如果系统默认值超出根证有效期，将会申请失败。不使用该参数时请注意默认值是否超出根证有效期。p10String必填，证书请求P10，P10需要去掉头尾和换行符响应参数：codeString返回结果代码msgString返回结果说明datap7dataString证书内容，Base64编码证书吊销请求路径：/cert/revoke调用方法：POST功能描述：吊销证书参数类型说明请求参数：subjectDnString可选，证书DN值，与sn不可同时为空。1）待下载证书吊销时，只能使用subjectDn2）同一subjectDn若有多张证书存在（不同状态），吊销时不可只传subjectdn3）subjectdn与sn同时存在时，以sn为准reasonString必填，作废原因，数字形式0：未知原因1：密钥泄露3：关系改变。证书的从属关系发送改变4：已被取代。证书已经被新的证书取代9：权限被回收。String可选，证书SN值，与subjectdn与sn同时存在时，以sn为准响应参数：codeString返回结果代码T/HBCCIA0002—2023msgString返回结果说明证书冻结请求路径：/cert/freeze调用方法：POST功能描述：冻结证书参数类型说明请求参数：subjectDnString可选，证书DN值，两个值同时提供的话，以sn为准String可选，证书序列号，与subjectDn不可同时为空，subjectdn与sn同时存在时，以sn为准响应参数：codeString返回结果代码msgString返回结果说明证书解冻请求路径：/cert/unfreeze调用方法：POST功能描述：解冻证书参数类型说明请求参数：subjectDnString可选，证书DN值，两个值同时提供的话，以sn为准String可选，证书序列号，与subjectDn不可同时为空，subjectdn与sn同时存在时，以sn为准响应参数：codeString返回结果代码msgString返回结果说明证书查询请求路径：/cert/query调用方法：POST功能描述：查询证书参数类型说明请求参数：String可选，证书序列号，与T/HBCCIA0002—2023证书DN值同时存在时，与subjectDn以且的关系存在subjectDnString可选，证书DN值，不可与sn同时为空。pageNumString可选，查询的页码-如果不设置的话，将取服务端默认值1。本参数方便分页查询，pageNum为结果集的第X页。pageSizeString必填，查询的每页的记录条数-如果不设置的话，将取服务端默认值10。本参数方便分页查询，pageSize为一页有多少条响应参数：codeString返回结果代码msgString返回结果说明datacertinfosubjectDnString证书主题templateString证书模板名String证书序列号notafterString证书部分失效时间notbeforeString证书部分生效时间certstatusString证书状态1：未下载2：正常3：冻结4：作废expiredString是否过期totalNumString响应信息，总条数totalPageString响应信息，总页数6.1.5短信令牌类获取短信令牌信息请求路径：/otp/getSmsCardInfo调用方法：POSTT/HBCCIA0002—2023功能描述：获取短信令牌详情参数类型说明请求参数：cardSNString令牌号(若令牌号不为空则按照令牌号获取)userIDString手机短信用户编号(令牌号为空则按照用户编号+用户组获取)groupIDString用户组编号(令牌号为空则按照用户编号+用户组解除获取)响应参数：codeString返回结果代码msgString返回结果说明datacardSNString返回的短信卡编号typeModeString卡类型firstUseDateString第一次使用时间lastUseDateString最近一次使用时间statuDescString卡状态revokeTimeString作废时间notBeforeDateString生效时间notAfterDateString到期时间usedTimesString已使用次数leaveTimesString剩余使用次数planRevokedString是否约定作废planRevokeTimeString约定作废时间pwdValidityString密码有效期counterString密码序列verifyCodeString验证码colcountStringT/HBCCIA0002—2023rowcountStringcolTitleString行标题rowTitleString列标题dayFaildTimesString当日失败次数failedTimesString累计失败次数dayFaildLimitString日失败次数上限totalFaildLimitString累计失败次数上限dayGetChallengeTimesString当日获取挑战数次数totalGetChallengeTimesString累计获取挑战数次数dayGetChallengeLimitString日获取挑战数次数上限totalGetChallengeLimitString累计获取挑战数次数上限generateDateString口令卡生成时间remarkString备注获取短信令牌编码请求路径：/otp/getNewSmsCard调用方法：POST功能描述：获取短信卡编码参数类型说明请求参数：cardTypeString应用终端类型编号（需配置为手机短信）响应参数：codeString返回结果代码msgString返回结果说明datacardSNString返回的短信卡编号绑定短信令牌T/HBCCIA0002—2023请求路径：/otp/smsCardBind调用方法：POST功能描述：参数类型说明请求参数：userIDString手机短信用户编号groupIDString用户组编号cardSNString手机卡编号（调用获取短信令牌编码获取）staticPwdString本地静态密码，可为空phoneNumberString手机号，可为空emailString邮箱，可为空响应参数：codeString返回结果代码msgString返回结果说明获取短信密码请求路径：/otp/getSmsPwd调用方法：POST功能描述：获取短信密码参数类型说明请求参数：cardTypeString获取方式,1:按令牌号获取，2：按用户+用户组获取cardSNString令牌号(获取方式为1时必填)userIDString手机短信用户编号(获取方式为2时必填)groupIDString用户组编号(获取方式为2时必填)policyIDString策略编号phoneNumString手机号，可为空emailString邮箱，可为空响应参数：codeString返回结果代码msgString返回结果说明datapasswordStringNetpass返回的短信密码T/HBCCIA0002—2023解绑短信令牌请求路径：/otp/smsCardUnbind调用方法：POST功能描述：解除短信令牌绑定参数类型说明请求参数：cardSNString令牌号(若令牌号不为空则按照令牌号解除绑定)userIDString手机短信用户编号(令牌号为空则按照用户编号+用户组解除绑定)groupIDString用户组编号(令牌号为空则按照用户编号+用户组解除绑定)响应参数：codeString返回结果代码msgString返回结果说明冻结短信令牌请求路径：/otp/lockSmsCard调用方法：POST功能描述：冻结短信令牌参数类型说明请求参数：cardSNString令牌号(若令牌号不为空则按照令牌号冻结)userIDString手机短信用户编号(令牌号为空则按照用户编号+用户组冻结)groupIDString用户组编号(令牌号为空则按照用户编号+用户组冻结)lockTimeString冻结时间（单位为分钟，为空或0表示永久冻结）响应参数：codeString返回结果代码msgString返回结果说明解冻短信令牌请求路径：/otp/unLockSmsCard调用方法：POSTT/HBCCIA0002—2023功能描述：短信令牌解冻参数类型说明请求参数：cardSNString令牌号(若令牌号不为空则按照令牌号解冻)userIDString手机短信用户编号(令牌号为空则按照用户编号+用户组解冻)groupIDString用户组编号(令牌号为空则按照用户编号+用户组解冻)响应参数：codeString返回结果代码msgString返回结果说明清除短信令牌失败次数请求路径：/otp/smsClearErrorCounter调用方法：POST功能描述：清除短信令牌失败次数参数类型说明请求参数：cardSNString令牌号(若令牌号不为空则按照令牌号清除)userIDString手机短信用户编号(令牌号为空则按照用户编号+用户组清除)groupIDString用户组编号(令牌号为空则按照用户编号+用户组清除)响应参数：codeString返回结果代码msgString返回结果说明验证短信密码请求路径：/otp/authSmsCard调用方法：POST功能描述：验证短信密码参数类型说明请求参数：cardSNString令牌号(若令牌号不为空则按照令牌号验证)userIDString手机短信用户编号(令牌号为空则按照用户编号+用户组验证)groupIDString用户组编号(令牌号为空则按照用户编号+用户组验证)T/HBCCIA0002—2023passwordString短息密码policyIDString策略编号，可为空响应参数：codeString返回结果代码msgString返回结果说明dataauthResultStringNetpass返回的校验结果6.1.6时间戳类获取时间戳请求路径：/ts/get调用方法：POST功能描述：获取时间戳参数类型说明请求参数：plainString必填，原文数据，长度不超过1024字节响应参数：codeString返回结果代码msgString返回结果说明dataObject成功时有返回，Base64编码的签名值验证时间戳（不包含签名证书）请求路径：/ts/verifyPlain调用方法：POST功能描述：验证时间戳参数类型说明请求参数：plainString必填，原文数据，长度不超过1024字节tokenBase64String必填，Base64编码的签名值signerCertBase64String必填，签名者公钥证书响应参数：codeString返回结果代码msgString返回结果说明dataObject成功时有返回，签名信息结构为{"signAlg":"SM2","time":"2019-10-2403:02:29"}T/HBCCIA0002—2023验证时间戳（包含签名证书）请求路径：/ts/verifyPlainWithCert调用方法：POST功能描述：验证时间戳参数类型说明请求参数：plainString必填，原文数据，长度不超过1024字节tokenBase64String必填，Base64编码的签名值响应参数：codeString返回结果代码msgString返回结果说明dataObject成功时有返回，签名信息结构为{"signAlg":"SM2","time":"2019-10-2403:02:29"}解析时间戳请求路径：/ts/parseToken调用方法：POST功能描述：解析时间戳参数类型说明请求参数：tokenBase64String必填，Base64编码的签名值响应参数：codeString返回结果代码msgString返回结果说明dataserialNumString序列号digestAlgString摘要算法signAlgString签名算法createTimeString产生时间certificatesString证书链sinerCertObject签名证书6.1.7签章类注册签章人2sT/HBCCIA0002—2023请求路径：/seal/registerUser调用方法：POST功能描述：注册签章人参数类型说明请求参数：nameString必填，签章人名称（字母数字下划线，长度不能超过50字符）deptIdString必填，机构标识（需要在NetSeal管理端提前创建）certDataB64String必填，经过Base64编码的证书文件emailString可选，签章人邮箱phoneString可选，签章人电话响应参数：codeString返回结果代码msgString返回结果说明申请印章请求路径：/seal/applySeal调用方法：POST功能描述：申请印章参数类型说明请求参数：sealNameString必填，签章名称certSnString必填，签章人证书SN（需先注册签章人并上传证sealTypeString必填，印章类型，1：单位章，2：个人章，3：手写章transparencyString必填，透明度，0=原图，数值越大越透明usedLimitString必填，最大使用次数，0=无限制，范围0-1000dpiString必填，印模分辨率，默认为96photoDataB64String必填，经过Base64编码的图片数据,最大20KB，格式一般为.png响应参数：codeString返回结果代码msgString返回结果说明获取印章详情请求路径：/seal/getSealInfoT/HBCCIA0002—2023调用方法：POST功能描述：获取印章详情参数类型说明请求参数：certSnString必填，签章人证书SN响应参数：codeString返回结果代码msgString返回结果说明dataString印章idnameString印章名称notBeforeString签章人证书有效开始时间notAfterString签章人证书有效截止时间获取印章文件请求路径：/seal/getSeal调用方法：POST功能描述：获取印章文件参数类型说明请求参数：sealIdString必填，签章序号，调用获取印章详情接响应参数：codeString返回结果代码msgString返回结果说明datasealDataB64String经过Base64编码的签章数据更新印章图片请求路径：/seal/updatePhotoData调用方法：POST功能描述：更新印章图片参数类型说明请求参数：sealIdString必填，签章序号，调用获取印章详情接photoDataB64String必填，经过Base64编码的图片数据,最大20KB，格式一般为.png响应参数：codeString返回结果代码msgString返回结果说明T/HBCCIA0002—2023pdf盖章盖章方式一：关键字盖章请求路径：/seal/pdfStamp调用方法：POST功能描述：pdf盖关键字盖章参数类型说明请求参数：sealIdString必填，印章Id（调用获取印章详情接口获取）plainDataB64String必填，经过Base64编码的PDF文件serverCertSnString可选，服务器签名证书序号photoDataB64String可选，手写章图片,经Base64编码的图片数据，为空，默认服务器签章图片(印模为手写章时，该项必填)pageNum必填，签章页码-1:表示关键字所在页数未知(某页)，系统从后向前查找(关键字模式生效)0:表示文档中每页(坐标、关键字模式生效)Integer.MAX_VALUE:表示文档最后一页(坐标、关键字模式生效)keywordsString必填，按照关键字签章，该字段一旦填写，即判定为关键字盖章plainDataCompress可选，待签章文件原文是否压缩处理，1:是，0：否keywordsLocationMode必填，关键字定位方式，1：从尾页向前查找，匹配到就结束，2：查找所有匹配的，pageNum和keywordsLocationMode一起传时，以pageNum的值为主响应参数：codeString返回结果代码msgString返回结果说明datapdfDataString盖上印章之后Base64编码的pdf数据盖章方式二：坐标盖章请求路径：/seal/pdfStamp调用方法：POST功能描述：pdf坐标盖章参数类型说明请求参数：sealIdString必填，印章Id（调用获取印章详情接口获取）T/HBCCIA0002—2023plainDataB64String必填，经过Base64编码的PDF文件serverCertSnString可选，服务器签名证书序号photoDataB64String可选，手写章图片,经Base64编码的图片数据，为空，默认服务器签章图片(印模为手写章时，该项必填)pageNum必填，签章页码-1:表示关键字所在页数未知(某页)，系统从后向前查找(关键字模式生效)0:表示文档中每页(坐标、关键字模式生效)Integer.MAX_VALUE:表示文档最后一页(坐标、关键字模式生效)plainDataCompress可选，待签章文件原文是否压缩处理，1:是，0：否x必填，坐标签章X轴坐标，四位,1000y必填，坐标签章Y轴坐标，四位,1000响应参数：codeString返回结果代码msgString返回结果说明datapdfDataString盖上印章之后Base64编码的pdf数据盖章方式三：盖骑缝章请求路径：/seal/pdfStamp调用方法：POST功能描述：pdf盖骑缝章参数类型说明请求参数：sealIdString必填，印章Id（调用获取印章详情接口获取）plainDataB64String必填，经过Base64编码的PDF文件serverCertSnString可选，服务器签名证书序号photoDataB64String可选，手写章图片,经Base64编码的图片数据，为空，默认服务器签章图片(印模为手写章时，该项必填)qfz必填，骑缝方式，0：左骑缝，1：右骑缝plainDataCompress可选，待签章文件原文是否压缩处理，1:是，0：否响应参数：codeString返回结果代码msgString返回结果说明T/HBCCIA0002—2023datapdfDataString盖上印章之后Base64编码的pdf数据验证pdf盖章请求路径：/seal/verifyPdfStamp调用方法：POST功能描述：验证pdf盖章参数类型说明请求参数：stampDataB64String必填，Base64编码的pdf数据信息stampDataCompressString可选，待签章文件原文是否压缩处理，1:是，0：否checkSealDateBoolean可选，是否验证证书日期checkCertDateBoolean必填，是否验证印章日期响应参数：codeString返回结果代码msgString返回结果说明6.1.8协同签名类生成服务端密钥对请求路径：/cipher/genenrateKey调用方法：POST功能描述：生成服务端密钥对参数类型说明请求参数：usernameString数字、字母组成(特殊字符默认不支持,可在系统参数配置页配置支持特殊字符)String移动端IMEI码isnewString1:新生成公私钥0：不生成响应参数：codeString返回结果代码msgString返回结果说明datakeylengthString密钥长度algorithmString算法publickeyString公钥,Base64编码T/HBCCIA0002—2023服务端协同签名请求路径：/cipher/getSignedVal调用方法：POST功能描述：提供获取协同签名值的功能参数类型说明请求参数：usernameString用户名String设备IMEI码initdataString签名初始数据，调用方初始化后产生，Base64编码numString挑战信息响应参数：codeString返回结果代码msgString返回结果说明datadataString服务端签名后的数据6.1.9数据统计类获取接口调用详情数据请求路径：/monitor/stat调用方法：POST功能描述：获取接口调用的详细数据列表，时间范围不超过一个月参数类型说明请求参数：beginTimeString统计数据开始时间，格式：YYYYMMdd，必填endTimeString统计数据结束时间，格式：YYYYMMdd，必填interfaceNameString接口路径，为空则查询所有响应参数：codeString返回结果代码msgString返回结果说明dataInterfaceNameString接口路径RequestTimeString接口请求时间，格式：YYYY-MM-ddT/HBCCIA0002—20236.2C接口规范6.2.1类型定义对称算法模式typedefenum{crypto_cipher_mode_none=0,/*模式未定义*/crypto_cipher_mode_ecb=1,/*加密模式ECB*/crypto_cipher_mode_cbc=2,/*加密模式CBC*/crypto_cipher_mode_cfb=3,/*加密模式CFB*/crypto_cipher_mode_ofb=4,/*加密模式OFB*/crypto_cipher_mode_ctr=5,/*加密模式CTR*/crypto_cipher_mode_gcm=6,/*加密模式GCM*/}crypto_cipher_mode_e;对称算法填充typedefenumcrypto_cipher_padding_e{crypto_cipher_padding_none=0,/*不填充*/crypto_cipher_padding_pkcs7=1,/*PKCS7填充（兼容PKCS5填充）*/}crypto_cipher_padding_e;数据格式typedefenumcrypto_data_format_e{crypto_data_format_none=0,/*数据格式未定义*/crypto_data_format_bin=1,/*字节数据，二进制字节数据*/crypto_data_format_der=2,/*字节数据，对二进制字节数据进行ASN.1(der)编码后的二进制字节数据*/crypto_data_format_base64=3,/*字符串数据，对DER数据进行Base64编码，单行输出的字符串数据*/crypto_data_format_pem=4/*字符串数据，对DER数据进行Base64编码，带T/HBCCIA0002—2023BEGIN/END标签的多行输出的字符串数据*/}crypto_data_format_e;证书信息typedefenumcrypto_certificate_info_e{crypto_certificate_info_none=0,crypto_certificate_info_serial,crypto_certificate_info_issuer,crypto_certificate_info_validity_before,crypto_certificate_info_validity_after,crypto_certificate_info_subject,crypto_certificate_info_pubkey,是DER编码公钥）经过Base64编码输出*/crypto_certificate_info_tbs,*/crypto_certificate_info_signature,crypto_certificate_info_signature_alg*/}crypto_certificate_info_e;/*证书序列号*//*证书颁发者*//*证书有效期开始时间*//*证书有效期结束时间*//*证书使用者*//*证书公钥，该数据（SM2是裸公钥，RSA/*待签数据，该数据经过Base64编码输出/*签名值，该数据经过Base64编码输出*//*签名算法（例如："sm2sign-with-sm3"）模块句柄typedefvoid*crypto_handle_t;6.2.2接口列表全局初始化功能描述在一个进程启动后，需要且仅需要一次调用本接口，进行全局初始化后，才能使用其他接口。后续使用过程中，不再需要调用该接口进行初始化。函数名称intcrypto_global_init(void);参数列表无0-成功，其他-失败其他说明无T/HBCCIA0002—2023全局初始化清理功能描述在一个进程结束前，需要且仅需要一次调用本接口，进行全局初始化清理，以释放资源。函数名称intcrypto_global_cleanup(void);参数列表无0-成功，其他-失败其他说明若应用在集成过程中，没有适当的时机进行释放，可以不调用本接口，但禁止频繁调用全局初始化清理和全局初始化。获取版本号功能描述返回非空只读版本号字符串函数名称constchar*crypto_version(void);参数列表无非空只读版本号字符串其他说明无创建句柄对象功能描述根据配置参数，返回句柄对象函数名称intcrypto_new_handle(constvoid*config,crypto_handle_t*handle);参数列表config[in]非空，应用上层定义的配置指针类型，比如自定义结构体handle[out]非空，返回句柄对象0-成功，其他-失败其他说明无删除句柄对象功能描述删除句柄对象函数名称intcrypto_delete_handle(crypto_handle_thandle);参数列表handle[in]非空，句柄对象0-成功，其他-失败其他说明无产生随机数功能描述随机产生指定长度的随机数字节数据。函数名称intcrypto_gen_random(crypto_handle_thandle,intlen,unsignedchar*data);T/HBCCIA0002—2023参数列表handle[in]可空，句柄对象len[in]非空，指定产生的随机数长度data[out]非空，随机数字节数据，缓冲区大小建议设置为[len]字节0-成功，其他-失败其他说明无产生非对称密钥对功能描述产生SM2非对称密钥对。函数名称intcrypto_gen_sm2_keypair(crypto_handle_thandle,crypto_data_format_eformat,void*sk,int*sk_len,void*pk,int*pk_len);参数列表handle[in]可空，句柄对象format[in]输出密钥的格式sk[out]可空，私钥数据sk_len[in]非空，私钥缓冲区大小[out]非空，私钥长度pk[out]可空，公钥数据pk_len[in]非空，公钥缓冲区大小[out]非空，公钥长度0-成功，其他-失败其他说明无产生对称密钥功能描述随机产生SM4算法的对称密钥字节数据。函数名称intcrypto_gen_sm4_symmkey(crypto_handle_thandle,unsignedchar*key,int*key_len);参数列表handle[in]可空，句柄对象key[in]对称密钥字节数据key_len[in]缓冲区大小，建议大小至少为16字节[out]对称密钥字节长度0-成功，其他-失败其他说明无消息杂凑功能描述若应用已加载完所有数据到内存，该接口对指定长度的字节数据消息进行SM3密码杂凑计算，并输出摘要结果。函数名称intcrypto_sm3_hash(crypto_handle_thandle,constvoid*data,intdata_len,constvoid*cert,intcert_len,constvoid*id,intid_len,unsignedchar*md,int*md_len);参数列表handle[in]可空，句柄对象data[in]非空，待摘要数据T/HBCCIA0002—2023data_len[in]非负数，待摘要数据长度cert[in]可空，包含证书或公钥的数据（用于计算SM2签名摘要预处理操作）cert_len[in]非负数，包含证书或公钥数据的长度（用于计算SM2签名摘要预处理操作）id[in]可空，用户ID标识（用于计算SM2签名摘要预处理操作）id_len[in]非负数，用户ID标识长度（用于计算SM2签名摘要预处理操作）md[out]可空，摘要缓冲区（传NULL时，由md_len返回缓冲区大小）md_len[in]非空，摘要缓冲区大小[out]非空，摘要长度0-成功，其他-失败其他说明注1：待摘要数据被作为字节数据进行编码，内部不对待摘要数据做其他编码处理（例如中文编码）0密钥派生功能描述场景：相同的任意长度的输入数据，可以产生相同的指定长度的输出数据功能：对指定原文进行SM3密钥派生。函数名称intcrypto_sm3_kdf(crypto_handle_thandle,constvoid*data,intdata_len,intout_len,unsignedchar*out);参数列表handle[in]可空，句柄对象data[in]非空，原文data_len[in]非空，原文长度out_len[in]非空，待派生密钥长度out[out]非空，输出缓冲区，缓冲区大小建议设置为[out_len]字节0-成功，其他-失败其他说明无1基于杂凑算法的消息鉴别功能描述基于SM3计算指定数据的HMAC消息鉴别码函数名称intcrypto_sm3_hmac(crypto_handle_thandle,constchar*key_id,constvoid*data,intdata_len,unsignedchar*md,int*md_len);参数列表handle[in]可空，句柄对象key_id[in]非空，HMAC运算需要使用的密钥标签data[in]非空，待计算数据缓冲区data_len[in]非负数，待计算数据长度md[out]可空，计算结果缓冲区（传NULL时，由md_len返回缓冲区大小）md_len[in]非空，计算结果缓冲区大小[out]非空，计算结果长T/HBCCIA0002—2023度0-成功，其他-失败其他说明注1：待HMAC数据被作为字节数据进行编码，内部不对待HMAC数据做其他编码处理（例如中文编码）2基于块密码的消息鉴别功能描述基于SM4计算指定数据的CMAC消息鉴别码函数名称intcrypto_sm4_cmac(crypto_handle_thandle,constchar*key_id,constvoid*data,intdata_len,unsignedchar*md,int*md_len);参数列表handle[in]可空，句柄对象key_id[in]非空，CMAC运算需要使用的SM4密钥标签data[in]非空，待计算数据缓冲区data_len[in]非负数，待计算数据长度md[out]可空，计算结果缓冲区（传NULL时，由md_len返回缓冲区大小）md_len[in]非空，计算结果缓冲区大小[out]非空，计算结果长度0-成功，其他-失败其他说明注1：待CMAC数据被作为字节数据进行编码，内部不对待CMAC数据做其他编码处理（例如中文编码）3对称加密功能描述对输入数据进行SM4对称加密运算操作。函数名称intcrypto_sm4_encrypt(crypto_handle_thandle,crypto_cipher_mode_emode,crypto_cipher_padding_epadding,constchar*key_id,constvoid*iv,intiv_len,constvoid*aad,intaad_len,constvoid*data,intdata_len,unsignedchar*enc,int*enc_len,inttag_len,unsignedchar*tag);参数列表handle[in]可空，句柄对象mode[in]非空，对称算法模式padding[in]非空，对称算法填充key_id[in]非空，对称密钥的标识iv[in]可空，初始向量iv_len[in]非负数，初始向量长度aad[in]可空，附加数据(GCM模式)aad_len[in]非负数，附加数据长度(GCM模式)data[in]非空，待加密数据data_len[in]非空，待加密数据长度enc[out]可空，二进制密文数据（传NULL时，由enc_len返回缓冲区大小）enc_len[in]非空，密文数据缓冲区大小[out]非空，密文长度tag_len[in]非负数，若对称算法模式为GCM，则需要指定输出的认T/HBCCIA0002—2023证数据的长度tag[out]可空，若对称算法模式为GCM，输出认证数据，缓冲区大小建议设置为[tag_len]字节0-成功，其他-失败其他说明注1：待加密数据被作为字节数据进行编码，内部不对待加密数据做其他编码处理（例如中文编码）4对称解密功能描述对输入密文进行对称解密运算操作。函数名称intcrypto_sm4_decrypt(crypto_handle_thandle,crypto_cipher_mode_emode,crypto_cipher_padding_epadding,constchar*key_id,constvoid*iv,intiv_len,constunsignedchar*enc,intenc_len,constunsignedchar*tag,inttag_len,unsignedchar*dec,int*dec_len);参数列表handle[in]可空，句柄对象mode[in]非空，对称算法模式padding[in]非空，对称算法填充key_id[in]非空，对称密钥的标识iv[in]可空，初始向量iv_len[in]非负数，初始向量长度enc[in]非空，待解密密文enc_len[in]非负数，待解密密文长度tag[in]可空，若对称算法模式为GCM，则需要输入认证数据tag_len[in]非负数，若对称算法模式为GCM，则需要输入认证数据长度dec[out]可空，明文数据（传NULL时，由dec_len返回缓冲区大小，建议设置为[enc_len]字节）dec_len[in]非空，明文数据缓冲区大小[out]非空，明文长度0-成功，其他-失败其他说明注1：待解密数据被作为字节数据进行编码，内部不对待解密数据做其他编码处理（例如中文编码）5枚举证书功能描述枚举所有证书函数名称intcrypto_enum_certificate(crypto_handle_thandle,char**buf,int*buf_len,int*num);参数列表handle[in]非空，句柄对象buf[out]可空，证书列表，每个证书之间使用'\0'结束，最后一个证书使用'\0\0'结束，为空时返回buf_len实际缓冲区大小buf_len[out]非空，证书列表长度num[out]可空，证书个数0-成功，其他-失败其他说明无T/HBCCIA0002—20236非对称加密功能描述使用外部传入SM2公钥或证书对输入数据做加密运算并输出结果。函数名称intcrypto_sm2_encrypt(crypto_handle_thandle,constvoid*cert,intcert_len,constvoid*data,intdata_len,intno_asn1,intno_c1c3c2,unsignedchar*enc,int*enc_len);参数列表handle[in]非空，句柄对象cert[in]非空，包含证书或公钥的数据cert_len[in]非负数，包含证书或公钥数据的长度data[in]非空，待加密数据data_len[in]非负数，待加密数据长度no_asn1[in]非负数，用于控制密文输出格式：0-SM2密文经过ASN.1(der)编码，1-SM2密文不经过ASN.1(der)编码。no_c1c3c2[in]非负数，若no_asn1设置为1，用于控制密文输出格式：0-SM2密文格式为C1C3C2，1-SM2密文格式为C1C2C3。enc[out]可空，密文数据缓冲区（传NULL时，由enc_len返回缓冲区大小）enc_len[in]非空，密文数据缓冲区大小[out]非空，密文长度0-成功，其他-失败其他说明注1：待加密数据被作为字节数据进行编码，内部不对待加密数据做其他编码处理（例如中文编码）7非对称解密功能描述使用SM2内部私钥对输入数据做解密运算并输出结果。函数名称intcrypto_sm2_decrypt(crypto_handle_thandle,constvoid*pin,constvoid*cert,intcert_len,constunsignedchar*enc,intenc_len,intno_asn1,intno_c1c3c2,void*dec,int*dec_len);参数列表handle[in]非空，句柄对象pin[in]可空，用于获取私钥权限的参数，比如口令cert[in]非空，包含证书