《GM-T0131-2023 电子签章应用接口规范.docx》由会员分享，可在线阅读，更多相关《GM-T0131-2023 电子签章应用接口规范.docx（29页珍藏版）》请在课桌文档上搜索。
1、ICS35.030CCS1.80中华人民共和国密码行业GM/T0131准2023电子签章应用接口规范E1.ectronicsea1.signatureapp1.icationinterfacespecification20206-012023T204发布国家密码管理局发布目次前言IIII范围I2规范性引用文件I3术语和定义I4缩略语25电子签章应用接11概述25.1 通用要求25.2 服务调用接口45.3 组件调用接口46Iit务调用接口46.1 基础接口46.2 综合接口127组件网用接11217.1 基础接口217.2 媒合接口28附录A（规范性）自定义JSON出文数据结构36附录B（规他
2、性）自定义C语言数据结构42附录C（资料性）典型服务网用接11示例51附录D（资料性）典型组件调用接口示例54冏录E（规范性）格误代码定义57财文献60前B本文件按照GB，T1.I-2020标准化工作目则第1部分：标准化文件的结构和起草规则的规定起草.请注意本文件的某些内容可能涉及专利.本文件的发布机构不承担识别专利的贡任.本文件由密玛行业标准化技术委员会提出并日口。本文件起草单位：北京国踪信安科技有限公司、北京数字认证股份有限公司、上海市数字证书认证中心有限公司、数字广东网格建设仃限公司、北京点聚信息技术右限公司、方正国际软件（北京）有限公司、三太信安科技股份行限公司、北京悟安世纪科技行限公
3、司、航天网安技术（深切I）行限公司.本文件主饕起草人：妻岭.郑志梅，张立1.封维福、李中声、张永强,刘岩,赵子轩、赵剑竹、车胜跃、李材险、汪杰、刘梦吟、砧猛、杨玉坤、季地、i志权、王腌飞、蕊松.电子签章应用接口规范1范B1.本文件规定了电子笠章系统对外提供的服务接口，为电子基章系统与应用系统之间提供统一的散据交互格式和使用接口,包括服务喝用和组件调用两种电子印章使用接口形式.本文件适用于电子签章系统的研制、使用和依测，以及基于电子签章系统的应用开发.2胡范性引用文件下列文件中的内容邮过文中的规范性引用而构成本文件必不可少的条款.其中.注日期的引用文件.仅该日期对应的版本适用于本文件：不注日期的
4、引用文件,其最新版本(包括所有的修改单)适用于本文件.GBT20518信息安全技术公阚域础设施数字证书格式GBT20520信息安全技术公的荔础设旗时间戳规范GBT32010.1文献管理可移If1.文档格式第1部分：PDFI.7GBT32905信总安全技术SM3密码杂凑舔法GBT33190电子文件存储与交换格式版式文档GBT33560信息安全技术密码应用标识双范GBT35275-2017信息安全技术SM2烹码算法加密摘名泊忠语法现苑GBT35291信思安全技术智能海码钥匙应用接11现范GB,T36322信息安全技术密码设备应用接口规范GBT38540-2020信息安全技术安全电子签章密吗技术设范
5、GMT()031-2014安全电子签章密码技术规伍GM.T0094-2020公用密码应用技术体系枢梨现行GM1T0099开放式版式文档密码应用技术规范GM1T0112PDF格式文档的定码应用技术要求GM1Z4001密码术语RFC4648BaSCI6、Base32.BaSC64软据酬码格式(BaSe1.6.Base32.undBasc64DataEncodings)3术i和定义GM1Z4001界定的以及下列术语和定义适用于本文件。3.1电子印章e1.ectronicsea1.一种由电子印章制作者数字链名的安全数据，注：包括电子印章所有着信息和图形化内容的数据.用于安较箸数据电文.【来源:GBT3
6、85402020,3.1)32电子签章e1.ectronicsea1.Sigmiture使用电子印章签岑数据电文的过程,由电广卷堂可实现,j纸明文件券章操作相似的可视效果可保障收楙来源的真实性、依据完整件以及签名人行为的不可否认性.来源：GB.T3854020203.2133筌京康务CkC1.nJniVsai1.signatureMTVkrC提供支持OFD和PDF等格式的数字电文的电子卬章签詈服务.3.4电aTS章系统e1.ectrnksea1.signaturesystem对数据电文梃供电子签章、数字签名、签名监证等取务的软件系统.33分散式签章decentra1.izedHectronks
7、ea1.sijnnture在电子FIJ章所有者掌控的密码模块中实现电子印章私税的存储及共计匏.%私税计算包括蝌签名方法.3.6集中式筌tcentra1.izede1.ectronicsea1.signature电子印章私审统一存储在指定的率码设备中.该密码设符由电子经章系统掌控。电子印章使用者通过电子签章系统实现对电子印球的使用.3.7用户印章usersea1.用户在电子笠供系统里被授权的电子印难3用户证书usercertificate用户在电子筌章系统里被授权的数字证书Q3.9B/S模式bnmM?r/scrvcrmode客户端统一为WEB浏览潺，系统功能实现的核心部分条中到眼务寄上的一种应用
8、系统模式。下.列缩略语适用于本文件DER:可疥可编码规则(DiS1.ingUiShedEncodingRu1.es)HTTP:超文本传粕拙议(HyPCrTextTranstcrPxtoco1.)JSONJavaScrip1.对象标记(JUYISCripObjectNotation)OFD:开放式版式文档(OPenFixed1.ayoutDocument)O1.D:对象标识符(OcctID)PDF:可移植文档格式(PoiiaHeDocunientFOng1.)PKI:公钥玳W；设i(Pub1.icKeyInfrasirucmre)SDK:软件开发工具包(SofIWareDeve1.opmcniK
9、iU5电子筌，应用接口集述5.1 通用要求本文件在GM疗00942020中笫4点的公物密码应用技术体系框架中的位况见图1.n1电子餐,康用捱口在公的宙碍应用技术体系事中的位置电子笺章应用接口包括服务调用报口和姐件词用技口两种按形式。服务调用可果用HTTP或HTTPS股务.组件调用可柔用抑署在川户辎的D1.1.SO等SDK组件.这两种接【1形式分别包含基础庖用接口和坊令应用接口，支持分散式空场和集中式空章两种模式，电子茶率应用接口列表如表1所示.1电子筌常庾用接口列我分类序号接口名功能些砒181SEF-GetProvi?。【，】D根据卬章名称/IDft沏卬堂4SEF-St1.erCertInfo
10、1.ist获取川户证书伯息列表5SKFJtCcrtByCcrtS根JW让书庠列号包谢还书6SEFGetA1.eO1.D获取签名和杂凌。法标识7SEF-PdCkSignZVaIue封装花瓶结构8SEI(idinrxtn11pToSig11cn1.uc添加时间能到签章结构体9SEF.PcickSignedMessiige封装消找名结构10SKFVcrifySi(ncUhtn验证签京/Jf1.息签名数弼11SEF(tSinedVa1.ue1.nfo婚折签单数需12SEF3SCidInfC解析印章数榭13SEFGHErrMeSSngg获取错误信息综合接口1SEFSea1.SignByPosition文
11、件定位笙章2SD:Sa1.SisnOnKeywords文件关键字笠率3SEFSea1Si11OnCrosspafies文件加;S构隹聿4SEFCertSign文件数字绘名5SfiFAddAnnnt文件添加文字或图片注群1电子却I池用接口列表(：分类序号接口名功能烧介tt116SEF.VerifySea1.SicndFik文件笙章验证7SEF-YerifyCertSignedFi1.e文件发名较证8SEF_GtSigrffiwwIvsuhMessaseStrinj;Ai与I。领I1.Ccdo对应的文字说明WTFN编码)ProVIderXaneStriru;mr织码的独章城务名移ProvidcKc
12、npttnyStringAJIrTF-8码的卷翼服务提供商的公司名称ProviderVerdKMiStringAJ签ttn务版本extCndPnrnnString否IrTF-8技女眼务如展信息6.1.2 R用户印M列赛功能描述：获收用户印章侑息列表，返回印章名称，印章标双，印章状态和印章版本号信息列表,对于分版式用章.为枚举智能密码物匙里的印章信息列卷,对于集中式用章.为获取指定的用户印章信息列表.接口地址：HTrP(三)“SERVER:PORTjSEFV1，SEFGCIUSC1.SCa1.Infb1.kt诩用方式：HTTPPOST(JSON)访求参数：荻取用户印章信息列表JSoN格式诂求新数
13、见表3.3禁取用户印章侑洲H*京敷数名称类型是否必逸描述rcqurstTix?Int时间1.为当前时间的亳秒数,用于超时校验userIDString用户以集中JWX应为非空,分WtK用点可为空SiteIDString否外部应用ID,当有多个外用:应用时可区分不同外部应用,适用于集中式鳌在statusInt印京状态英求.0：所在；I：疗效:2:无效：3:冰结nuthTyprInt认证类型.0:无认证I1:token认证12:第名值认证authVa1.ueString三认证数据，如!K是左N值认证,则生幺以法默认为SM2,2S名朦文为上向所仃请求参数胤序组A-响应金数：获取用户印章信息列表JSoN
14、格式响应参数见表4。4狭*用户印章假列蒙皮f1.圆数幺称类熨是否必逸描述Fcxu1.tCodcint。太东或功，等O表示搭次码rstMcssageStrin是与I。川k储血的文字说明OTF8编码)useiea1.1.nfo1.istfte5ea1.JnfoObject是用户印章伯忍列表.对应的用户印章僧恋心跳雅文结构定义标符合表A.I的规定6.13机印景名彝D好印章功能描述：根据F1.J章名称或否印章IDCi珈印率数据.接U地址：HrmSMSERVER:1.JoR1.vSE1.VSEF-QuCTyseaIsByNumcOrID调用方式：IrrTPPoST(JSON)请求参数：根据卬章名称/印章
15、ID五询卬章的JSoN格式诂求参数见表5。5根印章名勤印,IDg印，的请求敷等故名称类型选否必选描述request!imintIHffitt.为当时酎间的冬杪数,用于曲时校验Jcu1.Nan?String否印依名称scv1.IDString否印SHD9UtUSint印章状态，0：所有：1：有效：2:无效：3rffi注1SCa1.wIB1.ra1.!D至.少百方!是外效的，如果两顼同时有效.则两个条件同H怖足,响应参数：根据印章名称/印章ID杳询印章的JSON格式响应参数见表6.6艘印，名彝/印章IDg印M皮敷叁数竹林类型是否必逢描述resu1.tCodeint是。表示成功非。表示错设码reuI
16、IMessaueStringmu1.tC知对次的文字说明(IrTFH般吗)!Cca1.IAntaInto1.istSnn1.Dntn1.nfaObject印章敷露信1刖&.对应印章数据信必JSO找文玷构定文应符合表M2的规定6.1.4SHM户证书JB科功能描述I获取用户证书信息列表.分散式用章枚举智能密码切宓里的数字证书，集中式用章只能获取指定的用户证书.本接口只荻取对陶的签名证书,数字证书格式符合GBT20518接口培址：HTrRSMSERVER:PoRT.，SEFJV1.SEF-GctusciCcnIntb1.R调用方式：HTTPPOSTIJSON)请求参数：狭取用户证书信息列衣JSON格
17、式请求亚依见我7.7网用户ii用值勤M与敬名称类型是否必选描述rcquestTimeint时间值.为当时时间的电杪数,用于超时校验userIDSIrine否用户m分Bt或签章为UI1.泰中戌签京不健为XU.I.SitCIDStrirxR否外部应用也当行名个外郃应用时可区分不同外部应用，适用于集中式小拿statusint是正H状态.0.ffii1.ff：2:无效：3:冻结auIhTypeInt站认证类型，0：无认if;1.tokWi认证；2:笙名值认iauthTypeInt是认证类型.0:无认i:1:token认证：2:塞名,(ft认任响应参数：获取用户证竹信息列表的JsON格式晌应参数见表&爱
18、B班用户呻值息网Wft警数名欲烫型是否必选描述rcsuItCodint。龙示成功.#0表示拈说码rcsu!tMcxscString与11)8u1.Cod。时应的文字说明WTFTifiHq)UserCertInfo1.is1.UsriCcrtInfoObject是用户数字IEH列表.对应的用户证HfS6JSc5tincIn1.HMff1.为当IIt时间的，秒三用于1时校检CgrtSNString证书序列号3tAtU8int正书状左.。:所I小奴I2：无效I3：冻结晌应参数：根据证竹ID获取数字证竹数据的JS0、格式响应参数见表10.13封重结的请求St类型是否必选描述requestTi1.ieS
19、tring是时何值,为当匍时间的与秒数,用于超时校验userIDStringS用户ID.分敢式用章时为N1.1.1.如果是集中式用京.不能为NU1.1.SitgIDString否外部应用ID,当右多个外部屋用时可区分不同外籍也111.适用于集中式笠章SeauDString是印章标识PropercyInfoString否版文砚性.般为苏凌保护范阳对应的原义地信息(Iata1.1.ashString是签章保护Ki文数掂的杂次低数掂的Baa61编印HU1.hTyptntW认证类型.Q:无认UhIMohMMt,2;提名值认UEauthVnucString否认证值数据；如果他花名也认证，选名算法狄认为S
20、M2.线名原文为上面所有谛求参数依序加合响应参数：封装签章结构的JSON格式响应数见我14.14MK三MWn*参数名稔类型是否必地描述rcu1tCodcint是。衣小成功,非。农示炳误码resu1.tNessageStrinu是与resu1.iCSEF_AddTinKsiampToSeaISignedVaIue调用方式：InTPPOST(JSON)请求年数：添加时(BJ散到笠堂结构体的JSON格式请求参数见表15。*15*加时间签事构体A求段舲故名林类型AJ否&地requstTineintMOi1.frt.为当也时间的亳陟敛,用于邠时校验XPJiISignndVn1.uoStringBeee4
21、H的签章结构(不帝时间ItOtinestarpStringBiij8NH编吗的时间触应挎介GB/T20520的规定响应参数；添加时间筱到签章结构体的JSON格式响应参数见表1616津加时闾11到签M构体响应Tk参数名祢英型是否选描逑Fesu1.1.Codeini是0表水成功，小。表示任设码resuItMessageString是与IXjaHtCock对应的文字说明（ITFF编码）OutSea1.SienedVa1.ueString是g30&1温叼的带时间鼓的器中结构.仙果笏幺尊法为SM2,应符合C8/T38540的规定6.1.9封蒙湾筌绐构功能描述：调用户印章私钥诳行数字签名，料装不含时间我的
22、消息签名数据，如果彩名算法是SM2.消息签名数据应符公GB,T352752017中第8章规定的签各数据类型。接口地址：HTTP仿）:/SERvER:PORTNEEM,SEF-PackSigncdMcssagc调用方式：HTrPPoSTUSoN）请求参数：封装消息签名结构的JSON格式请求参数见表17.17封奘消息签名1构的请求敷参数名称类型是否必地描述requestTineString是时间依为当的时间的举秒数用丁妞时校验UgerIDString否用户IIK分散式用*时可为空.集中式用市时不能为SiteIDString否外部应用10.当仃多个外部吨用时可M分不同外需应用.增用F奥中式签章ccr
23、tSNString近书序列号data1.hshStringftBose61编码的若章保护原文数据的杂淡值（不带I。）diestMethodStringa原文杂决算法3D.吨符fGBT33560的规定11uthTycint认证炎里.0:无认近：1.token认it：2:?Sgtf认证authVa1.ueString否UkiiEffiftIW:如果是签名位认强.签名打法犹认为SX2.答名城义为上面所有请求叁Ii顺序,I合响应参数：封装消息签名结构的JSON格式响应参数见衣18.18时装消息筌名飨构的响皮敷警数名称类型是否必选描述Fcxu1.tCodcint0我东成功.#0次东H1.设码r8uJtH
24、essageString是与ER1.tCwkM前的文字说明(TF-8ft)%ignodk%itg0Stringg3c610FJ的酒.起卷X匕朝,如果使用S2算法,应符合G8XT35275规定的不幺数家类梨IO6. i.io功能描述；唳证电子笠率/消息笠幺数矩.笑堂数据应按照GB,T385402020中7.3的电干笠率验证流程进行验证；消息签名数据应按盥GB/T3S275的规定对消息翌名格式进行验证.接口地址,HTTP(SWSERVER:PORT?SEF/V1/SEFVeiifySigiKdData调用方式：HTTPPOST(JSON)谙求参SU的证答H/茶名数据的JSON格式请求参数见表19.
25、193证差/筌名的求一般改名称类型是否必选描述requestTi!x?int是时何故,为当计时间的在秒数，用于招时校验data!IashStringBose61明码的杂浊数据XigncdDatnString是IteSe64$码的等附/笠幺数据SignStructTypeint签章或者签名格式英皇.机未知：hCB/f38540:2:G&T35275：3:CM/T0031:4:PkCS7-咫A响应参数：验证签章/笠名数据的JSON格式响应参数见我20.202s*/x*aKa叁数名称类禁是否必选iresu1.tCodeIntD我示成功非。表示锚误码PU1tUcSSgCS1.rine与汁眈1ICcde
26、对应的文字说明(InF-8编冏)6.1.11功能描述I从电子笏章数据中获取相关信息,包拈签章时间、第名算法、誓章保护原文hash好,至少应支持GBJT38540f1.IGMT0031及定的电子签章数据.J2HHTTP:SERvER:PORITSEFV1JSEF-GCISigDCdva1.UCHb调用方式：HTTPPOST(JSON)请求参数：解析签章数据的JSON格式请求参数见度21.21集桥筌案敷的请求fft电数名称描述request!ineint时间他为当r时间的亳检tt用T他时校注SijjncdVa1.ueStringBrtge64金码的茶章数据versionint签章匕据版本响应参数；
27、评折釜章数据的JSoN格式响应否数见表226.3.3 文件须功能描述I对文件加藕骑岗章,可设置的健由纵坐标位置,以及一个整章切分的份数,同时可设置是否加盅主章，如果存在主章,需蹙指定主章所在页面的位置坐标。接口地址：H1.TP(SERVER:PoRT,SEFVI/SEFSca1.SignOnCrospagcs调用方式：I11TPPOSTeint请求时可.为当前时何的独与I1.读时间用于一时校4.不要用做签承时何fikteString必UTF8编码的文件名fiIcOatnTnioStringft数柢电文类型,H1.eDataStrinRttRamMa(特按章数据电攵或S1.nF8收码的数据地址，
28、具体根据入蠢fi14U11确定IockFiIcint是否钺定文件.0:不钺定，1:签章方丈镇定，2:签章后再涉知泊&翁名力式像定USerIDString否JBPID.分微式用章时可为XV1.1.集中式用章不能为W1.1.sitIDString否外却应用血小区分不同外部应用，运用f服务器签章场疹OU1.FiIWaUITyPeint返回数据类型，0：数据电文如，1：数弼地址1.A!eCrOssSea1.SiAsnInfc1.ist(PegcCrossSeeISign1.nfoObject骑堆事怕总列衣M应皆犍空印用伪总JsoMft文站构物符合&A.8的规定iiuthTypc*int是认证类81,0
29、:无认证IInokEikifi2:笠名做认证SUthVa1.ueString否认证他数抠：如染是注Wift认证，笠8。法默认为S2.若名蒯文为上面所行谛求参效咂序组合响应爹数：文件加盖骑鞋章的JSoN格式响应每教见衣30峋应参数：文件卷名险证的JSON格式响应参数见表38.38文件筌含威类型是否必选期逐resuItCodeInt0表示成功非0表示辐谀码rcsu1.tUXS3RCString与resu1.iCode对应的文字说明UiTFTai码)fiIrYcrify1.nfoFiInVcrifyInfaObjcet文件44证结果列表，时应文件般证结果JS似报文结构应符合我AjD的及定&28功能描
30、述：获取文件中的签章和消息签名个数.接口地址：HTTP(S上/NERVER:PoRTNEF/VISEF-GetSignCount调用方式：HTTPPOST(JSOX)请求参数：获取文件签章/签名个数的JS(N格式i?5求参数见表39,39期R文件签名个败请求卷鼓名林类型*否&燧Jeiirqucxt1.irIntAiBJMff1.为当前时利的电秒也，用于加时校验fiIcnarrStringUTF-8SS码的文件?fi1.011tnTyp0S1.rinS是数据屯文类中.。:早收据,1:鼓舞地址H1.cEhtaStringAJ阈女门娘码恃笏章数据电文或者UIF8嫔码的散亮地址，J1.体根据入叁nSM
31、sTgC确定响应参数：获取文件维壁/卷名个数的JSQN格式响应参数见表此4H0兼取文田签名M3*爹散名就类型AJ否&域挣述resu1.tCodeint是。表示成功，IH1.我示带误码resuItWeesageString与rrsuIcbdC对应的文字说明ft1.TA8辆码)iK11Cuntint是文件内空名和笠酸电数6.2.9 *三U1.tiE功能描述：验证文件中指定签章或者消息签名，返卜，1验证结果和时应的签章/消息绽名结构体.接口地址：HTrP(三)刃SERVER:PORTfEF/V“SEF_VerifySiSnBy1.ndeX调用方式：HTrPP0ST(JS0N)请求参数：指定答我，签名
32、跄证的JSON格式请求察数见表Ih返回值SEF-SUCCESS:其他：成功描误眄7.1.3相岬量彝ID*K9的致原型功能描述intSEF-QucryScakByNaInCor1.D(CQnStintRcqucstTimc.constchartrchSea1.IDxons(char*pchSea1.Naneconsin(iSta(us,SEA1.DATA1.NHo4Psca1.Data1.nfo1.iMjnt4PiscaIDataI):根据印政名称或者印章ID查询印章数据,或者查询问时满足两个条件的印章数据.多数iReques(Timein)PChSeaIIDin)PChSE1.NamCIini
33、StausinpSea1.Da1.a1.nfb1.is1.(i11ut返回值PiScaIDataIinoutSEF-SUCCESS:Kft1.i:时间做，为月前时间的意秒&.JIJFfii时校验印和DUTF-8编码的印堂名称对印章状态要求，0：所有：1：有效：2:无效：3:冻结印章数据信息列表,当为NU1.1.时，通过PiScaIData1.nfo1.ist1.en给出长度,印牵数据信息结构定义应符合BJ的规定.用户印章数据信息列表长度成功恪误码备注根据印余名称查询的印章可靠包含多个，因此使用列次格式返阿.印章ID和印章名称两者应有一项是有效的，不能都为NU1.1.如果两项同时有效，则两个条件
34、同时满足。7. 1.4禁取用户证书值总丸表的数像型iniSEF_Gc1.UscrCcrt1.nfo1.is1.(cons1.iniiReqesiTime.cons1.charpchUscrID,constchar*pchSitc1.D,cons(intiStatus,constintiAuthTypc,constunsignedchar*puchAuthVa1.uc.constintiAuthVa1.uc1.xn,USERCERT!NFO4pUserCcr1.Info1.st.int*piUserCert1.nfo1.is1.1.en):功能描述获取用户证书信息列玄，对于智能密码钥起,枚举智能
35、密码钥隧里的数字证书，对于集中式用章,只能获取指定的用户证打。本接口只获取对应的签名证也数字证书格式符合GB/T20518.参数iRcqucstTimeinPChUSar1.DinpchSitc1.DiniS(atusiniAu1.hTypcinpuchAuthVa1.ucIiniAuthV(in时间值，为当解时间的亳杪数用于超时校险用户ID,分散式用章时可为NU1.1.,如果是集中式用章,不能为NU1.1.外部应用1D.当有多个外部应用时可区分不同外部应用，适用于集中式签章证书状态,0:所有：1:有效：2:无效；3:冻结认证类型,0:无认证：1.tokcn认证：2:签名值认证认证数据认证数据
36、长度7.1.7封电即构函数原里加SEF-PackSigedVa1.uechAuthVa1.ue,cons(intiAuthVa1.ue1.unsignedCharXPUChSeaISi即CdVUIUCin1.*PiSea1.SignCdVmUe1.Cn);功能描述按照GB13854O-2O2O*P7.2的电子维章生成流程.封装不含时间戳的笠章结均体，签章数据结构和版本号根抠印奉数据结构和版本号决定参数iRcqueMTimeinpchUscr!DinpchSitcIDinpchSea1.1.D(inPChPrDPCrty1.nfQIin1.PuchDaCaHush1.iniDaiaHiish1.en1.inIiAuthTypcinpuchAuthVa1.uciniAuthVa1.te1.eninJpuchSea1.SigncdVa1.ucin/out1.piSca1.SigncdVIinoutIjS0(fiSEF-SUCrESS:其他r时间值，为当前时间的充秒数，用于超时检蛉用户1D.分散式用章时可为NU1.1.如果是里中式用率.不能为NU1.1.外部应用1D.当有多个外部应用时可区分不同
