GM-T 0019-2023 通.用密码服务接口规范

代替GM/T0019—2012通用密码服务接口规范国家密码管理局发布IGM/T0019—2023 Ⅲ 12规范性引用文件 1 1 1 25.1算法标识与常量定义 25.2密码服务接口数据结构定义 2 36.1通用密码服务接口在公钥密码基础设施应用技术体系框架中的位置 36.2密码服务接口组成和功能说明 3 47.1环境类函数 47.2证书类函数 77.3密码运算类函数 7.4消息类函数 8验证方法 538.1验证环境 8.2密码服务环境操作验证 538.3证书类函数功能验证 8.4签名验签验证 8.5摘要计算验证 8.6非对称加解密验证 8.7对称加解密验证 8.8生成密钥对验证 8.9PKCS#7运算验证 8.10SM2消息类运算验证 65 附录A(规范性)SM9密码算法应用接口 附录B(规范性)密码服务接口错误代码定义 Ⅲ起草。h)删除了“SAR_CertRev请注意本文件的某些内容可能涉及专利。本文本本文件由密码行业标准化技术委员会提出并归口。——2012年首次发布为GM/T0019-2012;—本次为第一次修订。1GB/T25069信息安全技术术语2DN:可识别名(DistinguishedName)LDAP:轻量级目录访问协议(LightweightDirectoryOCSP:在线证书状态协议(OnlineCertificateStatusOID:对象标识符(ObjectIdentifier)PKCS:公钥密码标准(thePublic-KeyCryptography5算法标识和数据结构5.1算法标识与常量定义本文件所使用常量定义、各类算法标识和证书解析标识的具体定义应符合GM/T0006的规定。5.2密码服务接口数据结构定义和说明数据常量标便的定义见表1。常量名25证书果项信息的学符串长度最大值用户书列表见表2。表2用注证书列表实际数据结构定义：typedefstructSGD_USR_CERT_ENUMLIST_{intcertificateLen[SGD_char*containerName[SGD_MAX_COUNT];intcontainerNameLen[SGD_MAX_COUNT];3密钥类型，1:SM2;2:RSA1024;3:RSA2048;4:RSA3072;5:RSA4096;6:SM9(SM9密码算法定义应符合附录A)typedefstructSGD_KEYCONTAINERINFO_ENUMLIST_(unsignedchar*conunsignedintcontainerNameLen[SGD_MAunsignedintkeyUsage[SGD_unsignedintkeyType[SGD_MAX_COUN4户登录函数(SAF_Login)创建应用接口可柄。当不再调用密码服务函数时，应调用注销登录函数证书类函数设置各类数字证书到应用接口会诉环境中，验证用户证书稚获取数字证书或CRL,提问控制安全机制。本文件沙及的数字证求应符会M/T001用程序，是应用槛序实现数据保需性完件和不可抵赖性安RSA算法时符合PKCS#7,使用国密算法时符合GM/T0010消息类函数提供了数据编解码、签名数据编解码、数字信封编解PKCS=7(RSA算法)或GM/T0010(SM2算法)、签名数据编解码格式应符合PKCS≠7(RSA算法)或GM/T0010(SM2算法)和PKCS#7(RSA算法),数字信封编解码格式应符合GM/T0010(SM2算50成功0成功6unsignedintuiContain为1时表示用户登录0unsignedchar*pucContaiunsignedintuiContain7返回值：0非08n)通过LDAP方式获取证书对应的CRL:SAF_unsignedchar*pucCertifica0907.2.4获取根CA证书puiCertificateLen[in,00unsignedintuiIndex);.应用接口句柄DER编码的证书证书长度CA证书索引0成功备注：本函数仅限于管理员使用。描述：unsignedint--puiCount)获取信任CA证事的个数0应拥接限句柄功误代码失败，返误代码yoidhAppHandlc,unsignedint*puiGertificateLen);获取指定位置CA证书。应用接口句柄CA证书索引DER编码的证书puiCertificateLen[in,o证书长度0成功07.2.10添加CRL0unsignedintuiUsrCertificuiUsrCertificateLen成功失败，返回错误代码，应符合附录B中的错误代码定义7.2.12根据CRL文件获取用户注销状态unsignedintuiUsrCertificateLenunsignedintuiDerCrlLen,unsignedchar*pucRev应用接口句柄DER编码的证书非败，返团的错误代码应符合附录B中的错候代码定义7.2.13根据OCSP获取证书状态unaignedcharpucOcspHostURL,unsignedinturOsspHostURLLen,unsignedchar*pucUsrCeunsignedintuiUsrGertificateLen,unsignedintuiCACertificateLen,应用接口句柄ocsp服务的URLDER编码证书uiUsrCertificateLen证书长度0非0unsignedintuiLdapHostURLL0非0unsignedchar*pucCertificaunsignedchar*pucCURL长度CRL文件长度0pucInfo[out]0pucInfo[out]00SGD_KEYCONTAINERINFO_ENUMLIST*keyContainerInfo0SGD_KEYCONTAINERINFO_ENUMLIST0描述：对输入的数据进行base64编码，编码格式符合IETFRFC4648。pucInData[in]编码前的数据uiInDataLen[in]编码前的数据长度pucOutData[out]编码后的数据puiOutDataLen[in,out]编码后的数据长度7.3.3单块base64解码unstgnedintuiInDataLen,unsignedint描述：对输入的数据进行bapucIrData[in前的数据uilaDataLen[i解码前的数据长度pucOutData[o码后数据描述：为任意长度数据的base64编解码创建base64对象，编码格武符合ETFRFC4648。phBase64Obj[out]指向创建的basc64对象句柄的指针备注：本函数与SAF_Basc64_DestroyBase64Obj,SAF_Base64_EncodeUpdatc,SGD_BaSAF_Base64_DecodeFinal函数共同使用以支持任意长度数据的base64编解码。删除basc64对象。0unsignedintuiInDataLen,unsignedint*puiOutDaunsignedint*puiOutDa0unsigncdcharxpuclnunsignedintuiInDamaLen,通过base64对象对数据多块base64解码，编码格式uilnDataLen[i是07.3.9通过base64对象解码结束unsignedint*puiOuD00unsignedint*puiOutDapucID[in]0unsignedchar*pucPublicKpucID[in]创建的HASH对象0hHashObj[in]待删除unsignedintuilnDataLen);0unsignedint*puiOutDa0unsignedintuiContainunsignedintuiExportFlag);unsignedchar*pucContaunsignedchar*pucPublicKpuiPublicKeyLen[in,o0unsignedintuiContainunsignedintuiHashAlgorithmID,unsignedchar*pucInDunsignedchar*pucSignDunsignedint*puiSignDHASH算法pucSignData[out]输出签名结果数据puiSignDataLen[in,out]输出的签名结果数据长度unsignedintuiContainunsignedintuiHashAlunsignedchar*pucSignDHASH算法输出的DER格式的签名结果数据puiSignDataLen[in,o0unsignedintuiHashAlDER编码的公钥00unsignedintuiHashAlgunsignedchar*pucS0unsignedintuiHashAlgunsignedchar*punsignedchar*pucSuiHashAlgorithmID[in]HASH算法标识0unsignedinauiExportFlag[in]1表示生成的密钥对可导出0表示不可导出成功unsignedchar*pucContainerName,puiPublicKeyLen[in,o0unsignedintuiContainunsigncdchar*pucSpuiSignDataLen[in,o输出的DER编码的签名数据0pucSignData[in]DER编码的签名数据unsignedchar*pucPublicKunsignedint*puiOutDa0unsignedchar*pucCertifica0非0SM2算法标识输出DER编码的数据7.3.29基于证书的SM2解密unsignedintuiAlgorunsignedintuiInDataLen,证书标识参数的具体含义，取值应符合GM/T0016中SM2算法标识puiOutDataLen[in,out]输出数据长度00密钥的容器名密钥的容器名长度pucIV[in]初始向量，ECB模式时此参数忽略初始向量长度，ECB模式时此参数忽略0解密uiCryptoAlgID[in加密算法标识07.3.32生成会话密钥并用外部公钥加密输出ynsigneddarpucl描述：生成会话密钥瓶用组部公钥加需输出。参数：对称算法对象输人的DER编码的公钥数据输入公钥数据的长度输出的加密后的会话密钥输出的加密会话密钥长度phKeyHandlelout]输出会话密钥的句柄0成功7.3.33导入加密的会话密钥0unsignedintuiSponsorunsignedchar*pucSponsorPublicunsignedint*puiunsignedint*puiSponsorTmpPublicKeyLen,void**phAgreementHanuiSponsorIDLength[in]puiSponsorPublicKeyLen[pucSponsorTmpPublicKey[out]unsignedchar*pucReunsignedintuiResponseIDLength,unsignedintuiResponsePublunsignedcharunsignedintuiResponseTmpPubvoid**phKeyHandle描述：使用SM2密钥协商算法，使用自身协商句柄和响应方的协商参数计算会话密钥，同时返回会证密钥句柄参数：uiRsponseIDLemphm密钥协商句柄外部输入的响应方值外部输人的响应方ID长度uikesponsePubhaKeEen[外部输人的响应务SM2公钥长度外部输人的响应方临时SM2公钥uiResponseTnpPablokey外部榆人的响应方临时SM2公钥长度返回的密钥何柄返回值：0备注：协商的发起方获得响应方的协商参数后调用本函数，计算会话密钥，会话密钥的计算过程应符合GM/I0009。7.3.36产生协商数据并计算会话密钥intuiSponsorPublicKeyLen,unsignedintuiSponsorTmpPubunsignedint*puvoid**phKeyHanuiResponseIDLength[pucSponsorID[in]pucSponsorPublicKey[ipucSponsorPublicKeyLen[uiSponsorTmpPublicKey[uiSponsorTmpPublicKeyLenpucResponsePublicKey[opuiResponsePublicKeyLen[in,opucResponseTmpPublicKey[opuiResponseTmpPublicKeyLen[in,响应方ID长度0000unsignedint*puiOutDa000非0unsignedint*puiOutDa00原型描述0unsignedint*puiOutDa0unsignedintpuilnDataLen);000输出的MACunsignedintuiSignContainunsignedintuiSignerCertunsignedintuiDigestAunsignedintuiEncCertunsignedint*puiDerP7pucSignContaincrNamc[uiSignContainerNameLenpucSignerCertificate[uiSignerCertificateLenuiDigestAlgorithms[uiEncCertificateLenpuiDerP7DataLen[in,oHASH算法07.4.3解码PKCS#7格式的带签名的数字信封数据unsignedintuiDecContainunsignedintuiDecKeyUsagc,unsignedint*puiSignpucDecContainerName[uiDecContainerNameLenpucSignerCertificate[opuiSigncrCertificateLenpuiDigestAlgorithms[opuiSignedDataLen[in,ounsignedintuiSignContainunsignedintuiSignerCertunsignedintuiDigestAunsignedchar*pucDerpucSignContainerName[uiSignContainerNameLenpucSignerCertificate[uiSignerCertificateLenuiDigestAlgorithms[pucDerP7SigncdData[o带签名值的P7数据puiDerP7SignedDataLen[in,o07.4.5解码PKCS#7格式的签名数据un6gnedchartponcDehsignedchapunSprcrCcratc,nsignedinepunsigncdintpuDigestAlgms,pucDerP⁷SignedData[in]pucSignerCertificatepuiSignerCertificateLen[in,puiDigestAlgorithms[oHASH算法00unsignedintuiEncCertunsignedchar*pucDerP7EnvelopedData,uiEncCertificateLenpucDerP7EnvelopedData[opuiDerP7EnvelopedDataLen[in,unsignedchar*pucDecContainerNaunsignedintuiDecContaiunsignedchar*pucDerP7EnvelopedDaunsignedintuiDerP7EnvelopuiDecContainerNameLen解密用私钥的容器名长度解密用私钥的用途pucDerP7EnvelopedData[数字信封数据uiDerP7EnvelopedDataLen数字信封数据长度解码后得到的数据原文解码后得到的数据原文数据长度7.4.8编码PKCS#7格式的摘要数据unsignedintuiDigestAlgorithm,unsignedchapucDcP7DigestodDatg描述：使用指定的杂读算法评算原文白，并打们波符合PKCS7摘要数据格式的数据包。应用接句柄杂凑算法标原文叛居原文数据长度符合PKCS#7摘要数据格式的数据包puiDerP7DigestedDataLen[in,out]符合PKCS#7摘要数据格式的数据包长度7.4.9解码PKCS#7格式的摘要数据intuiDigestAlgorithm,intpuiDerP7DigestedDataLen,charpucDigest,pucDerP7DigestedData[puiDerP7DigestedDataLen[0unsignedintuiSignContainunsignedintuiSignerCertunsignedintuiDigestAunsignedintuiEncCertunsignedchar*pucDerSignedAndEnvelopedDatunsignedint*puiDerSpucSignContainer.Name[uiSignContainerNameLenpucSignerCertificate[uiSignerCertificatcLeuiDigestAlgorithms[uiEncCertificateLenpuiDerSignedAndEnvelopedDataLen[in,0unsignedchar*pucDecContaiunsignedintuiDecContainerNameLen,unsignedintuiDecKeyUsage,unsignedchar*pucDerSignedAndEnunsignedintuiDerSignedAndEnvelopedDataLen,unsignedint*puiDipucDecContainerName[uiDecContainerNameLenpucDerSignedAndEnvelopedData[uiDerSignedAndEnvelopedDataLenDER编码后的SignedAndEnvelopedDatapucSignerCertificate[opuiSignerCertificateLen[in,puiDigestAlgorithms[o0非0unsignedchar*pucSignContaiunsignedintuiSignContaiunsignedchar*pucSignerCertifunsignedintuiSignerCertunsignedintuiDigestAunsignedchar*pucDepucSignContainerName[uiSignContainerNameLenpucSignerCertificate[uiSignerCertificateLeuiDigestAlgorithms[0intSAF_SM2_DecodeSunsignedintuiDerSignunsignedint*puiDigestApucSignerCertificate[opuiSignerCertificateLen[in,puiDigestAlgorithms[o0unsignedintuiEncCertunsignedintuiSymmAlgoriunsignedint*puiDerEnvuiEncCertificateLenpucDerEnvelopedData[oDER编码后的EnvelopedData数字信封数据，puiDerEnvelopedDataLen[in,0非0unsignedintuiDecContainerunsignedintuiDerEnvelopedpucDecContainerName[uiDecContainerNameLenpucDerEnvelopedData[uiDerEnvelopedDataLen非07.4.16解析PKCS#7格式的签名数据unsignedchar*pucDerP7SunsignedintuiDerP7SignedDataLen,unsignedint*puiIn描述：解码基于SM2算法的数字信封数据。nType[in]解析类型：1:版本号3:签名原文5签各值pucInfo[out]非0解机出来的信息长度城功买败，返和借识代码8验证方法接口提供方实现本文件所规定的接口，提供测试程序和测试程序源代码。接口需求方可选择使用接口提供方提供的测试程序验证接口，也可以白编写测试程序来验证接口。验证接口，应具备以下验证环境：a)运行接口服务所需的操作系统及测试程序软件；b)支持密码设备应用接口调用的密码设备；c)支持存储证书和密钥的存储介质(如智能密码钥匙)。8.2密码服务环境操作验证8.2.1密码服务空间验证验证目的：验证通过密码服务接口是否正确创建，使用，清除密码服务空间操作。a)添加CA根证书：步骤1:调用SAF_GectRootCaCertificateCount获取CA根证书的个数m;步骤2:调用SAF_AddTrustedRootCaCertificatc添加CA根证书rootCAl;步骤3:调用SAF_GctRootCaCcrtificateCount获取CA根证书的个数n;步骤4:输入索引n-1,调用SAF_GctRootCaCertificateCount获取CA根证书rootCA2;b)删除CA根证书：步骤1:执行验证过程a);步骤2:调用SAF_RemoveRootCaCertificate删除指定CA根证书；步骤3:调用SAF_GetRootCaCcrtificateCount获取CA根证书的个数n1;步骤4:输入位置索引m-1,调用SAF_GetRootCaCertificateCount获取已删除的CA根a)正常情况验证n=m+1日能够得到与设置相同的CA根证书(rootCA1=rootCA2b)异常情况验证：=n且sATGetRootCaCcruficateCount返步骤3:调州SAF_GetCaCertificateCount获取CA证书的个数p步骤1输入索引n-1,调用SAF_GetCaCertificatc获取CA根证书b)删除CA证书：步骤1:执行验证过程a步骤2:调用SAF_RemoveCaCertificate删除指定CA证书；步骤3:调用SAF_GetCaCcrificateCount获取CA证书的个数n1;步骤4:输入位置索引n1-1,调用SAF_GetCaCertificate获取已删除的CA证书。n=m+1且能够得到与设置相同的CA证书(CA1=CA2);nl=m且SAF_GetCaCertificateCount验证目的验证通过密码服务接口是否正确添加CRL、验证用户证书、根据CRL文件获取用户注销状步骤1:调用SAF_AddCrl添加CRL;步骤3:使用步骤2的原文和签名结果、列举证书时取到的签名证书，调用SA步骤4:使用步骤2的原文和签名结果、步骤3得到的签名公钥，调用SAF步骤1:使用预置的SM2签名证书、原文和签名值，调用SAF_Sm2Ver步骤3:使用步骤2的原文和签名结果、列举证书时取到的签名证书，调用SAF通过标准：a)正常情况验证：使用预定私钥对加密密文进行解密，得到结果与预定原文相同；加密数据格式应符合符合GM/T0009中加密数据格式的定义；b)异常情况验证：得到预期结果。8.6.2基于证书的SM2公钥加密验证目的：验证是否能正确采用外部证书的SM2公钥对输人数据进行加密，并输出加密结果。验证条件：完成环境初始化，使用预定SM2私钥申请证书。验证过程：a)正常情况验证：使用预定容器内调用SAF_Sm2PublicKeyEncByCert接口，对预定原文进行加密，返回加密结果b)异常情况验证使用非法参数调用不接日应返回错误码。通过标准：a)正常情况验证使用预定私钏对加密密文进行得到结单预定原支相同。加密数据格式应符合符合GM/T000911用密数据格式的道义；b)异常情况验证：得到预期结果。8.6.3基于证书的SM2解密验证目的：验证是否能正确来用容器内证书标识对应私钥进行解密，并输出原交。验证条件：完成环境初始化，证书标识对应私钥已存在。验证过程：a)正常情况验证：使用预定容器内调用SAF_Sm2PublicKeyDecByCert接口，对预定密文进行解密，返回明文数据；b)异常情况验证：使用非法参数调用本接口，应返回错误码；解密密钥不存在，应返回错误码。通过标准：a)正常情况验证：返回的明文数据与预定明文一致；b)异常情况验证：得到预期结果。步骤1和步骤2返回的加密密文与预定密文一致。步骤1和步骤2中设置初始化环境函数SAF_Initializc、用户登录函数SAF_Login、创建对称算法对象SAF_Crcatc-步骤1:调用SAF_SymmEncryptUpdate接口，对多个预定明文数据分组进行加b)异常情况验证：不执行步骤1,直接执行步骤2应返回错误码。a)正常情况验证pyiOutDataLen返回结果数据实际长度；b)鼻常情况验证得到预期结果验证是否能正确进行多块数据解密验证过程：b)异常情况验证使用非法参数调用上述接口，应返回错误码；不执行步骤1,直接执行步骤2应返回错步骤1和步骤2返回的解密明文与预定明文一致，步骤1和步骤2中设置pucOutData=验证是否能正确生成符合规范的SM2密钥对。格式的带签名的数字信b)异常情况验证：验证是否能正确进行SM2算法的带签名的数字信封编码运算。调用SAF_SM2_EncodeSigncdAndEnvelopedData接口，对预定数据进行SM2的带签名b)异常情况验证：b)异常情况验证：验证是否能正确进行基于SM2算法的带签名的数字信封解码运算。调用SAF_SM2_DecodeSignedAndEnvelopedData接口，对预定数据进行进行基于SM2b)异常情况验证：验证是否能正确创建Base对象。调用SAF_Base64_CreateBase64Obj接口，为任意长度数据的Base64编解b)异常情况验证：b)异常情况验证：8.11.3Base64解码(规范性)SM9主私钥数据结构符合表A.1。表A.1SM9主私钥数据结构4s主私钥#defineSM9ref_MAX_BITS#defineSM9ref_MAX_LENtypedefstructSM9refMasterPrivateKey_st{表A.2SM9签名主公钥数据结构4曲线上点X坐标高维曲线上点X坐标低维曲线上点Y坐标高维曲线上点Y坐标低维C语言的数据结构定义：typedefstructSM9refSignMasterPublicKey_st{ULONGbits;BYTExa[SM9ref_MAX_LEN];A.1.3SM9加密主公钥数据结构SM9加密主公钥数据结构符合表A.3。表A.3SM9加密主公钥数据结构4XSM9ref_MAX_LEN曲线上点X坐标y曲线下点Y坐协C语言的数据结构定义：typedefsructSM9reEncMastcPablicKeyst{SM9用户签名私钥数据结构符合表A4管义4Xy曲线上点Y坐标C语言的数据结构定义：typedefstructSM9refSignUserPrivateKey_st{BYTEy[SM9ref_MAX_LEN];A.1.5SM9用户加密私钥数据结构SM9用户加密私钥数据结构符合表A.5。4曲线上点X坐标高维曲线上点X坐标低维曲线上点Y坐标高维曲线上点Y坐标低维typedefstructSM9refEncUserPriva{BYTExb[SM9ref_MAX_LEN];BYTEya[SM9ref_MAX_LEN];4XyhL4CLtypedefstructSM9refCipher_st{BYTEy[SM9ref_MAX_LEN];hX曲线上点的X坐标y曲线上点的Y坐标{字段名称Xy封装的交换密义曲线上点Y坐标C语言的数据结构定义：typedefstructSM9rcfkeyPa{BYTEy[SM9ref_MAX_LEN];SM9用户加密密钥对保护结构符合表A.9。444SM9EncUserPrivateKey结构体中产生对称密钥的密钥封装数据的主公钥44typedefstructSM9refEncEnvelopedKey_st{BYTEencryptedPriKey[SMSM9EncMastPublicKeytmpMa444SM9SignUserPrivateKey结构体中产生对称密钥的密钥封装数据的主公钥441ypedefstructSM9refSi{BYTEencryptedPriKey[SM9rSM9EncMastPublicKeytmpMastPubKey;ULONGkeyLen;SM9KeyPackagekeunsignedintuiKeyIndex,unsignedintuiKeyType,unsignedchar*pucMasterPublickKey,unsignedintuiMasterPublickKeyLen);0unsignedcharpUserKey,uiUserKeyLen[in]DER编码的用户密钥保护结构数据长度uiMasterPublicKeyInd0uiMasterPublicKeyInunsignedcharunsignedcharunsignedchar描述：使用SM9用户标识和签名主公钥对数据进行签名验证运算，SM9运算过程应符unsignedcharunsignedcharuiMast