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.se何谓函数所需叁数修求状态非登录状态«a.icom烟件的IHI代码班（Ir宏描述f定义值说明S0«NotKxportKrrOXOB00031i对象未导出SORVcryPo1.icyErrOXOB000312未能完全按照策略验i£成功SOR-DccryptPadErrOXOB000400解密时做补丁错误S0«,Mac1.enErrOXOBOOOIOIMACKfStfiiaSOKKey1.nfoTypeErrOXOBOOO-102密钥类型错误SORNU1.1.PointerErrOXOBOOO103某一个参数为空指针SORAITNotFoundErrOXOBOOOIOI没有找到该应用SORCERTEXCODEErrOXOBOOO105证书编码格式错误SOR.CERTIWA1.IDErr0X0B0G0406证书无效，不是可信CA领发的证书SoR-CERTIIASEXPIREDErrOXOB000107证书已过期SORCERTRB1OKEDerrOXOBOOO408证书己钱被吊销SORSIGNDATAErrOXoBooO409鸵名失败SORVERIFYS1.GM)ATAErrOXOBOO0110监证笠名失败SOK.RhWI1.EErrOXOBOOO1.1.1.读文件弁常，可能文件不存在或没有读取权限等SORWRITEFI1.EErrOXOBOOO112写文件异常,可能文件不存在或没有写权限等SORSHCRETSEGMI-VFErrOXOBOOOH3门限尊法密钥分割失败S0«SKCKKIKECOVEKYErrOXOBOOO114门眼利受失败SORESfRYPTDATAErrOXOBOOO115对数据的对徐加I密失败SORDECRYMDATAErrOXOBOOOn6对称算法的数抠解密失效SORPKCSTENCODEErrOXOB000117PKCS7编码格式情误SORKM1.ENCDDEHrrOXOB000418不是合法的X迎编眄数据SOKPRMETERNOTS1.PIX)RIErrOXOBOOO119不支持的参数soR.ct1.notfoundOXOB000420没有发现侑任列表SorappnoifoijNDOXOB000421.设置的应用名称没发现SORCERTXOTTRUST0X0B0G05O0验证证书失败,证拈不被信任SORCertiiasexpiredOXOB0005O1验证证书失败.证书胡过有效期范憎SO(1.CERTHASREYoKEDOXOB0005O2验证证书失败，证书已作废SORCI-RTHAS1.iO1.DH)OXOB0005O3监证证书失败，证书1.I冻结SOKCERNOTVR1.IDYETOXOB0005OI验证证拈失败,证书未生效soRCertverifyoihererrOXOB000505验证证书失败,共他错误«A.2JAMMa件的异常值0ft异常挪还说明java.1.ang.PointerException某一个参数为仝指计SOR-InitExccption初始化环境失败S0R_AppNotfOundException没有找的漆应用SOK_CertEncodcException证书编用格式格设SOKCcrt1.nva1.idExceptioni三书无效.不是可倒CASt发的证书SOK_CertNotYetVa1.idException证书未生效SORCertHasExpiredExceptioni三书已过期SORCertRevokedException证书1.1.经被小倩SOR-SignDataException线名失败SORVerifySignDataException发述纥名失K1.SORReadFi1eException读文件片常可能文件不存在或没仃读取权限等SORWriteFiIeException写文件界常.可能文件不存在或没有写权限等SOR-SecretSegmentException门限分割算法失败SORSecertRecoveryException门奴情北失败SOREncryptDa1.aExctyption数据加密失散SOKDecryptDataExccption数据解密失败SORPkcsTEncodeExceptionPKCS#7编积格式错设SORXm1.EncodeException不是合法的XMuft眄数据SoR.Parameter、OtSUPPOrtEXCePIion不支持的咨教SORFncryptDataFxception数据腐密失败SORIkycryptDa1.aException数据解,密失败SORMessageEncodeException湎息编枳格式错谈SORXin1.EncodeException不是合法的X儿埔包牧据W»B证书应用修合务接口MMHM基FB/S架构应用系线的证书应用综合服务接口的部署示意图见图B.I.nB.1B/sf1.r构应用系拉的典SHE书应用接口“示意图在应用服务网端应部*的软件包括：证书网用综合服务接口（服务器端接口，接口形态也为COM组件或JAvA姐件两类）和其他底层密码眼务接I（包括I率码设备接U和通用密码眼务接IJ等）.应部田的硬件是密码设备,如密码机或玄码卡，用于梁务器端的签名、验证、,加密、解雷等密码运算.证书用户客户端可以是PC机、手机或其色智能移动终掂.部善的软件包括：证书应用琮合服务接（客户端接口，接口形态一般为CoM组件、动态库或JavaScript等形态,防若技术的发展接口形态可以进行扩展）和其他底层密码服务接11（主要包括智能ICR/智能密码钥½应用接11fJ通用密码服务接口、证书较体弱动程序等）.附郃署的硬件足容码设备.如智能IC卡或智能密码物电（USBKCy）.用于客户福的签名、脸证、加密、制密等密码运兑”(XMtt)证书应用0合务捱口拿取示例典V.证书登录认证流程图见图CI.Bc.证书H认证SUaMHB旗表单业务数据的筌名和验转流程见图C.2.C2曹务强字筌名证充基于表单业务数据的签名和验签流理,常首先按照图C完成证书登录认证流程，登业认证成功后，业务系统展示交易衣用,证书用户根据业务系统展示的表取填写业务交易数据，检查无误后提交业务申请,提交业务中请时需对业务交易数据做数字签名,根据业务数据不同可选择调用不同的签名接11I 如果业务数据是普通数据,s/11SOF-SignDaia接I： 如果业务数据存放在文件中,调用SoF-Si即M1.e接I； 如果业务数楸是XM1.格式，调用So也SignDaIaXM1.接U1. 如果业务数据是消息，调用SOF-SignMzage接口； 仙果业务数1«仅以Hash方式提交.先调用SoFHa$hData岐SOFHashHIe.再调用SOh1.SiRnHashData接口.业务交易数据和签名值起提交到业务系统服务器.业务系统服务罂议用对应的依证接I1.验证正确后进行业务处理，完成后提示用户交易成功。M*1>(资料性)客户.如、HSCriPt本接口鼻步用示侑说明为保证多种类型浏览器的兼容性，7.2客户端脚木接口枭用异步调用方式定义.斑个功能接口都时应个月调函数和个【可调参数对象,网调函数的原型为：functionca)1.b<K：k<resu1.t.c1.x)功能接口的返回V1.通过resu1.t参数传递给回词的数对功能接口返回值的业务处理代码在回调函致内完成.如果回调函数不需要CtX参数,调用功能接口时可传递空值或忽略.使用示例：functionSOF_GetVersion_cb<rcsuk.ctx)(a1.ert("接”版本号为：“+resu1.t);业rt(“调用者传入的回调入数"+CU);SoF_GetVCniiOn(SoF_GetVCrSiOn_cb);所有功能接口的返回他都通过回词函数的resu1.t返回,功能接口本场没有返回值.如上述调用.在获取根本号时,应在刈调函数SoF_GeNerSiOnJb中接收SoF_GeNeNion接I1.的返到伯井做相关业务端处理代码，如下是不正确的使用方式：VarMrVersion=SOF_Ge«Version();因功能接口采用异步祖用方式定义.StrVcNion变盘并不保证能正确荻取到版本号。)2电文IK11GBT197132005侑息技术安全技术公物基础设旗在城证书状态协议12JGM1T0016智能密科钥匙密码应用接口规范GMjT()094-2020公物密码应用技术体系框架规范4RSASecurity:Pub1.ic-KeyCryptographyStandards(PKCS)PKCS例ICryPIographicTokenInterfaceSunchrdIETFRFC2459InternetX.509Pub1.icKeyInfrasiruciureCertificateandCRI.Profi1.e(7IETFRFC2560X.509InicmctPub1.icKeyInfrastructureOn1.ineCertificateSutusProtoco1.8IETFRFC)7771.ightweightDirectoryAccessProtoco1.(9IETFRFC2587Interne!X.509Pub1.icKeyInfKIrUeIUrU1.DAPV2Schema(10IETFRFC3647InternetX.509Pub1.icKeyInfrastructureCertificatePo1.icyandCertificationPracticesFrainewort(111SO.,1EC8X25-1:2021Informationtechno1.ogyASNJencodingruksPan1:Spccifica-IionofBa>icEncodingRu1.e(BER)iGinonkaIEncodingRUkS(CER)andDiMinguMxdEncodingRu1.es(DER)