GM-T 0018-2023 密码设备应用接口规范

密码设备应用接口规范国家密码管理局发布I Ⅲ 1 1 1 1 25.1算法标识定义 2 25.3设备信息定义 25.4密钥分类及存储定义 3 4 5 5 6 6 76.1密码设备应用接口在公钥密码基础设施应用技术体系框架中的位置 7 86.3密钥管理类函数 6.4非对称算法运算类函数 6.5对称算法运算类函数 6.6杂凑运算类函数 6.7用户文件操作类函数 6.8验证调试类函数 附录A(规范性)函数返回代码定义 附录B(规范性)SM9算法相关数据结构和接口函数 附录C(规范性)VPN设备相关接口函数 Ⅲb)删除了基于RSA算法的数字信封转换和基于ECC算法的数字信封转换两个接口函数(见本文件的目标是为公钥密码基础设施应用体系框架下的服务端密码设备制定统一的应用接口标1GB/T15852.2信息技术安全技术消息鉴别GB/T36624信息技术安全技术可鉴别的加密机制GB/T38635(所有部分)信息安全技术SM9标识密码算法2本文件中的基本数据类型均为高位字节在前(Big-Endian)方式存储和交换。表1定义了基本数据定义句柄，指面数据对象的起始地址表2定义了设备信息。字节)设备型号设备编号，包含：日期(8字符)、批次号(3字符)、流水号(5字符)448前4字节表示支持的算法，表示方法为非对称算法标识按位或运算的结果；4所有支持的对称算法，表示方法为对称算法标识4所有支持的杂凑算法，表示方法为杂凑算法标识4支持的最大文件存储空间(单位字节)typedefstructDeviceInfo_st{3CHARDcviceScrial[16];ULONGStandardVersion;ULONGAsymAlgAbility[2];一个加密密钥对。其中，索引号为0表示设备密钥。索引号1开始表示用户密钥。表3描述了设备密公钥设备签名公钥设备签名私钥设备加密公钥设备加密私钥……密钥加密密钥密钥加密密钥0014在最高位，不足位从高位向低位填充数据0。表5定义了RSA密钥数据结构。公钥数据结构定义数据长度(字节)4me公钥指数数据长度4md素数p和系数i#defineRSAref_MAX_PLtypedefstruciRSAreIRublicKey_st{BYTEe[RSAref_MAX_LEN];typedefstructRSArefPrivateKey_st{BYTEm[RSAref_MAX_LEN];BYTEe[RSAref_MAX_LEN];BYTEd[RSAref_MAX_LENBYTEprime[2][RSAref_MAX_PLEN];BYTEpexp[2][RSAref_MAX5表6定义了ECC密钥数据结构。公钥数据结构定义数据长度(字节)4Xy数据长度(字节)4K私钥typedefstructECCrcfPublicKey_st{typedefstructECCrefPrivateKey_st{表7定义了ECC加密数据结构。数据长度(字节)Xy6表7ECC加密数据结构(续)数据长度(字节)M明文的杂凑值L4CLtypedefstructECCCipher_stBYTEx[ECCref_MAX_LEN];BYTEy[ECCref_MAX_LEN];ULONGL表8定义了ECC签名数据结构。数据长度(字节)r签名的r部分s签名的s部分typedefstructECCSignature_st{密钥管理系统下发到设备中的ECC加密密钥对使用本结构保护，表9定义了ECC密钥对保护数据长度(字节)4版本号，本版本为17数据长度(字节)4对称算法标识(必须为ECB模式)4用保护公钥加密过的对称密钥密文结构typedefstructEnvelopedECCKey_st{BYTEcbEncryptedPriKey[ECCref_MAX_LE8密码设备密码资源管理(云环境表10设备管理类函数函数名称获取设备信息SDF_GetPrivateKeyAcSDF_ReleasePrivateKeyAc900原型：LONGSDF_OpenSession(HANDLEhDeviceHandle,HANDLE*phSessionHandle);0原型：LONGSDF_CloseSes返回值：0DEVICEINFO*pstDevic0与段备建的会所命脑返回值：0原型：lONGSDF_GetPrivateKeyAccessRight(HANDLEhSessionHandle,LPSTRpucPassword,对索引值的起始索引值为1,最大为n,密码设备的实际存储容量决定n值。私钥访问控制码不少于8字节。返回值：0成功原型：LONGSDF_ReleasePrivateKeyULONGuiKeyIndex);参数：hSessionHandle[in]与设备建立的会话句柄uiKeyIndex[in]密码设备存储的密钥对的索引值返回值：0成功表11密钥管理类函数函数名称功能导出RSA签名公钥导出RSA加密公钥生成会话密钥并用内部RSA公钥加密输出生成会话密钥并用外部RSA公钥加密输出导出ECC签名公钥导出ECC加密公钥生成会话密钥并用内部ECC公钥加密输出生成会话密钥并用外部ECC公钥加密输出SDF_GenerateAgreementD生成密钥协商参数并输出计算会话密钥SDF_GenerateAgreementDataAnd产生协商数据并计算会话密钥生成会话密钥并用密钥加密密钥加密输出表11密钥管理类函数(续)函数名称导入会话密钥并用密钥加密密钥解密销毁会话密钥6.3.2导出RSA签名公钥原型：LONGSDF_ExpHANDLEhsessionHandle,描述：导排密码设备内部存储的指定索引位置的RSA签名公钥。参数：HSessionHandle[in]与设备建立的会话句柄密码设备存储的密钥对的素引值返回值：0成ULONGuiKeyIndexRSArefPublicKey*pucPubl描述：导出密码设备内部存储的指定索引位置的RSA加密公钥与设备建立的会话句柄密码设备存储的密钥对的索引值RSA公钥结构返回值：06.3.4生成会话密钥并用内部RSA公钥加密输出原型：LONGSDF_GHANDLEhSessionHandle,ULONGuiIPKIndex,ULONGuiKeyBits,pucKcy[out]返回值：0原型：LONGSDF_GenerateKeyWithEpucKey[out]pucKey[in]返回值：0返回值：0ECC公钥结构HANDLEhScssionHandle,pucKey[out]返回值：0HANDLEhSessionHandle,ULONGuiAlgID,ECCrefPublicKey*pucPupucKey[out]返回值：0输入的外部ECC公钥结构成功原型：LONGSDF_ImpHANDLEhSessionHandle,pucKey[in]返回值：0成功原型：LONGSDF_GeneraHANDLEhSessionHandle,ULONGuiSponsorIDLenECCrefPublicKey*pucSponsorPubECCrefPublicKey*pucSponHANDLE*phAgrpucSponsorID[in]pucSponsorPublicKey[oupucSponsorTmpPublicKey[ophAgreementHandle[o返回值：0HANDLEhSessionHandle,ULONGuiResponseIDLeECCrefPublicKey*uiResponseIDLength[pucResponsePublicKey[pucResponseTmpPublicKey[in]外部输入的响应方临时ECC公钥结构phKeyHandlc[out]返回的密钥返回值：0原型：LONGSDF_GenerateAgneementDataHANDLEhSessionHandle,UEONGuiISKIndex,uiONGuResonscIDrcngECConauhekeyponso钥句柄。使用SM2算法计算会话密钥的过程应符合GB/T35276。本函数由响应方uiResponseIDLength[pucSponsorID[in]pucSponsorPublicKey[ipucSponsorTmpPublicKey[pucResponsePublicKey[o响应方ID值响应方ID长度发起方ID值发起方ID长度外部输入的发起方ECC公钥结构外部输入的发起方临时ECC公钥结构返回的响应方ECC公钥结构pucResponseTmpPublicKey[out返回值：0原型：LONGSDF_GenerateKcyWithKEK(HANDLEhSessionHandle,pucKey[out]返回值：0HANDLEhSessionHandle,描述：导入会话密钥并用密钥加密密钥解密，同时返回会话密钥句柄。加密模式为ECB模式。参数：hSessionHandle[in]与设备建立的会话句柄pucKey[in]返回值：0算法标识，指定分组密码算法和工作模式密码设备存储的密钥加密密钥的索引值缓冲区指针，用于存放输入的密钥密文输入的密钥密文长度返回的密钥句柄成功6.3.17销毁会话密钥销毁会话密钥开释放密钥句极分配的对存资源本面数在对称算法运算完成后调用。返回值：06.4非对称算法运算类函数非对称算法运算类函数提供RSA公私钥运算、ECC签名验证和加密功能，表12列出了非对称算法运算类函数，附录A定义了函数返国代码。表12非对称算法运算类函数函数名称SDF_ExternalPublicKeyOperSDF_InternalPublicKeyOper内部公钥RSA运算SDF_InternalPrivateKeyOper内部私钥RSA运算内部私钥ECC签名内部公钥ECC验证外部公钥ECC加密原型：LONGSDF_ExternalPublicKeyOperHANDLEhSessionHandle,ULONG*puiOutputL外部RSA公钥结构返回值：0原型：LONGSDF_InternalPHANDLEhSessionHandle,ULONGuiInputLength,ULONG*puiOutputL原型：LONGSDF_InternalPrivateKeyOperaHANDLEhSessionHandle,ULONG*puiOutputLength);0HANDLEhSessionHandle,ECCrefPublicKey*pucPublicKey,ECCSignature*pucSignatu描述：使用外部公钥对ECC签名值进行验证运算。输入数据为待签数据的杂凑值。当使用应符合GB/T35276。外部ECC公钥结构返回值：0原型：LONGSDF_InterECCSignature*pucSignature);描述：使用内部指定索引的私钥对数据进行ECC签名运算。输入数据为待签数据的杂凑值。处理过程应符合GB/T35276。返回值：0原型：LONGSDF_InteECCSignature*pucSignatu0ECCrefPublicKey*pucPu外部ECC公钥结构返回值：0函数名称计算单包MAC多包对称加密初始化多包对称加密多包对称加密结束多包对称解密初始化多包对称解密多包对称解密结束多包MAC初始化多包MAC计算多包可鉴别加密初始化多包可鉴别加密多包可鉴别加密结束多包可鉴别解密初始化多包可鉴别解密多包可鉴别解密结束HANDLEhKeyHandle,描述：使用指定的密钥句柄和IV对数据进行对称加密运算。此函数不对数据进行填充处理。此函数的IV数据长度与算法分组长度相同。与设备建立的会话句柄指定的密钥句柄法，指定分组密码算法和工作模式缓冲区指针，用于存放输入的数据明文输入的数据明文长度缓冲区指钆，用于存放输出的数据密文输画的数据密文长度返回值：0HANDLEbSessionHandleULONGuiAlgID,ULONG*puiD描述：使用指定的密钥句柄和IV对数据进行对称解密运算。此函数的IV数据长度与算法分组长度相同。pucIV[in]与设备建立的会话句柄指定的密钥句柄算法标识，指定分组密码算法和工作模式缓冲区指针，用于存放输入的IV数据HANDLEhSessionHandle,HANDLEhKeyHandle,pucIV[in]0HANDLEhKeyHandle,ULONGuiStartVarLength,使用指定的密钥句栖对数据进行可鉴加密之算。此函数应用于可鉴别加密的CCM和设备建会话句硒法标指定分组密码算法和二作模式输入的开始变量长度pueAadn]puiAuthDataLength[o返回值：0ULONGuiAadLength,返回值：0HANDLEhSessionHandle,pucIV[in]输入的IV数据长度返回值：0成功HANDLEhSessionHandle,返回值：0成功HANDLEhSessionHandle,ULONG*puiLastEncDataLpuiLastEncDataLength[o返回值：0HANDLEhSessionHandle,pucIV[in]输入的IV数据长度返回值：0HANDLEhSessionHandle,ULONGuiEncDataLength,返回值：0HANDLEhSessionHandle,ULONG*puiLastDatpuiLastDataLength[o返回值：0HANDLEhSessionHandle,HANDLEhKeyHandle,pucIV[inHANDLEhSessionHandle,ULONGuiDataLength);返回值：0HANDLEhSessionHandlc,返回值：0HANDLEhSessionHandle,HANDLEhKeyHandle,UAONGyiAadLengthULONGuiDataLength);据。此函数应用于可鉴别加密的CCM和GCM模式，输入输出数据应接照GM/T0006uiSartVarLengih信0没备建立的会话的法标识分组密偶算法和工作模输入的开始变长度原型：LONGSDF_AuthEncUpdate(HANDLEhSessionHandle,ULONGuiDataLength,ULONG*puiEncDataLen0HANDLEhSessionHandle,ULONG*puiLastEncDataLength,ULONG*puiAuthDataLpuiLastEncDataLength[puiAuthDataLength[o返回值：0HANDLEhSessionHandle,HANDLEhKeyHandle,ULONGuiAadLength,ULONGuiDataLength);据。此函数应用于可鉴别解密的CCM和GCM模式，输入输出数据应按照GM/T0006定义的算法标识和GB/TpucAad[in]36624的规定进行确定。GCM模式下的数据明文总长度参数输入的额外的再鉴数居长度uiDataLength入的数据文总长愈原型：LONGSDF_AuthDecUpdHANDLEhScssionHandlc,ULONG*puiLastDataLen返回值：0函数名称带密钥的多包杂凑运算带密钥的杂凑运算结束多包杂凑运算HANDLEhSessionHandle,HANDLEhKeyHandle,描述：三步式带密钥的数据杂凑运算第一步。本函数执行带密钥的杂凑运算过程应符HANDLEhSessionHandle,0HANDLEhSessionHandle,返回值：0HANDLEhScssionHandlc,ECCrefPublicKey*pucPublicKey,pucID[in]0HANDLEhSessionHandle,ULONGuiDataLength);HANDLEhSessionHandle,pucHash[out返回值：0函数名称LPSTRpucFileName,返回值：0HANDLEhSessionHandle,ULONGuiNameIenBYTE*pucBuffer);描述：读取在密码设备内部存储用户数据的文件的内容。hSessionHandlein]入参谢指啶读取文作内容的长度出参时返回实际读取返回值：0非0失败返圆错误代码ULONGuiFileLength,非0HANDLEhSessionHandle,ULONGuiNameLen);返回值：0函数名称产生RSA非对称密钥对并输出产生ECC非对称密钥对并输出SDF_ExternalPrivateKeyOpcr外部私钥ECC签名外部私钥ECC解密外部私钥SM9签名外部私钥SM9解密外部密钥单包对称加密表16验证调试类函数(续)函数名称外部密钥单包对称解密RSArefPublicKey*pucPublicKey,RSArefPrivateKey*pucPrivateKe返回值：0ECC公钥结构返回值：0成功原型：LONGSDF_ExternalPrivateULONGuilnputLength,ULONGuiInputLength,pucPrivateKey[in]外部ECC私钥结构返回值：0外部ECC私钥结构返回值：0SM9SignMasterPublicKey*pSignMastPublicSM9SignUserPrivateKey*ULONGuiDataLengthpSignUserPrivateKey[非0pEncUserPrivateKey[返回值：0ULONGuiIVLength,ULONG*puiEncDataLength);描述：使用外部密钥和IV对数据进行对称加密运算。此函数不对数据进行填充处理。pucKcy[in]pucIV[in]返回值：0成功原型：LONGSDF_Ext描述：使用外部密钥和IV对数据进行对称解密运算。pucKey[in]pucIV[in|out非0ULONGuiKeyLength,pucKey[in]pucIV[in]返回值：0ULONGuiKeyLength,pucKcy[in]pucIV[in]输入的IV数据长度返回值：0描述：主步式带密钥的数据集法运算第一二步。本函数执行形密研丽杂凑运算过程应符uiAlgID[inuiKeyLcngth[in返回值：0(规范性)说明操作成功未知错误不支持的接口调用SDR_BASE十0x00000003与设备通信失败打开设备失败无私钥使用权限不存在的密钥调用不支持的算法调用井defineSDR_ALGMODN不支持的算法模式调用公钥运算失败多步运算步骤错误文件长度超出限制指定的文件不存在SDR_BASE十0x00000013随机数产生失败说明指定文件已存在用户标识错误至预留表B.1定义了SM9主私钥数据结构，用于SM9签名主私钥和SM9加密主私钥。数据长度(字节)4s主私钥#defineSM9ref_MAX_LEN((SM9ref_MAX_BITS+7)/8)typedefstructSM9refMasterPrivateKey_st{ULONGbits;BYTEs[SM9ref_MAX_LEN];表B.2定义了SM9签名主公钥数据结构。数据长度(字节)4曲线上点X坐标高维曲线上点X坐标低维曲线上点Y坐标高维曲线上点Y坐标低维typedefstructSM9refSignMasterPublicKey_st{ULONGbits;BYTExa[SM9ref_MAX_LEN];BYTExb[SM9ref_MAX_LEN];BYTEya[SM9rcf_MAX_BYTEyb[SM9ref_MAX_LEN];B.1.3SM9加密主公钥数据结构定义表B.3定义了SM9加密主公钥数据结构。数据长度(字节)4X曲线上点X坐标y曲线上点Y坐标typedefstructSM9refEncMasterPublicKey_st{数据长度(字节)4X曲线上点X坐标y曲线上点Y坐标typcdcfstructSM9refSignUserPriva{表B.5定义了SM9用户加密私钥数据结构。数据长度(字节)4曲线上点X坐标高维曲线上点X坐标低维曲线上点Y坐标高维曲线上点Y坐标低维typedefstructSM9refEncUserPrivateKey_st{BYTExa[SM9ref_MAX_LEN];BYTExb[SM9ref_MABYTEya[SM9ref_MAX_LEN];BYTEyb[SM9ref_MA表B.6定义了SM9加密数据结构。数据长度(字节)4XyhL4CLtypedcfstructSM9refCipher_st{表B.7定义了SM9签名数据结构。表B.7SM9签名数据结构数据长度(字节)hXytypedefstructSM9refSignaturc_st表B.8SM9密钥封装数据结构数据长度(字节)XytypcdefstructSM9rcfKcyPackage_st表B.9定义了SM9用户加密密钥对保护结构。表B.9SM9用户加密密钥对保护结构数据长度(字节)444数据长度(字节)SM9EncUserPrivateKey结构体中除去长产生对称密钥的密钥封装数据的主公钥44typedefstructSM9refEncEnvclopcd{ULONGversion;BYTEencryptedPriKey[SM9ref_MAX_LENSM9EncMastPublicKeytmpMa数据长度(字节)444SM9SignUserPrivateK数据长度(字节)产生对称密钥的密钥封装数据的主公钥44SM9KeyPackagc类型{enc:sptedPrikoyISM⁹aIMAXEBYTEuserID[256];函数名称功能SDF_GenerateEncMasterK装并输出装并输出使用SM9密钥封装结构导入会话密钥并用表B.11SM9算法相关接口函数(续)函数名称功能SDF_GenerateAgreementDSM9生成密钥协商参数并输出SDF_GenerateAgreementDataAnd内部主公钥SM9验证SDF_InternalSignWithMas外部主公钥SM9签名SDF_InternalSignWithMas内部主公钥SM9签名内部主公钥SM9加密HANDLEhSessionHandle,ULONGuiKeyIndex,参数：hSessionHandle[in]uiKeyIndex[in]输出的用户标识缓冲区，若该项为NULL,则puiUse-rIDLen输出所需缓冲区长度输入为pucUserID的缓冲区长度，输出为pucUserID实际长度原型：intSDF_GenerateEncMasterKeyPHANDLEhSessionHandle,SM9EncMastcrPublicKcy*pEncMasterPucli护结构。当输入的SM9主密钥索引值为0xFFFFFFFF时，输出的主密钥索引值由密码pEncMasterPaclicKeyfout]输出的SM9主公钥数据结构0B.2.4生成会话密钥并用SM9外部加密主公钥和用户标进行密钥封装并输出原型：intSDF_GeneratcEezWEMIk_SM9(HANDLFhSesfonfa钥封装的具体过程应符合GB/T38635。密钥封装和解封装函数输入的对称密钥长度值输出的SM9密钥封装结构返回值：0HANDLEhSessionHandle,ULONGuiISKIndex,返回值：0原型：intSDF_GenerateAgreementDataWithSM9(ULONGuiKeyBits,ULONGulResponseIDSM9EncMastPublicKey*pSponHANDLE*phAgreementHpSponsorID[in]pSponsorTempPublicKey[ophAgreementHandle[o原型：intSDF_GenerateAgreementDataAndKeyWithSM9(HANDLEhSessionHandle,ULONGuiKeyBits,ULONGulResponseIDLen,ULONGulSponsorIDLen,SM9EncMastPublicKcySM9EncMastPublicKeypSponsorID[in]响应方id响应方id长度发起方id发起方id长度pPublicKey[in]发起方主公钥pSponsorTempPublicKey[in]发起pResponseTempPublicKey[out]返回的响应方临时主公钥phKeyHandlc[out]返回的密钥句柄返回值：0HANDLEhSessionHandle,SM9SignMasterPublicK描述：使用外部签名主公钥和用户标识对SM9签名进行验证运算。输入数据为待签数据的用户标识0非0ULONGuiSignMasterKeyIndULONGuiDataLength,描述：使用内部签名主公钥和用户标识对SM9签名进行验证运算。输入数据为待签数据的返回值：0原型：intSDF_InternalSiULONGuiISKInd描述：使用外部签名主公钥和SM9用户签名私钥对数据进行签名运算。输入数据为待签数据输人的数据长度缓河指键用于存放输出的签径值数据0成原型：ntSDF_InternalSigrVMaHANDLEhScssionHLanULONGuiISKInd描述：使用内部签名主公钥和SM9用户签名私钥对数据进行签名运算。输入数据为待签数据非0ULONGulAlgID,0原型：intSDF_EncryptWithMastULONGuiMasterKeyIULONGuiUserIDLeULONGuiDataLengthulAlgID[in]uiDalaLength[in相际识的长度加密明文的算法标识通区指钋于存放外部输人的数据缓冲区指针、川工存放偷的数据密文0非HANDLEhSessionHandle,ULONGuiUscrIDLen,应符合GB/T38635。IV数据长度为16个字节，仅当uiAlgID为SGD_SM98CBC、SGD_SM98OFB、SGD_输入的IV数据返回值：0函数名称功能计算IKE工作密钥并用外部ECC公钥加密输出计算IPSEC会话密钥并用外部ECC公钥加密输出计算SSL工作密钥并用外部ECC公钥加密输出原型：LONGSDF_GenerateHANDLEhSessionHandle,ULONGuiSponsorNonceLenULONGuiResponseNonceLeULONGuiSponsorCookieLeULONGuiResponseCookieLeuiSponsorNonceLength[uiResponseNonceLengthuiSponsorCookieLength[uiResponscCookicLength返回值：0HANDLEhSessionHandle,ULONGuiSponsorNonceLength,ULONGuiResponseNonceLength,ULONGuiSponsorCookieLeULONGuiResponseCookieLeULONGuiEccAlgIDECCrefPublicKey*pucPublicKey,ULONGuiKeyBitsE);息3和消息4交互完成后，本函数由参与通信的双方各白调用，计算后续工作密钥uiSponsorNonceLength[uiResponseNonceLengthuiSponsorCookicLength[uiResponseCookieLength发起方cookie输入的外部ECC公钥结构SKEYID_d密钥长度原型：LONGSDF_GeneratULONGuiProtocolIDLength,ULONGuiSponsorNonceLenULONGuiResponseNonceLeHANDLEhKeyHandle,协议IDuiProtocolIDLength[uiSponsorNonceLength[uiResponseNonceLength协议ID长度发起方nonce载荷主体发起方n