GMT 0016-2023 智能密码钥匙密码应用接口规范

代替GM/T0016—2012智能密码钥匙密码应用接口规范国家密码管理局发布I 12规范性引用文件 13术语和定义 1 25结构模型 25.1层次关系 2 36数据类型定义 46.1算法标识 46.2基本数据类型 46.3常量定义 46.4复合数据类型 57接口函数 7.1设备管理 7.3应用管理 7.4文件管理 7.5容器管理 7.6密码服务 7.7验证调试 8接口使用要求 438.1设备使用阶段 8.2权限管理 8.3其他安全要求 附录A(规范性)错误代码定义 45附录B(规范性)SM9应用接口 附录D(资料性)SM9编程范例 参考文献 75Ⅲj)增加了VPN相关接口(见附录C);本文件的目标是为公钥密码基础设施应用体系框架下的智能密码钥匙设备制定统一的应用接口10017—20232管理员PINadministratorPIN管理员的口令，为ASCII字符串。用户的个人口令，为ASCIⅡ字符串。包括容器和文件的一种结构，具备独立的管理权限。4缩略语下列缩略语适用子禾文件API:应用编程接口(ApplicationProgrammingInterface)ASCII:美国信息交换标准码(AmericanStandardCodeforInformationInterchange)PKI:公朗基研设施PaubicKeyhntfastuctmc)PIN:个人身份识别码CPersonalIdentheafonkanber)5结构模型图1所示。智能密码钥匙硬件接日所符合GM/f0027-20+E中6工的规定NFCNFC图1接口在应用层次关系中的位置3终端设备应具有一个设备认证密钥。终端设备应支持一个或多个应用。应用之间应相互独立。设备的逻辑结构如图2所示。应用1应用2应用n权限状态。管理员PIN和用户PIN的校验操作可改变应用权限状态。一个应用的逻辑结构如图3钥对用于数字签名和验证，会话密钥用于数据加解密和MAC运算。容器中存放SM2算法的密钥对容器1容器1会话密钥用户PIN文件m46数据类型定义密码算法标识应符合GM/T0006—2023中第6章的规定。字节数组应使用高位字节在前(Big-Endian)的方式存储和交换。基本数据类型定义见表1。表十一基本数据类型备注有符号16位整数例如，typedefunslgnedc字行型九在号8位整设备句柄数据常量标识定义了在规范中用到的常量的取值。数据常量标识的定义如表2所示。5常量名_stdcall函数调用方式01typedefstructStruct_Version{数据项应符合表3的规定。意义次版本号typedefstruct6ULONGMaxBuf数据项应符合表4的规定。数据项意义设备厂商信息以‘\0’为结束符的ASCII字符串发行厂商信息以‘\0'为结束符的ASCII字符串以‘\0'为结束符的ASCII字符串以‘\O'为结束符的ASCII字符串分组密码算法标识非对称密码算法标识一设备总空间大小用户可用空间大小能够处理的ECC加密数据大小数据大小 typedefstructStruct_RSAPUBLICKEYBLOB{7BYTEModulus[MAX_RSA_MODULUS_LEN];BYTEPublicExponent[MAX_RSA_EXPONENT_数据项类型意义备注算法标识号模数n=p*q实际长度为BitLen/8字节#defineMAX_RSA_MODULUS_LE#defineMAXRSAEXPONENT_LEN公开密钥c一般为00010001typedefstructStruct_RSAPRIVATEKEYBLOB{BYTEModulus[MAX_RSA_MODULUS_LEN];BYTEPublicExponent[MAX_RSA_EXPONENT_BYTEPrivateExponent[MAX_RSA_MODULUS_LEN];BYTEPrimel[MAX_RSA_MODULUS_LEN/2];BYTEPrime2[MAX_RSA_MODULUS_LEN/2];BYTEPrimelExponent[MAX_RSA_MODULUS_LEN/2];BYTEPrime2Exponent[MAX_RSA_MODULUS_LEN/2];BYTECoefficient[MAX_RSA_MODULUS_LEN/2];8数据项意义算法标识号实际长度为BitLen/8字节一般为00010001实际长度为BitLen/8字节typedefstructStruct_ECCPUBLICKEYBLOB{BYTEXCoordinate[ECC_MAX_XCOORDINATE_BITS_LEN/8];BYTEYCoordinate[ECC_MAX_YCOORDINATE_BITS_LEN/8];ECC_MAX_XCOORDINATE_LEN为ECC算法X坐标的最大长度；ECC_MAX_YCOORDINATE_LEN为ECC算法Y坐标的最大长度。数据项描述见表7。数据项意义曲线上点的X坐标#defineECC_MAX_XCOORDINATE_BITS_LEN曲线上点的Y坐标#defineECC_MAX_YCOORDINATE_BITS_LEN9typedefstructStruct_ECCPRIVATEKEYBLOB{BYTEPrivateKey[ECC_MAX_MODULUS_BITECC_MAX_MODULUS_BITS_LEN为E表8ECC私钥数据结构数据项意义私有密钥#defineECC_MAX_MODULUS_BITS_LENtypedefstructStruct_ECCCIPHERBBYTEXCoordinate[ECC_MAX_XCOORDINATE_BITS_LEN/8];YCoordinate[ECC_MAX_XCOORDINATE_BITS数据项描述见表9。数据项意义与y组成椭圆曲线上的点(x,y)与x组成椭圆曲线上的点(x,y)明文的杂凑值6.4.9ECC签名数据结构typedefstructr[ECC_MAX_XCOORDINATE_BITS_LEs[ECC_MAX_XCOORDINATECC_MAX_MODULUS_BITS_LEN为ECC算法模数的最大长度。数据项描述见表10。表10ECC签名数据结构数据项类型意义备注rtypedefstructStruciBEOCRCIPHEReARAM数据项描述见表11。表11分组密码参数数据项意义初始向量实际长度(按字节计算)反馈值的位长度(按位计算)只针对OFB、CFB模式typedefstructStruct_ENVELOPEDKEYBLOB数据项意义的原文为ECCPRIVATEKEYBLOB加密密钥对的公钥一typedefstructStruct_FILEATULONGReadRights;表13文件属性意义文件名以‘\O'结束的ASCII字符串，最大长度为32文件大小创建文件时定义的文件大小写入权限写入文件应已取得的权限权限类型的定义见表14表14权限类型权限类型值说明理员权限用主权限设备状态的定义见表表设备状态设备状态值说明设备不存在设备存在设备状态未知接口函数所返回的错误代码应符合附录A中的规定。7接口函数7.1设备管理设备管理主要完成设备的插拔事件处理、枚举设备、连接设备、断开连标签、获取设备信息、锁定设备、解锁设备的操作。设备管理系列函数见表16。表16设备管理系列函数函数名称断开连接获取设备信息原型ULONGDEVAPISKF_WaitForDevEvent(LPSTRszDevName,ULONGNameLen,ULONG*pulEv参数szDevName[OUT]pulEvent返回值SAR_OK:成功。原型ULONGDEVAPISKF_Cancel功能描述该函数取消等待设备插入或者拔除事件。ULONGDEVAPISKF_EnumDev(BOOLbPresent,LPSTRszNameList,ULONG参数bPresent[IN]为TRUE表示取当前设备状态为存在的设备列表。为FALSEszNameList[OUT]设备名称列表。如果该参数为NULL,将由pulSize返回该列原型ULONGDphDev[OUT]原型ULONGDEVAPISKF_DisConnectDev(DEVHANDLEhDev)原型ULONGDEVAPISKF_GetDevState(LPSTRszDpulDevState[OUT]返回设备状态。原型功能描述ULONGDEVAPISKF_SetLabel(DEVHANDLEhDev,LPSTRszLabel)hDev[IN]连接设备时返回的设备句柄。szLabel[IN]设备标签字符串。该字符串应小于32字节。原型ULONGDEVAPISKF_GetDULONGDEVAPISKF_LockDev(DEVHANDLEhDev,ULONG函数名称修改设备认证密钥获得PIN码信息ULONGDEVAPISKF_ChangeDevAuthKey(DEVHANDLEhDepher,ULONGulKeyCipherLen,BYTE*pbKeyMac,UL原型ULONGDEVAPISKF_DevAuth(DEVHANDLEhDev,BYTE*pbAut原型ULONGDEVAPISKF_ChangePIN(HAPPLICATIONhApplication,ULONGulPIN-Type,LPSTRszOldPin,LPSTRszNewPin,ULONG原型ULONGDEVAPISKF_GetPINInfo(HAPPLIType,ULONG*pulMaxRetryCount,ULONG*pulRemainRetryCount,BOOL*pbDe-原型ULONGDEVAPISKF_VerifyPIN(HAPPLIType,LPSTRszPIN,ULONG*pulRetryCou原型ULONGDEVAPISKF_UnblockPIN(HAPPLICATIONhA原型ULONGDEVAPISKF_Cl表18应用管理系列函数创建应用关闭应朋ULoNGDEVAPISKF_CreateApplieatronPSTRszAdminPin,DWORDdwAdminPinRetryCount,LPSTRdwOserPinBetryCount,DWORDdwCreateFileRights,HAPPLiCATiON*phApplszAppNameN]应用名称szAdminPin[IN]管理员PIN。phApplication[OUT]应用的句柄。SAR_OK:成功。ULONGDEVAPISKF_EnumApplication(DEVHANDLEhDev[IN]连接设备时返回的设备句柄。ULONGDEVAPISKF_DeleteApplication(DEVHANDLEhDev原型ULONGDEVAPISKF_OpenApplication(DEVHAN参数hDevphApplication原型ULONGDEVAPISKF_CloseApplication(HAPPLICATI函数名称获取文件信息原型ULONGDEVAPName,ULQNGaieSize,Gulrights,功能描述创建文件时要指定文件的名称大小，以及义件的读写权限。szFileName文件名称。度不应人132个字ulFleSize文件大小种权限的或值。ulWritekoghts[IN]文件写权限，权限类型应符合6.41的要求。取值可为各原型ULONGDEVAPISKF_DeleteFile(HAPPLICATIONhApplicName)hApplication[IN]要删除文件所在的应用句柄。szFileName[IN]要删原型ULONGDEVAPISKF_EnumFiles(HAPPLICATIONhApplication,LPSTRszFileULONGDEVAPISKF_GetFileInfo(HAPPLICATIONhApplication,LPSTRszFile-Namc,FILEATTRIBUTE*pFileInf原型ULONGDEVAPISKF_ReadFile(HAPPLICATIONhApplication,LPSTRszFile-Name,ULONGulOffset,ULONGulSize,BYTE*pbOutData,ULONG原型ULONGDEVAPISKF_WriteFile(HName,ULONGulOffset,BYTE*pbData,ULONGulSize)返回值SAR_OK:成功。出数字证书操作。容器管理函数见表20。表20容器管理系列函数函数名称获得容器类型导入数字证书导出数字证书原型ULONGDEVAPISKF_CreateContainer(HAContainerName,HCONTAINER*phContainer)phContainerphContainer原型ULONGDEVAPISKF_DeleteContain原型ULONGDEVAPISKF_OpenContaitainerName,HCONTAINER原型ULONGDEVAPISKF_CloseContain原型ULONGDEVAPISKF_EnumContaincr(HAPPLICATIONhApplicatio原型ULONGDEVAPISKF_GelContainerType(HCONTAINERhContainer,ULONG*pul-功能描述获取容器的类型。原型ULONGDEVAPISKF_ImportCertificpbCertULONGDEVAPISKF_ExportCertificate(HCONTAINERhContainerpbCert成功。错误码。功能。密码服务系列函数见表21。表21密码服务系列函数函数名称功能RSA签名ECC签名SKF_GenerateAgreementDECC生成密钥协商参数并输出SKF_GenerateAgreementDataAnd导出公钥导入会话密钥单包数据加密多包数据加密结束加密表21密码服务系列函数(续)函数名称功能单包数据解密多包数据解密结束解密多包数据密码杂凑结束密码杂凑多包数据消息鉴别码运算带密钥的杂凑运算初始化带密铜的单包杂淡运算带密钥包杂凑运算带密钒的凑运算结策原型功能描述参数返回值UONCDEVAPISKF_GenRandom(DEVHANDLEULONGunRandomLen)产生指定长度的随机数。hDev[IN]设备句柄。pbRandom[OUT]返回的随机数。ulRandomLen[IN]随机数长度SAR_OK:成功。7.6.3生成RSA签名密钥对原型功能描述参数ULONGDEVAPISKF_GenRSAKeyPair(HCONTAINERhContainer,ULONGu生成RSA签名密钥对并输出签名公钥。hContainer[IN]容器句柄。ulBitsLen[IN]密钥模长。pBlob[OUT]返回的RSA公钥数据结构。返回值SAR_OK:成功。7.6.4导入RSA加密密钥对功能描述ULONGDEVAPISKF_ImportRSAKeyPaHCONTAINERhContainer,ULONGulSymAlgId,BYTE*pbWrappedKey,ULONGulWrapBYTE*pbEncryptedData,ULOhContainer[IN]容ulSymAlgIdpbWrappedKey[IN]使用该容器内签名公钥保护的对称算法密钥。ulWrappedKeyLen[IN]保SAR_OK:成功。7.6.5RSA签名DEVAPISKF_RSASignData(HCONTAINERh功能描述[IN]签名数据长度，应不大于RSA密钥模长-11。成功。原型ULONGDEVAPISKF_RSAVerify(HCONTAINERhCULONGulDataLen,BYTE*pbSignature,ULONGulSignLen)功能描述使用hContainer指定容器的签名公钥，进行验证RSA签名操作。参数hDev[IN]设备句柄。pRSAPubKeyBlob[IN]RSA公钥数据结构。[IN]待验证签名的数据。[IN]数据长度，应不大于公钥模长-11。[IN]待验证的签名值。[IN]签名值长度，应为公钥模长。返回值其他：成功。错误码。7.6.7RSA生成导出会话密钥原型功能描述参数返回值ULONGDEVAPISKF_RSAExportSessionKey(HCONTAINERhContulAlgId,RSAPUBLICKEYBLOB*pPubKey,BYTE*pbData,UIONG*pulDataLen,HANDLEphSessionKey)牛成会话密钥并用外部RSA公钥加密输出。hConzginerTN容器句柄。NI会话密班算法标。NI会话密班算法标。封[INT]输人表示会话密钥密文数据缓冲区长度，输出时表公话密钥密文的实际长度IQUT]导出的密钥年病pPubKey借误码。借误码。SAR_OK:7.6.8外来RSA公钥运算原型功能描述参数ULONGDEVAPISKF_ExtRSAPubKeyOperRSAPUBLICKEYBLOB*pRSAPubKeyBlob,BYTEpbInpBYTE*pbOutput,ULONG*pulOut使用外部传入的RSA公钥对输入数据做公钥运算并输出结果。hDev[IN]设备句柄。pRSAPubKeyBlob[IN]RSA公钥数据结构。返回值pbInputpbOutput其他：成功。错误码。[IN]指向待运算的原始数据缓冲区。[IN]待运算原始数据的长度，应为公钥模长。[OUT]指向RSA公钥运算结果缓冲区，如果该参数为NULL,则由pulOutputLen返回运算结果的实际长度。[IN,OUT]输入时表示pbOutput缓冲区的长度，输出时表示RSA公钥运算结果的实际长度。功能描述ULONGDEVAPISKF_GenECCKeyPair(HCONTAINERhContainer,ULONGulAl-hContainer[IN]密钥容器句柄。pBlob成功。7.6.10导入ECC加密密钥对原型ULONGDEVAPISKF_ImportECCKeyPai功能描述PENVELOPEDKEYBLOBpEnvelopedKeyBlob)导入ECC公私钥对。原型ULONGDEVAPISKF_ECCSignData(ULONGulDataLen,PECCSIGNATUREBLOBpSig功能描述ECC数字签名。采用ECC算法和指定私钥hKey,对指定数据pbData进行数字签名。签名后的结果存放到pSignature中。参数hContainer[IN]原型ULONGDEVAPISKF_ECCVerify(DEVHANDLEhDev,pECCPubKeyBlob,BYTE*pbData,ULONGulDataLen,PECCSIGNATURpECCPubKeyBlob[IpSignature原型ULONGDEVAPISKF_ECCExportSessionKey(HCONTulAlgId,ECCPUBLICKEYBLOB*pPubKey,PECCCIPHERBLOBpData,HAN功能描述生成会话密钥并用外部公钥加密导出。ulAlgIdpPubKey[IN]外部输入的公钥结构。pData[OUT]会话密钥密文。phSessionKey[OUT]返回值SAR_OK:成功。原型ULONGDEVAPISKF_ExtECCEncrypt(DEVHANDLEhDECCPUBLICKEYBLOB*pECCPubKeyBlob,BYTE*pbPlainText,ULONGulPlain-TextLen,PECCCIPHERBLOBpCipherText)功能描述使用外部传入的ECC公钥对输入数据做加密运算并输出结果。参数hDevpECCPubKeyBlob[IN]pbPlainTextulPlainTextLen[IN]pCipherText[原型ULONGDEVAPISKF_GenerateAgreementDataWithECC(HCONTAINERhCon-ULONGulAlgId,ECCPUBLICKEYBLOB*pContaincrECCPubKeyBlob,ECCPUBLICKEYBLOB*pTempECCPubKeyBlob,BYTE*pbID,ULONGulIDLen,ulAlgIdpTempECCPubKeyBlob[OUT]发起方临时ECC公钥。pbID[IN]发起方的ID。phAgreementHandle[OUT]返回的密钥协商句柄。ECCPUBLICKEYBLOB*pECCPuECCPUBLICKEYBLOB*pTempECCPBYTE*pbID,ULONGulIDLen,HANDpECCPubKeyBlob[IN]外部输入的响应方ECC公钥。pTempECCPubKeyBlob[IN]外部输入的响应方临时ECC公钥。pbID[IN]响应方的ID。phKeyHandle[OUT]返回的密钥句柄。tainer,ULONGulAlgId,ECCPUBLICKEYBLOB*pSponsorECCPubKeyBlob,ECCPUBLICKEYBLOB*pSponsorTempECCPECCPUBLICKEYBLOB*pTempECCPBYTE*pbID,ULONGulIDLen,BYTE*pbSponsorID,ULONGulSponsorIDLen,ulAlgId[IN]会话密钥算法标识。pSponsorECCPubKeyBlob[IN]发起方的ECC公钥。pSponsorTempECCPubKeyBlob[IN]发起方的临时ECC公钥。pTempECCPubKeyBlob[OUT]响应方的临时ECC公钥。pbSponsorID[IN]发起方的ID。phKeyHandle[OUT]返回的对称算法密钥句柄。返回值SAR_OK:成功。ULONGDEVAPISKF_ExportPublicKey(HCONTAINERhFlag,BYTE*pbBlob,ULONG*pulBpbBlob[OUT]指向RSA公钥结构(RSAPUBLICKEYBLOB),或ECC公钥结构(ECCPUBLICKEYBLOB),或SM9用户标识(BYTE数组),如果pbBlob成功。ULONGDEVAPISKF_ImportSessionKey(HCONTAINERhContainer,ULONGulAl-gId,BYTE*pbWrapedData,ULONGulWrapedLen,HANDLE*phKey)phKey密文数据PAIRKEYPACKAGEBLOB。ULONGDEVAPISKF_EncryptInit(HANDLEhKey,BLOCKCIPHERPARAMEn-SAR_OK:成功。ULONGDEVAPISKF_Encrypt(HANDLEhKey,BYTE*pbData,ULONGulDat-aLen,BYTE*pbEncryptedData,ULONG*pulEncryptedLen)于先调用SKF_EncryptUpda返回值SAR_OK:成功。原型ULONGDEVAPISKF_EncryptUpdate(HANDLEhKey,BYTE*pbData,ULONGul-DataLen,BYTE*pbEncryptedData,ULONG功能描述多个数据包的加密操作。用指定加密密钥对指定数据进行加密，被加密的数据包含多个数据包，加密后的密文保存到指定的缓冲区中。SKF_EncryptUpdate对数据进行加密，SKF_EncryptUpdate处理全部数据包之后，应调用SKF_EncryptFinal结束加密操作。参数hKey[IN]加密密钥句柄pbDataN]待加密数据。ulDataLen[IN]待加密数据长度。pbEncryptedData[OUT]加密后的数据缓冲区指针。pulEncryptedLen[OUT]返回加密后的数据长度。其他：错医码原型功能描述结束多个分维数拥的加密，返，余加一果。先调用SKFBncryptmit初始化加密操作，再调用SkTErptOpdate对多个分组数据进行加密取后调用SkFEncryptFinal结束多个分组数的加蓝参数hKeyEINI加密密钥句柄。pbEncyptedData[OUT]加密结果的缓冲区。ulEncyptedDataLen[OUT]加密结果的长度。返回值SAR_OK:成功。原型ULONGDEVAPISKF_DecryptInit(HANDLEhKey,BLOCKCIPHERPARAMDe-功能描述数据解密初始化，设置解密密钥相关参数。调用SKF_DecryptInit之后，可调用SKF_De-crypt对单个分组数据进行解密，也可多次调用SKF_DecryptUpdate之后再调用SKF_De-cryptFinal完成对多个分组数据的解密。参数hKey[IN]解密密钥句柄。的位长度。返回值SAR_OK:成功。原型ULONGDEVAPISKF_DecrypulEncryptedLen,BYTE*pbData,ULONG*pulDa于先调用SKF_DecryptUpdahKcy返回值SAR_OK:ULONGDEVAPISKF_DecryptUpdate(HANDLEhKey,BYTE*pbEncryptedData,ULONGulEncryptedLen,BYTE*pbData,ULONG*pulDaulEncryptedLen[IN]待解密数据长度。pbData[OUT]指向解密后的数据缓冲区指针。返回值SAR_OK:原型ULONGDEVAPISKF_DhKey[OUT]指向解密结果的缓冲区，如果此参数为NUpulDecryptedDataLen返回解密结果的长度。[IN,OUT]输入时表示pbDecryptedData缓冲区的长度，输出时表示解密结果的长度。返回值成功。错误码。原型功能描述参数返回值ULONGDEVAPISKF_DigestInit(DEVHANDLEhDev,ULONGulAlgID,初始化密码杂凑计算操作，指定计算密码杂凑的算法。hDev[IN]连接设备时返回的设备句柄。ulAlgID[IN]密码杂凑算法标识。pFubKey[IN]签名者公钥。当ulAlgID为SGD_SM3时有效。phHash00T]密码杂凑对象何柄。。7.6.29单包数据密码杂凑原型功能描述参数返回值uloNGIEVAPISKEDgstIHANDEEhlasb,BYTIGspbData,uLoNGulDat-aLen,BYTE*pbHashD对单包的消息进行密码杂凑计算。调用SKF_Digest之前，应调用SKF_DigestInit初始化密码杂凑计算操作。SKF_Digest等价于多次调用SKFDigestUpdate之后再调用SKFSAR_OK:成功。[IN]密码杂凑对象何柄。N]指向消息数据的缓神区。[IN]消息数据的长度。[OUT]密码杂凑数据缓冲区指针，当此参数为NULL时，由pul-HashLen返回密码杂凑结果的长度。[IN,OUT]输入时表示结果数据缓冲区长度，输出时表示结果数据实际长度。原型ULONGDEVAPISKF_DigestUpdate(HANDLEhHash,BYTE*pbData,ULONG功能描述对多个分组的消息进行密码杂凑计算。调用SKF_DigestUpdate之前，应调用SKF_Di-gestInit初始化密码杂凑计算操作；调用SKF_DigestUpdate之后，应调用SKF_DigestFi-nal结束密码杂凑计算操作。参数hHash[IN]密码杂凑对象句柄。pbData[IN]指向消息数据的缓冲区。ulDataLen[IN]消息数据的长度。原型ULONGbpEVAPISKF_DigestFinal(HANDLEhHash,BYTE*pHashDala,ULONG功能描述结束多个分组消息的密码杂淡引算操作函密码杂淡结果保存到脂定的缓冲区。LtasHLcn返回杂决的长度果的长度原型ULONGDEVARISKF_MacInit(HANDLEhKey,BLOCKCIPHERPARAM*pMa功能描述初始化消息鉴别码计算操作，设置计算消息鉴别码的初始参数，并返回消息鉴别码句柄。参数hKey[IN]计算消息鉴别码的密钥句柄。pMacParam[IN]phMac[OUT]消息鉴别码对象句柄。返回值SAR_OK:成功。原型ULONGDEVAPISKF_Mac(HANDLEhMac,BYTE*pbData,ULONGulDataLen,BYTE*pbMacData,错误码。原型ULONGDEVAPISKF_MacUpdate(HANDLEhMac,BYT原型ULONGDEVAP原型ULONGDEVAPISKF_HMACInit(HANDLE功能描述三步式带密钥的数据杂凑运算的第一步。参数hKey[IN]密钥句柄。phHMac[OUT]HMAC对象句柄。返回值SAR_OK:成功。原型ULONGDEVAPISKF_HMAC(HANDLEhHMac,BYTE*pbData,ULONGulDataLength,BYTE*pbHashData,ULONG*pulHashLen)功能描述单包数据的带密钥的数据杂凑运算，对输入的明文进行杂凑运算。pbData[IN]缓冲区指针，指向明文数据。ulDataLongth[N]明文数据的长度。pbHashData[OUT]密码杂凑数据缓冲区指针，当此参数为NULL时，由pulHash-Lcn返回密码杂凑结果的长度。puiHashLenfIN,OUT]输人时表示结果数据缓冲区长度，输出时表示结果数据实际长度。返回值SAROK:成功原型功能描述三步式带密钥的数据泵淡运算的郅步对输人的明文进行杂淡运算。参数DNIHMAC对象句柄。其他：[IN]明文数据的长度。成功。原型功能描述参数返回值ULONGDEVAPISKF_HMACFinal(HANDLEhHMac,BYTE三步式带密钥的数据杂凑运算的第三步，杂凑运算结束返回结果。hHMac[IN]HMAC对象句柄。pbHMac[OUT]缓冲区指针，指向杂凑计算结果。pulHMacLength[OUT]杂凑计算结果的长度。SAR_OK:成功。参数hHandle[IN原型ULONGDEVAPISKF_GenExtRSAKey(DEVHANDLEhDev,ULONGulBitsLen,功能描述由设备生成RSA密钥对并明文输出。参数hDevpBlob[OUT]返回的私钥数据结构。原型ULONGDEVAPISKF_GenExtECCKey(DEVHANDLEhDev,ULONGECCPRIVATEKEYBLOB*pPrivate_key,ECCPUBLICKEYBLOB*pP功能描述由设备生成ECC密钥对并明文输出。参数hDevpPublick_key[OUT]返回的公钥数据结构。函数原型ULONGDEVAPISKF_ExtRSAPriKeyOperation(DEVHANDRSAPRIVATEKEYBLOB*pRSAPriKeyBlob,BYTE*pblnput,ULONGulInputLen,BYTE*pbOutput,ULONG*pulOutpRSAPriKeyBlob[IN]pbInput[IN]指向待运算putLen返回运算结果的实际长度。pulOutputLenRSA私钥运算结果的实际长度。返回值SAR_OK:成功。7.7.5ECC外来私钥解密ECCPRIVATEKEYBLOB*pECCPriKeyBlob,PECCCIPHERBLOBBYTE*pbPlainText,ULONG*pulPlai功能描述使用外部传入的ECC私钥对输入数据参数hDevpECCPriKeyBlob[IN]ECC私钥数据结构。pCipherText[IN]待解密的密文数据。pulPlainTextLen返回明返回值SAR_OK:成功。函数原型ULONGDEVAPISKF_ExtECECCPRIVATEKEYBLOB*pECCPriKeyBlob,BYTE*pbData,ULONGulDataLen,PECCSIGNATUREBLOBpSignaturc)参数hDevpECCPriKeyBlob[INpbData[IN]待签名数据。函数原型ULONGDEVAPISKF_ExtKeyEncrypt(HANDLEhDev,BYTE*pbKey,ULONGulKeyLen,BYTE*pbData,ULONGulDataLen,BYTE*pbEncryptedData,ULONGpbKey函数原型参数ULONGDEVAPISKF_ExtKeyDecrypt(HANDLEhDev,BYTE*pbKey,ULONGulKeyLen,BYTE*pbData,ULONGulDataLen,BYTE*pbEncryptedData,ULONGhDevpbKey原型ULONGDEVAPISKF_ExtHmac(HANDLEhDev,BYTE*pLength,BYTE*pbData,ULONGulDataLength,ULONGuAlgID,BYTE*pbHash-Data,ULONG*pulHashLen)ulDataLength[IN]明原型ULONGDEVAPISKF_Transmit(DEVHANDLEULONGulCommandLen,BYTE*pbData,ULONG*pulDataL参数hDevpbCommand[IN]设ulCommandLen[IN]命令长度。pbDatac)管理员权限：管理员PIN码验证通过后，获得管理员权限，管理员权限只作用于其所在的1)用户PIN码和管理员PIN码均具有最大重试次数，在创建应用时设定。当验证PIN码错误h)用户PIN码的修改应已取得用户权限，管理员PIN码的修改应已a)被认证方调用SKF_GenRandom函数从设备获取8字节随机数RND,并用0x00将其填充至a)PIN码长度应不少于6个字符；障方面应符合GM/T0028—2014中第8章的规定。(规范性)本文件定义的错误代码如表A.1所示。表A.1错误代码定义和说明说明成功失败异常锆误不支持的服务文件操作错误文件错误未初始化内存错误生成随机数错误表A.1错误代码定义和说明(续)说明对象未导出无事件错误设备已移除没有初始化用户口令文件已经存在空间不足文件不存在已达到最大可管理容器数密钥已被锁住容器不存在容器已存在密钥未被使用文件操作权限错误设备未认证(规范性)#defineSM9_MODULUS_BYTESLEN((SM9_MODULUSBITS_LEN+7)/8)typedefSM9MAsTPRIVATEKEYBLOBSM9SIGNMASTPRIVATEKEYBLOBtypedefSM9MASTPRIVATEREYBEOBSMOENCMASTPRIVATEKEYBLOB,*PSM9ENCMASTPRIV座Kb)数据项晶述见表B压数据项意义模数的位长度#defineSM9_XCOQRDINATE_BITS_LENSM9_MODULUSBITSLEN#defineSM9_XCOORDINATE_BYTESLEN((SM9xcOORDINATE_BITS_LEN+7)/8)=defineSM9_YCOORDINATEBITS_LEN=defineSM9_YCOORDINATE_BYTES_LEN((SM9_YCOORDINATE_BITS_LEN+7)/8)typedefstructStruct_SM9KEYBLOB2{cbXACoordinate[SM9_XCOORDINATcbXBCoordinate[SM9_XCOORDINATEBYTEcbYACoordinate[SM9_YCOORDINATE_BYTES_LEN];BYTEcbYBCoordinate[SM9_YCOORDINATE_BYTES_LEN];typedefSM9KEYBLOB2SM9SIGNMASTPUBLICKEYBLOB,其中，SM9_XCOORDINATE_BYTES_LEN为SM9签名主公钥X坐标的字节长度，值为32;SM9_YCOORDINATE_BYTES_LEN为SM9签名主公钥Y坐b)数据项描述见表B.2。意义值为2、3或4。当为4时cbYACoordinate、cbYACoordinate、cbYBBYTE数组曲线上点的X坐标高维BYTE数组曲线上点的X坐标低维BYTE数组曲线上点的Y坐标高维BYTE数组曲线上点的Y坐标低维a)类型定义typedefstructStruct_SM9KULONGulBitLen;BYTEcbXCoordinate[SM9_XCOORDINATE_BYTES_LBYTEcbYCoordinate[SM9_YCOORDINATE_BYTES_LtypedefSM9KEYBLOB1SM9ENCMASTPUBLICKE表B.3SM9加密主公钥数据结构意义值为2、3或4。当为4时cbYCoordiBYTE数组曲线上点的X坐标BYTE数组曲线上点的Y坐标typedefSM9KEYBLOB1SM9USERSIGNPRIVATEKEYBLOB,b)数据项描述见表B.4。表B.4SM9用户签名密钥数据结构意义值为2、3或4。当为4时cbYCoordinatc有效，当BYTE数组曲线上点的X坐标BYTE数组曲线上点的Y坐标a)类型定义typedefSM9KEYBLOB2SM9USERENCPRIVATEKEYBLOB,b)数据项描述见表B.5。表B.5SM9用户加密密钥数据结构意义值为2、3或4。当为4时cbYACoordinate、cbYBCoordinate有效，当为其他值时cbYACoordinate、cbYBBYTE数组曲线上点的X坐标高维BYTE数组曲线上点的X坐标低维BYTE数组曲线上点的Y坐标高维BYTE数组曲线上点的Y坐标低维typedefstructh[SM9_MODULUS_BYTES_LcbSXCoordinate[SM9_XCOORDINATEcbSYCoordinate[SM9_XCOORDINATEb)数据项描述见表B.6。意义hBYTE数组BYTE数组typedefstructStruct_SM9CIPHERBLOB{ULONGulAsymAlgId;cbXCoordinate[SM9_XCOORDINATEcbYCoordinate[SM9_YCOORDINATEb)数据项描述见表B.7。数据项意义typedefstructStruct_SM9KEYPACKAGEBLOB{BYTEcbXCoordinate[SM9_XCOORDINATE_BYTES_LEN];BYTEcbYCoordinate[SM9_YCOORDINAb)数据项描述见表B.8。意义BYTE数组BYTE数组typedefstructSM9KEYPACKAGEBLOBkey}SM9SIGNENCAPSULATEDKEYBLOB,*PSM9b)数据项描述见表B.9。数据项意义版本号，本版本为1一补满)对称算法加密的用户签名私钥KGC用于生成用户签名私钥的签名主公钥公钥用户标识用户标识长度用临时加密主公钥和用户的对称密钥的封装密文度的对称密钥typedefstructStruct_SM9SIGNENVELOPEDKEYBLOB{}SM9SIGNENVELOPEDKEYBLOB,*Pb)数据项描述见表B.10。数据项类型意义备注应为ECB模式(不填充补满)KGC用于生成用主公钥密主公钥用户标识用户标识长度typedefstructSKF_SM9ENCENCAPSULATEDKEYBLOB{cbEncryptedPriKey[SM9_MODULUS_}SM9ENCENCAPSULATEDKEYBLOB,*PSb)数据项描述见表B.11。数据项类型意义备注应为ECB模式(不填充补满)OB结构中的cbXACoordinatellKGC用于生成用户加密密钥的的加密主公钥户生成的临时用识长度的脚钥封装密交用萨根据ulSymmAlgID解封装出特定长度的对称密钥B.1.12SM9用户加密密钥数字信封保护结构lypedefstrucSKFSM9ENCENVELOPEDKEYBLOB{}SM9ENCENVELOPEDKEYBLOB,*b)数据项描述见表B.12。数据项意义版本号，本版本为1应为ECB模式(不填充补满)对称算法加密的用KGC用于生成用户加密密钥的的签名主公钥用户生成的临时加密主公钥用户标识用户标识长度用临时加密主公钥称密钥密文函数原型ULONGDEVAPISKF_ImportSM9SignMastPubKetion,PSM9SIGNMASTPUBLICKEYBLOBpSignMastPubKeyBlob)pSignMastPubKeyBlob函数原型ULONGDEVAPISKF_ImportSM9EncMastPubKey(HAPPtion,PSM9ENCMASTPUBLICKEYBLOBpEncMastPubKe功能描述参数返回值导入SM9加密主公钥。SAR_OK:成功。[IN]应用句柄。[IN]SM9加密主公钥数据结构。函数原型功能描述参数返回值ULONGDEVAPISKFExporISM9SignMastPubKey(HAPPLICATIONtion,PSM9SIGXMASTPUBLICKEYBLOBpSignMasbPubKeyBlob)导出SM9签名主公钥phApplieation[IN]应用句柄。pSignMastIubKeyBlob[OUT]SM9签名主公钥数据结构。其他错误码。B.2.4导出SM9加密主公钥函数原型功能描述参数返回值导入SM9加密主公确要应排句栖0U1SMo加密主公钥数据结构。函数原型ULONGDEVAPISKF_GenSM9EncMastKcyPair(HAPPLICATIONhApplication,PSM9ENCMASTPUBLICKEYBLOBpEncMastPubKeyBlob)功能描述生成SM9临时加密主密钥对并输出加密主公钥。参数phApplication[IN]应用句柄。返回值SAR_OK:成功。函数原型ULONGDEVAPISKF_ImportSM9SignEncapsulatedKey(HCONTAINERhPSM9SIGNENCAPSULATEDKEYBLOBpEncapsulatedKeyBl功能描述导入使用用户签名密钥对保护结构1保护的SM9用户签名私钥和签名主公钥。参数hContainer功能描述ULONGDEVAPISKF_ImportSM9SignEnvelopedKey(HCONTAINERhContainer,PSM9SIGNENVELOPEDKEYBLOBpEnvelopedKeyBlob)导入使用用户签名密钥对保护结构2保护的SM9用户签名私钥和签名主公钥。pEnvelopedKeyBlob[IN]函数原型ULONGDEVAPISKF_ImportSM9EncEncapsulatedKey(HC