GM-T0020-2023证书应用综合服务接口规范.docx
目次前音m引言IV1范困12规范性引用文件I3术语和定义14缩略语15算法标识和数据结构25.1 标识定义25.2 数据结构定义26证书应用粽合服务接口定位、分类和要求26.1 证书应用踪令服务接口在公期密码应用技术体系框架中的位置26.2 证书应用综合服务接口分类26.3 客户端限务接口26.4 服务潺端服务接口36.5 数据格式要求37证书应用综合服务接口定义37.1 客户端COM组件接口37.2 服务潺端COM纲件接口137.3 服务器端JaVa俎件接口247.4 客户端JaaScrip（脚本接口35附录A（规范性）证书应用绘令服务接口描误代码定义46附录B（资料性）证书应用综合服务接口典型部署模缗49附录C（资料性）证档应用综合服务接口集成示例50附录D（资料性）客户端JaVaSCriP1.脚本接口异步调用示例说明52参考文献53本文件依托于GM/T0019通用密码限务接口说范3,为应用层规定了统的再殴南码服务接【1.证书应用综合服务接口为应用系统提供简洁、/用的证书应用接口屏板了各类密码设备（服务器密码机和智能率码的比等）的设符定异性,以及各类密码设备的密码应用接口之间的差异性,实现应用与密码设符无关性，可的化应用开发的杂性。证书应用擦台服务接口分成客户需服务接口和服务器端服务接口两类.可湎足B/S和CS等多种架构的应用系统的调用得求，有利于密码果务接11产品的开发,有利于应用系统在密码服务过程中的集成和实施.有利于实现各应用系统的互联互通.IV证书应用综合服务接口规范1«本文件规定了面向证书应用的综合服务接口.本文件适用于公钥密码应用技术体系下密弼应用股务产品的开发，密弼应用支拽平台的研制及检测，也可用,指9直按使用密码设招和密码服务的应用系统的集成和开发.2般范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款.其中，注口期的引用文Ch仅该日期对应的版本适用于本文件I不注日期的引用文件,其挺新版本（包括所有的修改单适用于本文件CGBrrGMTGMTGM1TGM.TGM1TGM1Z25061-2020信息安全技术XM1.数字答名谱法与处理规范OoO6密码应用标识规范OOo9SM2冷码算法使用规范0010SM2济码尊法加密笠名消息语法规范15基TSM2密码算法的收字证书格式双位0019岫用密码服务接1熄范4001密码术语PKCSWIRSA加密标准(RSACryptographyStandard)PKCS#7加密消息调法标准(CryPtOgraPhiCMessageSyntaxStandard)IETFRFC3275(可扩展标记语宫)XM1.签名语法和处理(Exiensib1.eMarkupUnguage)XM1.-SignatureSyntaxandpR>oessing)IETFRFC4648BSd6、BdMJ32和Basc64数据编叫TheBasc1.6.B<Ne32.aJBx64Da1.aEn-CUding、)3术甯和定义GM.Z4001界定的以及卜列术语和定义适用本文件,用户密铜IBCrkey存储在设备内部的用于应用密码运算的善时称格钊身.注：用户诙钥包含签名密钥时和加密语钥对.WScontainer密码设备中用于保存密钥所划分的唯性存储空间.卜列缩略语适用于本文件.客户端服务接口一般通过谓用GM，T0016或GMT0019来实现.主要功能包括：配置管理、证书娜析、维名与脸证、加密与帕密:数字信封、XM1.数据签名与验证等，6.4 务务接口服务器端服务接口采用支持多种编程语；的COM组件和服务端常使用的JaVa语言为例描述，其适用于服务器出程序谑用.接U的形态包括CQM组件、JAR包等.支持主流操作系统.服务诳端服务接口一械通过调用GMjT0018或GNvT0019来实现,功能基本与客户端服务接口相对应，主要包括：配置管理、证书解析、母名与依征、加函与解密数字信封、XM1.数据拓名与验证、时间战等.6.5 敷格式要求本文所涉及的数字证拈格式应符合GMrT0015.本文件所描述的B然c64编码格式参照IETFRFC4648中Basc64Encoding郃分.在没有特殊说明的情况下，本文件中字符小果用UTF8编码，其格式叁照IETFRFC3629.木文件所定义接口返H的错误码或抽出的异常信息应符合附录A.典也就署模型可冬考附录B.集成示例可参考附求C，木文件以CoM组件为例进行接口描述时，所用到的数据类型说明见表1.«1三IafMMiftfimw类型说明BSTR字符串类型,不同的开发语宫应采取对应的类型定义,如，char*.CStrine.java,1.nfi.StringIjONG32titSftSIORTIett挖数IW1.布尔类43其取位范国及TR1.E和FA1.SE,其中TIaE表示Ji值，HU.SE表示侵假空器长度等于。的字符卡非空长度大ro的字符申7证书应用瀛合务接口定义7.1 户C0Mjfi件捱口7.1.1 再户C3fifHKfi½客户螭COM组件接口提供配置管理、证书杯析'签名Ij晚证'加密。解烹数字信封、XM1.数抠签名与验证等功能，共包含35个接【】表2列出了客户端COMff1.件接口列衣,7.1.27.1.36蛤出了接口详细定义。«2客户C0M蛆件捱口列我序乡章条号接口名功能I7.1.2SOFeGeiVersion我取接口的板本号27.1.3SO1.jSeISignMe1.hod设“笠幺以法7.1.2 H取接口版本值息SoF.GetVersion原型：BSTRSOF-GetVersionO描述：获取接U的版本号.多数：无返回值：版本号成功.返回接I版本号失败.可通过SOF-Gct1.aE1or获取符合表AJ定义的错误代码7.1.3 设置签名Jt法SoF-SetSiRnMethod原型：1.ONGSOF_Se【SignMe1.hod(1.oNGSignMahod)描述：设置接11在签名和验签运匏时使用的签名算法.参数:SignMcthod签名算法标识,应符合GWrouo6返回值：Sd1.1.oK喇其他失败，返回符合表A1.定义的错误代码7.1.4 CM9釜名算法SoF-GetSignMethcd原型：1.ONGSOF-CictSignMcthodO描述：获得接口当前使用的签名算法.参数：无返回值：签名舞法标识成功,返回接口当前使用的签名律法标识0接门当前没有设置签名算法1.1.1 设mm法SOF-SctEncryptMcthod原型：1.oNGSOF_SeiEnCTyPtMC1.hod(1.ONGEncryptMe1.hod)描述：设置接1.1.进行数据加密时使用的对称算法.对称加密算法标识，应符合GM.T<XX)6.本接口可支持不帝附加认证数参数：EnCryPtMC1.hod据的加解密算法返回值；SOR-OK成功其他失败，返问友A.I定义的错误代码7.1.6 枚Ihn宙算法SOF-GetEncryptMethod原型：1.ONGSoF-Ge1.Encryp1.Me1.hodO描述：茯得接门当前使用的对称加解密算法.多数：无返阿伯：加密算法标识成功，返I可接Q当前使用的加密算法标识O接口当前没有设置加密算法7.1.7 缺曲书列表SOF-Get1.ser1.kt原型：BS1.RSOF_GctUscr1.i$iO描述：取得当前已安装证书的用户列表.FA1.SE验证失（,失败泉因应符合附录A中t<A.1.中的错误代闪公用失畋，可通过SoI1.GeI1.aStErrOr获取符合表A.1定义的忸误代码7.1.12导出用户加密CE韦SoF-ExportExChangeUeerCert原型：描述：参数：返回值：BSTRSojEXPOrtEXehangCUSerCCrt（BSTRCertID）根据证书唯一标识,获取BaSC64编码的加密（交换）if书字符小.CcnID证书唯一标识加密证书成功，运三m编码的加密（交换证书字符串空甲失败，可通过SOF_GeU_a“Erro<获取符合表A.I定义的错误代码7.1.13禁。证书值JISOF-GetCertInfo原型：BSTRSOF_Ge1.CertInfo(BSTRBase64CEsHoRT描述：获取证书内指定类型的信息。参数：BaSe64Cer1.BaSeM编码的证布字符申TyPe证书解析标识,应符合GM，TOoo6诋回值:证书信息成功，返回证书内指定类型的信息TyPe)空审失败或证书中不存在该项内容7.1.14嵌19证书IriMJBSOF-GetCertInfoByO1.d原型：BSTRSOF_GrtCert1.nfoByoid(BSTRBasc64Ccrt.BSTROid)描述：科数：根WIO1.D获取证书私有忙展项信息.BGCNc«tBaSe64编码的证书字符申Oid私有扩展对象ID.U-1.2.156.xxx''返回值：证书扩展信息空中成功，返成证书私行扩展项OID对应的信息失散或证书中不存在该私有扩展项7.1.15SOFJJetDevkeInfo原型IBSTRSOF.GctDcvkc1.nfo(BSTRCcrt1.DXONGTyPC)描述I根据证书唯-标识和类型代码获得设得侑息.>7：CcriID证书唯一标识Typc设信信息的类型，应符合GMT0006返回值r设饴佰思成功,返回TyPC对应的设饴信息空中失1收.可通过SOF-Gct1.astError换取符合非A定义的错误代码原型：1.ONGSoF_Va1.K1.MCeeTt(BSTRBase64Ccrt)描述：参航收证证书有效性.BiISC64CEBasc64腕码的证书字符串返回由SAR.OK验证成功7.1.1.ItSiE中有效性SO1.Va1.idateCertK他QXoBOoo5(XOXOBO<M5057.4.32 任书登出SOFjQimit151型：functionSOF-1.OgoUt(CCrt1.Dcb.x)Iffi述：退出登录状态.卷数；Ccrt1.DCbC1.X½MM:(R1.Cfa1.se证书唯一标识回调一敷W谑函数所需参数成功失败.可通过SoF一Get1.astErtor烧取符合衣A.I定义的错误代码由证书登出衣示师放该证仿用户对应的私钥使用权限.证书登出后再征用签名、解密等霜蝴有私登使用权跟才修正常操作的接”时,需再次成功调用SoF1.ogin接”获取私钥使用权限.7.4.33 用户H状本IMSOF-Is1.oRin原型：fundionSOF_M.ogm<Certir),cb,cix)描述：判断证书用户是否为登录状态.参政，Cen1.Dcb诙书唯一标识回调函数C1.X½Htt:trcfa1.
