GMT 0020-2023 证书应用综合服务接口规范

代替GM/T0020—2012证书应用综合服务接口规范国家密码管理局发布I前言 N 1 13术语和定义 1 1 25.1标识定义 25.2数据结构定义 2 2 2 26.3客户端服务接口 2 36.5数据格式要求 3 37.1客户端COM组件接口 37.2服务器端COM组件接口 附录A(规范性)证书应用综合服务接口错误代码定义 附录B(资料性)证书应用综合服务接口典型部署模型 附录C(资料性)证书应用综合服务接口集成示例 附录D(资料性)客户端JavaScript脚本接口异步调用示例说明 53Ⅲ本文件按照GB/T1.1—2020《标准化工作导则第1部分：标准化文件的结构和起草规则》的规定起草。本文件代替GM/T0020—2012《证书应用综合服务接口规范》,与GM/T0020—2012相比，除结构调整和编辑性改动外，主要技术变化如下：a)删除了术语“数字证书”(见2012年版的-3.1);b)增加了Base64格式数据的更明确描述(见6.5);c)增加了接口“证书登出SOF_Logout”(见7.1.35)、“证书登录状态检测SOF_IsLogin”(见d)增加了接口数据摘要SOF_HashData”(见7.1.31、7.2.37、7.3.38)文件摘要SOF_HashFile”e)删除了接日“SOFEnerypiBile”(见2012年版的7123)“SOEDeeyptFie”(见2012年版的f)增加了“客户端JavaScup脚不接口”(见7.4)请注意本文件的某些内容可能涉及专利本文件由密码行业标准化技小委员会提件的发布机构不底理识别考利的责任。公、格尔软件股份有限公司北京海泰方圆科技股份有限公司、上海市数字证书认证中定有跟公司、无锡江南信息妥全工程投水市之中电科网络要全科技股份有限公司长春吉大正元信息技术股份有限公司兴唐通信型接有限公河市东得安信息版术有限公本文件及其所代替文件的历次版本发布情况为：——2012年首次发布版为GM/T0020—2012;——本次是第一次修订。1证书应用综合服务接口规范1范围本文件规定了面向证书应用的综合服务接口。本文件适用于公钥密码应用技术体系下密码应用服务产品的开发，密码应用支撑平台的研制及检测，也可用于指导直接使用密码设备和密码服务的应用系统的集成和开发。2规范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本(包括所有的修改单)适用于本文件。GB/T25061-2020信息安全技术XME数学签名语法与处理规范GM/T0006密码应用标识规范GM/T0009SM2密码算法使用规范GM/T0010SM2密码算法加密签名消息德法规范GM/T0015基于SM2密码算法的数家GM/T0019通用密码服务接口规范GM/Z4001密码术语PKCs#IRSA加密标准CRSACyptograplsStandard)PKCS#加密消息语法标准CGypiogepuicMessageSynueStantardIETFRFC3275(可扩展标记语言)XMH.签名语法和处理(ExiensibleMarkapLanguage)XML-3术语和定义GM/Z4001界定的以及下列术语和定义适用于本文件存储在设备内部的用于应用密码运算的非对称密钥对。容器container密码设备中用于保存密钥所划分的唯一性存储空间。4缩略语下列缩略语适用于本文件。2内的位置参见GM/T0094—2020的第4章。3说明字符串类型，不同的开发语言应采取对应的类型定义，如：char*、CString、java.lan16位整数布尔类型，其取值范围是TRUE和FALSE,其中TRUE表示真值，F空串长度等于0的字符串长度大于0的字符串章条号1获取接口的版本号24章条号34567导出用户签名证书89导出用户加密证书获得证书信息获得证书扩展信息获得设备信息数据签名验证数据签名文件签名验证文件签名消息签名验证消息签名SOF_GetInfoFromSign解析消息签名XML数字签名验证XML数字签名获取最新的错误信息摘要数据签名验证摘要值签名证书登出证书登录状态检测567返回值：证书信息空串失败或证B中不存在该项内容BSTRSOF_GeiCertlntoByOid(返回值：证书扩展信息空串失败政证书中不存在该私有扩展项验证失败，失败原因应符合附录A中表A.1中的错误代码范围其他87.1.17数据签名SOF_SignDataInData签名返回值：签名值成功，返回Base64编码的签名结果7.1.18验证数据签名SOF_VerifySignedData参数：Base64CertInData签名SignValueBase64编码的签名值7.1.19文件签名SOF_SignFileInFile原文文件全路径(包含路径十文件名)7.1.20验证文件签名SOF_VerifySignedFile参数：Base64CertBase64编码的签名者证书InFile原文文件全路径(包含路径十文件名)SignValueBase64编码的签名值9数字信封加密，加密过程为使用临时产生的对称密钥加密数据，然后使用数字证书的公钥描述：加密对称密钥，返回Base64编码格式的数据类型B密文数据。InData待加返回值：密文数据成功，返回Base64编码的密文7.1.22数据解密SOP_DecryptData描述：使用证书对应的私钥解密数字信封，密文数据格式为Base64编码的数据类型B。InData香解密的Bse64编码的密文数据返回值：明文数据成功返画解密后的明文描述：对字符串数据进行消息签名，返回B高e64编码的数据类型B签名结果。b)0表示Attached,即带原文CertID证书唯一标识7.1.25解析消息签名SOF_GetInfoFromSignedMessage码的数据类型B。c)3解析出Base64编码空串失败或不存在该项7.1.26XML数据签名SOF_SignDataXML对XML数据进行数字签名，证书为RSA算法时签名结果符合RFC3275,证书为SM2算法InDataXML格式的签名原文7.1.27验证XML数字签名SOF_VerifySignedDataXML7.1.28解析XML签名数据SOF_GetXMLSignatureInfo7.1.29产生随机数SOF_GenRandom参数：RandomLen7.1.30获取最新的错误信息SOF_GetLastError7.1.31计算数据摘要SOF_HashDataIndata原始数据返回值：摘要值7.1.32计算文件摘要SOF_HashFileInFile文件全路径(包含路径+文件名)7.1.33摘要数据签名SOF_SignHashDataBase64HashDataBase64编码的摘要值7.1.34数据摘要签名验证SOF_VerifySignedHashDataBOOLSOF_VerifySignedHashData(BSTRBase64Cert,SignValueBase64编码的签名值描述：判断证书用户是否为登录状态。7.2服务器端COM组件接口签名与验证、时间戳等功能，共包含39个接口。表3列出了服务器端COM组件接口列表，7.2.2~章条号12查询证书信任列表别名3456789获得服务器证书获得证书信息章条号获得证书扩展信息数据签名验证数据签名文件签名验证文件签名消息签名验证消息签名不带原文的消息签名SOF_VerifySignedMess验证不带原文的消息签名SOF_GetInfoFromSign解析消息签名XML数字签名验证XML数字签名摘要数据签名LONGSOF_SetCertTrustList(BSTRCTLAltName,BSTRCTLContent,LONGCTL-其他证书信任列表长度成功失败，返回表A.1定义的错误代码7.2.3查询证书信任列表别名SOF_GetCertTrustListAltN描述：查询证书信任列表别名。参数：无返回值：信任列表别名空串成功，返回信任列表别名的字符串组合，如“CA001@CA002@CA003”失败，可通过SOF_GetLastError获取符合表A.1定义的错误代码7.2.4查询证书信任列表SOFGetCertTrustList描述：根据别名查询证书信任列表。参数：cTLAltName证书信任列表别名返回值：信任列表成功，返国Ba61编码的正信作列表7.2.5删除证书信任列表SOTDeICertTrus描述：根据别名删除证书信任列表参数：CTLAltName证手信任列表别名返回值：SAR_OK成功其他失败，返回表八上定义的错误代码原型：LONGSOFInitCe根据应用策略名称设置应用符合的证书应用策略。该名称要和服务器配置文件对应。接描述：口从配置文件中读取应用策略信息，宜包括使用的密钥和证书、信任的根证书、证书验证的策略、验证方式。配置内容自行定义。参数：PolicyName其他失败，返回表A.1定义的错误代码描述：设置COM组件签名运算使用的签名算法。其他失败，返回表A.1定义的错误代码参数：无7.2.13获得证书信息SOF_GetCertInfo原型：BSTRSOF_GetCertIn描述：根据指定类型，获取证书内的相关信息。参数：Base64CertType证书解析标识，应符合GM/T0006返回值：证书信息成功，返回证书内指定类型的信息空串失败或证书中不存在该项内容7.2.14获得证书扩展信息SOF_GetCertfnfoByOid参数：Base64CertBase64编码的证书返回值：证书扩展信息成功，返回证书私有扩展项OID对应的信息空事头败或证书中玉存在该私有扩展项7.2.15验证证书有效性SOFValdateCet描述：根据应用的策略根据验证证书有参数：Base64Cert待验间的B验证成功验证天败，实败原因癌符合表入的的雷误代码范围0X0B000500~7.2.16数据签名SOF_SignData描述：对字符串数据进行数字签名，返回Base64编码的数据类型A签名结果。参数：InData待签名的数据原文返回值：签名值成功，返回Base64编码的签名值空串失败，可通过SOF_GetLastError获取符合表A.1定义的错误代码7.2.17验证数据签名SOF_VerifySignedData数字信封加密，加密过程为使用临时产生的对称密钥加密数据，然后使用数字证书的公钥描述：加密对称密钥，返回Base64编码的数据类型B密文数据。空串返回值：消息签名值7.2.27验证不带原文的消息签名SOF_VerifySignedMessageDetachSignedMessageBase64编码的签名值7.2.28解析消息签名SOF_GetInfoFromSignedMessage码的数据类型B。b)2解析出Base64编码的签名者证书；返回值：解析结果时签名结果符合GB/T25061。描述：创建时间戳请求。空串返回值：摘要值7.2.38计算文件摘要SOF_HashFiInFile原文文件全路径(包含路径十文件名)返回值：摘要值成功、返回Base64编码的数据摘要值返回值：签名值Base64编码的签名值7.2.40数据摘要签名验证SOF_VerifySignedHashDataSignValue,LONGHash0009规定的预处理过程计算。章条号12SOF_getCertTrustLis查询证书信任列表别名345获取指定应用的实例6789获得服务器证书SOF_getServerCertifica获得指定密钥用途的服务器证书获得证书信息获得证书扩展信息数据签名验证数据签名文件签名验证文件签名表4服务器端Java组件接口列表(续)章条号消息签名验证消息签名SOF_getInfoFromSign解析消息签名不带原文的消息签名SOF_verifySignedMess验证不带原文的消息签名XML.数字答名验证XM,数字签名摘要数据签名7.3.2设置证书信任列表SOFsetCertTrustListjava.lang.StringctlContent)描述：设置证书信任列表。ctlContentBase64编码格式的证false失败，可通过SOF_getLastError获取符合表A.1定义的错误代码7.3.3查询证书信任列表别名SOF_getCertTrustListAltNames描述：查询证书信任列表别名。返回值：信任列表别名成功，返回信任列表别名的字符串组合，如“CA001@CA002@CA003”失败，可通过SOF_getLastError获取符合表A.1定义的错误代码返回值：无描述：设置组件对数据加密使用的对称算法标识。返回值：无7.3.10获得加密算法SOF_ge返回值：加密算法标识成功，返回接口当前使用的加密算法标识07.3.11获得服务器证书SOF_getServerCertificate7.3.12获得指定密钥用途的服务器证书SOF_getServerCertificateByUsage7.3.13产生随机数SOF_genRandom参数：randomLen7.3.14获得证书信息SOF_getCertInfo原型：java.lang.StringSOF_getCertInfo(java.lan返回值：证书信息空串证书解析标识，应符合GM/T0006成功，返回证书内指定类型的信息失败或证书中不存在该项内容7.3.15获得证书扩展信息SOF_getCertInfoByOid原型：java.lang.StringSOF_getCertInfoByOid(javjava.lang.Stringoid)描述：根据OID获取证书私有扩展项信息。返回值：证书扩展信息空串成功，返回证书私有扩展项OID对应的信息失败或证书中不存在该私有扩展项7.3.16验证证书有效性SOF_valid描述：根据应用的策略验证证事有效性。验证头败，失以因应行合表A.1中的借误代码范围0xOB000500~7.3.17数据签名SOF_sigiDa描述：对字符串数据进行数字签名，返回Base64编码的数据类型A签名结果。参数：inData待签名的数据原文返回值：签名值成功，返回Base64编码的签名值空串失败，可通过SOF_getLastError获取符合表A.1定义的错误代码7.3.18验证数据签名SOF_verifyStgnedDatajava.lang.StringsignValue)描述：验证数字签名，签名值格式为Base64编码的数据类型A。参数：base64CertBase64编码的签名证书inData待验证的原文signValueBase64编码的签名值false失败，可通过SOF_getLastError获取符合表A.1定义的错误代码7.3.19文件签名SOF_signFile原型：java.lang.StringSOF_signFile(java描述：对文件数字签名，返回Base64编码的数据类型A签名结果。返回值：签名值成功，返回Base647.3.20验证文件签名SOF_verifySignedFilejava.lang.StringinFile,ava.lang.StringsignValsignValueBase64编码的签名值7.3.21数据加密SOF_encryptData原型：java.lang.String数字信封加密，加密过程为使用临时产生的对称密钥加密数据，然后使用数字证书的公钥加密对称密钥，返回Base64编码的数据类型B的密文数据。书之间用&&&作为分隔符连接返回值：密文数据成功，返回Base64编码格式的密文数据7.3.22数据解密SOF_decryptDatainDataBase64编码的待解密的密文数据7.3.23文件加密SOF_encryptFilejava.lang.StringinFile,java.lang.StringoutFile)描述：加密文件，得到数据类型B的密文文件。Base64编码的数据接收者的加密证书，如有多个接收者，多个接收者证inFile待加密的明文文件全路径outFile密文文件保存全路径false失败，可通过SOF_getLastError获取符合表A.1定义的错误代码7.3.24文件解密SOF_decryptFilejava.lang.StringinFile,java.lang.StringoutFile)描述：解密密文文件，密文文件格式为数据类型B。参数：ceftId解密密钥对应的证书唯一标识，如不需要可传空电jfFile待解整的密文文件路径outFle明义文件保存略径返回值：true成功描述：对字符串数据进行消息签名、返回Bas4编玛的带原文的数据类型B签名结果。参数：:inData待签名的数据原文返回值：消息签名值成功，返回Base64编码的数据类型B空串失败，可通过SOF_getLastError获取符合表A.1定义的错误代码7.3.26验证消息签名SOF_verifySignedMessage原型：booleanSOF_verifySignedMes描述：验证消息签名，签名格式为Base64编码的带原文的数据类型B。false失败，可通过SOF_getLastError获取符合表A.1定义的错误代码7.3.27解析消息签名SOF_getInfoFromSignedMessage原型：byte[]SOF_getInfoFrom描述：解析Base64编码的带原文的数据类型B签名值的信息，可获得原文、签名值、签名证书等信息。返回值：解析结果空串Base64编码的签名值c)3解析出签名值7.3.28不带原文的消息签名SOF_signM返回值：消息签名值空串7.3.29验证不带原文的消息签名SOF_ver描述：验证签名格式为Base64编码的不带原文数据类型B的数字签名。Base64编码的签名值7.3.30XML数字签名SOF_signDataXML原型：java.lang.StringSOF_signDataXML(java.lang.StringinData)对XML数据进行数字签名，证书为RSA算法时签名结果符合RFC3275,时签名结果符合GB/T25061。参数：空串7.3.31验证XML数字签名SOF_verifySignedDataXMLjava.lang.StringxmlSignedData,shorttype)d)4解析出签名证书；原型：java.lang.StrireqType请求的时间戳服a)0表示时间戳响应应包含时间戳服务器证书b)1表示时间戳响应不包含时间戳服务器证书extension扩展项返回值：时间戳请求成功，返回Base64编码格式的时间booleanSOF_verifyTimebyte[]inData,byte[]signCert,byte[]use返回值：摘要值java.lang.StringinFile,byte[]signCert,byte[]userID)返回值：签名值Base64编码的签名值java.lang.StringsignValue,longhashAlg)章条号1获取接口的版本号234567导出用户签名证书89导出用户加密证书获得证书基本信息获得证书扩展信息获得设备详细信息数据签名验证数据签名表5客户端JavaScript脚本接口列表(续)章条号消息签名验证消息签名SOF_GetInfoFromSign解析消息签名XML数字签名验证XML数字签名SOFGenRandom获取最新的错误信息摘要数据签名8O⁶go面证书登出SOE班可g远ctx阿通函数所需参7.4.3设置签名算法SOF_SetSignMethod描述：设置接口在签名和验签运算时使用的签名算法。返回值：签名算法标识成功，返回接口当前使用的签名算法标识007.4.7获得证书用户列表SOF_GetUserList失败或当前不存在证书用户列表，可通过SOF_GetLastError获取符合表A.1定义的错误代码cb调函数返回值剩余口令重试次数，当重试次数或等于表示证书日令已被锁定描述：修改证书口令7.4.13获得证书基本信息SOF_GetCertInfo参数：Base64Cert参数：Base64Cert返回值：证书扩展信息成功，返回证书私有扩展项OID7.4.15获得设备详细信息SOF_GetDeviceIn验证失败，失败原因应符合附录A中表A.1中的错误代码范围7.4.17数据签名SOF_SignDataInData7.4.18验证数据签名SOF_VerifySignedDataInDataSignValueBase64编码的签名值cb回调函数返回值：密文数据书之间用&&.&作为分隔符连接7.4.20数据解密SOF_DecryptDataIndata待解密的Base64编码格式的密文数据7.4.21消息签名SOF_SignMessageb)0,表示Attached,即带原文7.4.22验证消息签名SOF_VerifySignedMessage描述：验证消息签名，签名值的格式为Base64编码的数据类型B。7.4.23解析消息签名SOF_GetInfoFromSignedMessage返回值：解析结果空串b)2解析出Base64编码的签名者证书；c)3解析出Base64编码的签名值对XML数据进行数字签名，证书为RSA算法时签名结果符合RFC3275,证书为SM2算法描述：时签名结果符合GB/T25061。InXMLData待签名的XML数据7.4.25验证XML数字签名SOF_VerifySignedDataXML7.4.26解析XML签名数据SOF_GetXMLSignatureInfoa)1解析出XML原文；b)2解析出摘要值；c)3解析出签名值；d)4解析出签名证书；e)5解析出摘要算法；f)6解析出签名算法7.4.27产生随机数SOF_GenRandom描述：产生指定长度的随机数。cb返回值：随机数成功，返回Base64编码的随机数值返回值：错误代码，应符合表A.1错误7.4.29计算数据摘要SOF_HashDataSignCert和UsreID值不为空时，应按照GM/T0009规定的预处理过程计算，摘要值可以作为SM2签名的输入。返回值：摘要值原始数据Base64编码的签名者证书，摘要算法为SM3时有效，如不需要传空串签名者用户ID,摘要算法为SM3时有效，如果SignCert参数为空，则本参数无意义回调函数回调函数所需参数失败，可通过SOF_GetLastError状取符合表A.1定义的错误代码7.4.30摘要数据签名SOF_SignHashData对数据摘要签名，返回Basc64编码的数据类型A签名结果。Base64HashBaaBasecb回周函数ctx向调的数所需参数返回值：签名值成、返回Base61编码的数据水型7.4.31数据摘要签名验证SOF_VerifySignedHaBase64Cert,Base64HashData,SignValue,HashAlg,cb,etx)规定的预处理过程计算。参数：Base64CertBase64编码签名者证书Base64HashDataBase64编码摘要值SignValueBase64编码的签名值cb回调函数ctx