GM-T 0016-2023 智能密碼鑰匙密碼應(yīng)用接口規(guī)范

代替GM/T0016—2012智能密碼鑰匙密碼應(yīng)用接口規(guī)范國(guó)家密碼管理局發(fā)布I 12規(guī)范性引用文件 13術(shù)語(yǔ)和定義 1 25結(jié)構(gòu)模型 25.1層次關(guān)系 2 36數(shù)據(jù)類型定義 46.1算法標(biāo)識(shí) 46.2基本數(shù)據(jù)類型 46.3常量定義 46.4復(fù)合數(shù)據(jù)類型 57接口函數(shù) 7.1設(shè)備管理 7.3應(yīng)用管理 7.4文件管理 7.5容器管理 7.6密碼服務(wù) 7.7驗(yàn)證調(diào)試 8接口使用要求 438.1設(shè)備使用階段 8.2權(quán)限管理 8.3其他安全要求 附錄A(規(guī)范性)錯(cuò)誤代碼定義 45附錄B(規(guī)范性)SM9應(yīng)用接口 附錄D(資料性)SM9編程范例 參考文獻(xiàn) 75Ⅲj)增加了VPN相關(guān)接口(見附錄C);本文件的目標(biāo)是為公鑰密碼基礎(chǔ)設(shè)施應(yīng)用體系框架下的智能密碼鑰匙設(shè)備制定統(tǒng)一的應(yīng)用接口12管理員PINadministratorPIN管理員的口令，為ASCII字符串。用戶的個(gè)人口令，為ASCIⅡ字符串。包括容器和文件的一種結(jié)構(gòu)，具備獨(dú)立的管理權(quán)限。4縮略語(yǔ)下列縮略語(yǔ)適用子禾文件API:應(yīng)用編程接口(ApplicationProgrammingInterface)ASCII:美國(guó)信息交換標(biāo)準(zhǔn)碼(AmericanStandardCodeforInformationInterchange)PKI:公朗基研設(shè)施PaubicKeyhntfastuctmc)PIN:個(gè)人身份識(shí)別碼CPersonalIdentheafonkanber)5結(jié)構(gòu)模型圖1所示。智能密碼鑰匙硬件接日所符合GM/f0027-20+E中6工的規(guī)定圖1接口在應(yīng)用層次關(guān)系中的位置3終端設(shè)備應(yīng)具有一個(gè)設(shè)備認(rèn)證密鑰。終端設(shè)備應(yīng)支持一個(gè)或多個(gè)應(yīng)用。應(yīng)用之間應(yīng)相互獨(dú)立。設(shè)備的邏輯結(jié)構(gòu)如圖2所示。應(yīng)用1應(yīng)用2應(yīng)用n權(quán)限狀態(tài)。管理員PIN和用戶PIN的校驗(yàn)操作可改變應(yīng)用權(quán)限狀態(tài)。一個(gè)應(yīng)用的邏輯結(jié)構(gòu)如圖3鑰對(duì)用于數(shù)字簽名和驗(yàn)證，會(huì)話密鑰用于數(shù)據(jù)加解密和MAC運(yùn)算。容器中存放SM2算法的密鑰對(duì)用戶PIN文件m會(huì)話密鑰容器146數(shù)據(jù)類型定義密碼算法標(biāo)識(shí)應(yīng)符合GM/T0006—2023中第6章的規(guī)定。字節(jié)數(shù)組應(yīng)使用高位字節(jié)在前(Big-Endian)的方式存儲(chǔ)和交換。基本數(shù)據(jù)類型定義見表1。表十一基本數(shù)據(jù)類型備注有符號(hào)16位整數(shù)例如，typedefunslgnedc字行型九在號(hào)8位整設(shè)備句柄數(shù)據(jù)常量標(biāo)識(shí)定義了在規(guī)范中用到的常量的取值。數(shù)據(jù)常量標(biāo)識(shí)的定義如表2所示。5常量名_stdcall函數(shù)調(diào)用方式01typedefstructStruct_Version{數(shù)據(jù)項(xiàng)應(yīng)符合表3的規(guī)定。意義次版本號(hào)typedefstruct6ULONGAlgSULONGAlgAULONGAlgHaULONGDevAULONGULONGFULONGMaxECCBuULONGMaxBu數(shù)據(jù)項(xiàng)應(yīng)符合表4的規(guī)定。數(shù)據(jù)項(xiàng)意義設(shè)備廠商信息以‘\0’為結(jié)束符的ASCII字符串發(fā)行廠商信息以‘\0'為結(jié)束符的ASCII字符串以‘\0'為結(jié)束符的ASCII字符串以‘\O'為結(jié)束符的ASCII字符串分組密碼算法標(biāo)識(shí)非對(duì)稱密碼算法標(biāo)識(shí)一設(shè)備總空間大小用戶可用空間大小能夠處理的ECC加密數(shù)據(jù)大小數(shù)據(jù)大小—typedefstructStruct_RSAPUBLICKEYBLOB{7BYTEModulus[MAX_RSA_MODULUS_LEN];BYTEPublicExponent[MAX_RSA_EXPONENT_數(shù)據(jù)項(xiàng)類型意義備注算法標(biāo)識(shí)號(hào)模數(shù)n=p*q實(shí)際長(zhǎng)度為BitLen/8字節(jié)#defineMAX_RSA_MODULU#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數(shù)據(jù)項(xiàng)意義算法標(biāo)識(shí)號(hào)實(shí)際長(zhǎng)度為BitLen/8字節(jié)一般為00010001實(shí)際長(zhǎng)度為BitLen/8字節(jié)typedefstructStruct_ECCPUBLICKEYBLOB{BYTEXCoordinate[ECC_MAX_XCOORDINATE_BITS_LEN/8];BYTEYCoordinate[ECC_MAX_YCOORDINATE_BITS_LEN/8];ECC_MAX_XCOORDINATE_LEN為ECC算法X坐標(biāo)的最大長(zhǎng)度；ECC_MAX_YCOORDINATE_LEN為ECC算法Y坐標(biāo)的最大長(zhǎng)度。數(shù)據(jù)項(xiàng)描述見表7。數(shù)據(jù)項(xiàng)意義曲線上點(diǎn)的X坐標(biāo)#defineECC_MAX_XCOORDINATE_BITS_LEN曲線上點(diǎn)的Y坐標(biāo)#defineECC_MAX_YCOORDINATE_BITS_LEN9typedefstructStruct_ECCPRIVATEKEYBLOB{BYTEPrivateKey[ECC_MAX_MODULUS_BITECC_MAX_MODULUS_BITS_LEN為E表8ECC私鑰數(shù)據(jù)結(jié)構(gòu)數(shù)據(jù)項(xiàng)意義私有密鑰#defineECC_MAX_MODULUS_BITS_LENtypedefstructStruct_ECCCIPHERBBYTEXCoordinate[ECC_MAX_XCOORDINATE_BITS_LEN/8];BYTEYCoordinate[ECC_MAX_XCOORDINATE_BITS_LEN/8];BYTEHASH[32];數(shù)據(jù)項(xiàng)描述見表9。數(shù)據(jù)項(xiàng)意義與y組成橢圓曲線上的點(diǎn)(x,y)與x組成橢圓曲線上的點(diǎn)(x,y)明文的雜湊值 6.4.9ECC簽名數(shù)據(jù)結(jié)構(gòu)typedefstructStruct_ECCSIGNATUREBLOB{BYTEr[ECC_MAX_XCOORDINATE_BITS_LEN/8];BYTEs[ECC_MAX_XCOORDINATE_BITS_LEN/8];ECC_MAX_MODULUS_BITS_LEN為ECC算法模數(shù)的最大長(zhǎng)度。數(shù)據(jù)項(xiàng)描述見表10。表10ECC簽名數(shù)據(jù)結(jié)構(gòu)數(shù)據(jù)項(xiàng)類型意義備注rtypedefstructStruciBEOCRCIPHEReARAM數(shù)據(jù)項(xiàng)描述見表11。表11分組密碼參數(shù)數(shù)據(jù)項(xiàng)意義初始向量實(shí)際長(zhǎng)度(按字節(jié)計(jì)算)反饋值的位長(zhǎng)度(按位計(jì)算)只針對(duì)OFB、CFB模式typedefstructStruct_ENVELOPEDKEYBLOB數(shù)據(jù)項(xiàng)意義的原文為ECCPRIVATEKEYBLOB加密密鑰對(duì)的公鑰一typedefstructStruct_FILEAT表13文件屬性意義文件名以‘\O'結(jié)束的ASCII字符串，最大長(zhǎng)度為32文件大小創(chuàng)建文件時(shí)定義的文件大小寫入權(quán)限寫入文件應(yīng)已取得的權(quán)限權(quán)限類型的定義見表14表14權(quán)限類型權(quán)限類型值說(shuō)明理員權(quán)限用主權(quán)限設(shè)備狀態(tài)的定義見表表設(shè)備狀態(tài)設(shè)備狀態(tài)值說(shuō)明設(shè)備不存在設(shè)備存在設(shè)備狀態(tài)未知接口函數(shù)所返回的錯(cuò)誤代碼應(yīng)符合附錄A中的規(guī)定。7接口函數(shù)7.1設(shè)備管理設(shè)備管理主要完成設(shè)備的插拔事件處理、枚舉設(shè)備、連接設(shè)備、斷開連標(biāo)簽、獲取設(shè)備信息、鎖定設(shè)備、解鎖設(shè)備的操作。設(shè)備管理系列函數(shù)見表16。表16設(shè)備管理系列函數(shù)函數(shù)名稱斷開連接獲取設(shè)備信息原型ULONGDEVAPISKF_WaitForDevEvent(LPSTRszDevName,ULONGNameLen,ULONG*pulEv參數(shù)szDevName[OUT]pulEvent返回值SAR_OK:成功。原型ULONGDEVAPISKF_Cancel功能描述該函數(shù)取消等待設(shè)備插入或者拔除事件。原型ULONGDEVAPISKF_EnumDev(BOOLbPresent,LPSTRszNbPresent[IN]為TRUE表示取當(dāng)前設(shè)備狀態(tài)為存在的設(shè)備列表。為FALSE[OUT]設(shè)備名稱列表。如果該參數(shù)為NULL,將由pulSize返回該列原型ULONGDphDev[OUT]原型ULONGDEVAPISKF_DisConnectDev(DEVHANDLEhDev)原型ULONGDEVAPISKF_GetDevState(LPSTRszDpulDevState[OUT]返回設(shè)備狀態(tài)。原型ULONGDEVAPISKF_SetLabel(DEVHANDLEhDev,LPSTRszLabel)功能描述設(shè)置設(shè)備標(biāo)簽。參數(shù)hDevszLabel[IN]設(shè)備標(biāo)簽字符串。該字符串應(yīng)小于32字節(jié)。ULONGDEVAPISKF_GetDevInfo(DEVHANULONGDEVAPISKF_LockDev(DEVHANDLEhDev,ULONG函數(shù)名稱修改設(shè)備認(rèn)證密鑰獲得PIN碼信息原型ULONGDEVAPISKF_ChangeDevAuthKey(DEVHANDLEhDev,BYTE*pbKeyCi-pher,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應(yīng)用管理系列函數(shù)創(chuàng)建應(yīng)用關(guān)閉應(yīng)朋原型ULoNGDEVAPISKF_CPSTRszAdminPin,DWORDdwAdminPinRetryCount,LPSTRdwOserPinBetryCount,DWORDdwCreateFileRights,HAPPLiCATiON*phApplszAppNameN]應(yīng)用名稱szAdminPin[IN]管理員PIN。phApplication[OUT]應(yīng)用的句柄。返回值SAR_OK:原型ULONGDEVAPISKF_EnumApplication(參數(shù)hDev[IN]連接設(shè)備時(shí)返回的設(shè)備句柄。原型ULONGDEVAPISKF_DeleteApplication(DEV參數(shù)hDev原型ULONGDEVAPISKF_OpenApplication(DEVHAN參數(shù)hDevphApplication原型ULONGDEVAPISKF_CloseApplication(HAPPLICATI函數(shù)名稱獲取文件信息原型ULONGDEVAPName,ULQNGaieSize,Gulrights,功能描述創(chuàng)建文件時(shí)要指定文件的名稱大小，以及義件的讀寫權(quán)限。szFileName文件名稱。度不應(yīng)人132個(gè)字ulFleSize文件大小種權(quán)限的或值。ulWritekoghts[IN]文件寫權(quán)限，權(quán)限類型應(yīng)符合6.41的要求。取值可為各原型ULONGDEVAPISKF_DeleteFile(HAPPLICATIONhApplication,LPSName)參數(shù)hApplication[IN]要?jiǎng)h除文件所在的應(yīng)用句柄。szFileName[IN]要?jiǎng)h原型ULONGDEVAPISKF_EnumFiles(HAPPLICATIONhApplication,LPSTRszFile原型ULONGDEVAPISKF_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:成功。其他：錯(cuò)誤碼。出數(shù)字證書操作。容器管理函數(shù)見表20。表20容器管理系列函數(shù)函數(shù)名稱獲得容器類型導(dǎo)入數(shù)字證書導(dǎo)出數(shù)字證書原型ULONGDEVAPISKF_CreateContainer(HAContainerName,HCONTAINER*phContainer)原型ULONGDEVAPISKF_DeleteContain原型ULONGDEVAPISKF_OpenContaitainerName,HCONTAINERphContainer原型ULONGDEVAPISKF_CloseContain原型ULONGDEVAPISKF_EnumContaincr(HAPPLICATIONhApplicatio原型ULONGDEVAPISKF_GelContainerType(HCONTAINERhContainer,ULONG*pul-功能描述獲取容器的類型。原型ULONGDEVAPISKF_ImportCertificate(HCONTFlag,BYTE*pbCert,ULONGul原型ULONGDEVAPISKF_ExportCertificate(HCONTAINERhContaFlag,BYTE*pbCert,ULONG*pulCertLen)成功。錯(cuò)誤碼。功能。密碼服務(wù)系列函數(shù)見表21。表21密碼服務(wù)系列函數(shù)函數(shù)名稱功能RSA簽名ECC簽名SKF_GenerateAgreementDECC生成密鑰協(xié)商參數(shù)并輸出SKF_GenerateAgreementDataAnd導(dǎo)出公鑰導(dǎo)入會(huì)話密鑰單包數(shù)據(jù)加密多包數(shù)據(jù)加密結(jié)束加密表21密碼服務(wù)系列函數(shù)(續(xù))函數(shù)名稱功能單包數(shù)據(jù)解密多包數(shù)據(jù)解密結(jié)束解密多包數(shù)據(jù)密碼雜湊結(jié)束密碼雜湊多包數(shù)據(jù)消息鑒別碼運(yùn)算帶密鑰的雜湊運(yùn)算初始化帶密銅的單包雜淡運(yùn)算帶密鑰包雜湊運(yùn)算帶密釩的湊運(yùn)算結(jié)策原型UONCDEVAPISKF_GenRandom(DEVHANDLEhDev,BXTE*ULONGunRandomLen)功能描述產(chǎn)生指定長(zhǎng)度的隨機(jī)數(shù)。參數(shù)hDev[IN]設(shè)備句柄。pbRandom[OUT]返回的隨機(jī)數(shù)。ulRandomLen[IN]隨機(jī)數(shù)長(zhǎng)度返回值SAR_OK:成功。其他：錯(cuò)誤碼。7.6.3生成RSA簽名密鑰對(duì)原型ULONGDEVAPISKF_GenRSAKeyPair(HCONTAINERhContainer,ULONGulBit-功能描述生成RSA簽名密鑰對(duì)并輸出簽名公鑰。參數(shù)hContainer[IN]容器句柄。ulBitsLen[IN]密鑰模長(zhǎng)。pBlob[OUT]返回的RSA公鑰數(shù)據(jù)結(jié)構(gòu)。返回值SAR_OK:成功。7.6.4導(dǎo)入RSA加密密鑰對(duì)HCONTAINERhContainer,ULONGulSymAlgId,BYTE*pbWrappedKey,ULONGulWrapBYTE*pbEncryptedData,ULO功能描述導(dǎo)入RSA加密公私鑰對(duì)。參數(shù)hContainer[IN]容ulSymAlgIdpbWrappedKey[IN]使用該容器內(nèi)簽名公鑰保護(hù)的對(duì)稱算法密鑰。ulWrappedKeyLen[IN]保pbEncryptedDataulEncryptedDataLcn[IN]對(duì)稱算法密鑰保護(hù)的RSA加密公私鑰對(duì)長(zhǎng)度。返回值SAR_OK:成功。7.6.5RSA簽名原型ULONGDEVAPISKF_RSASignDaULONGulDataLen,BYTE*pbSignature,ULONG功能描述[IN]簽名數(shù)據(jù)長(zhǎng)度，應(yīng)不大于RSA密鑰模長(zhǎng)-11。成功。原型ULONGDEVAPISKF_RSAVerify(HCONTAINERhCULONGulDataLen,BYTE*pbSignature,ULONGulSignLen)功能描述使用hContainer指定容器的簽名公鑰，進(jìn)行驗(yàn)證RSA簽名操作。參數(shù)hDev[IN]設(shè)備句柄。pRSAPubKeyBlob[IN]RSA公鑰數(shù)據(jù)結(jié)構(gòu)。pbData[IN]待驗(yàn)證簽名的數(shù)據(jù)。ulDataLen[IN]數(shù)據(jù)長(zhǎng)度，應(yīng)不大于公鑰模長(zhǎng)-11。pbSignature[IN]待驗(yàn)證的簽名值。ulSignLen[IN]簽名值長(zhǎng)度，應(yīng)為公鑰模長(zhǎng)。返回值SAR_OK:成功。其他：錯(cuò)誤碼。7.6.7RSA生成導(dǎo)出會(huì)話密鑰原型ULONGDEVAPISKF_RSAExportSessionKey(HCONTAINERhContainer,ULONGulAlgId,RSAPUBLICKEYBLOB*pPubKey,BYTE*pbData,UIONG*pulDataLen,HANDLEphSessionKey)功能描述牛成會(huì)話密鑰并用外部RSA公鑰加密輸出。參數(shù)hConzginerTN容器句柄。ulAigIdNI會(huì)話密班算法標(biāo)。封pulDataLen[INT]輸人表示會(huì)話密鑰密文數(shù)據(jù)緩沖區(qū)長(zhǎng)度，輸出時(shí)表公話密鑰密文的實(shí)際長(zhǎng)度phSessionKeyIQUT]導(dǎo)出的密鑰年病返回值SAR_OK:疲功。其他借誤碼。7.6.8外來(lái)RSA公鑰運(yùn)算原型ULONGDEVAPISKF_ExtRSAPubKeyOperation(DEyHANDLEhDev,RSAPUBLICKEYBLOB*pRSAPubKeyBlob,BYTEpbInput,ULONGulInputLen,BYTE*pbOutput,ULONG*pulOut功能描述使用外部傳入的RSA公鑰對(duì)輸入數(shù)據(jù)做公鑰運(yùn)算并輸出結(jié)果。參數(shù)hDev[IN]設(shè)備句柄。pRSAPubKeyBlob[IN]RSA公鑰數(shù)據(jù)結(jié)構(gòu)。pbInput[IN]指向待運(yùn)算的原始數(shù)據(jù)緩沖區(qū)。ulInputLen[IN]待運(yùn)算原始數(shù)據(jù)的長(zhǎng)度，應(yīng)為公鑰模長(zhǎng)。pbOutput[OUT]指向RSA公鑰運(yùn)算結(jié)果緩沖區(qū)，如果該參數(shù)為NULL,則由pulOutputLen返回運(yùn)算結(jié)果的實(shí)際長(zhǎng)度。pulOutputLen[IN,OUT]輸入時(shí)表示pbOutput緩沖區(qū)的長(zhǎng)度，輸出時(shí)表示RSA公鑰運(yùn)算結(jié)果的實(shí)際長(zhǎng)度。返回值SAR_OK:成功。其他：錯(cuò)誤碼。功能描述ULONGDEVAPISKF_GenECCKeyPair(HCONTAINERhContainer,ULONGulAl-hContainer[IN]密鑰容器句柄。pBlob[OUT]返回ECC公鑰數(shù)據(jù)結(jié)構(gòu)。7.6.10導(dǎo)入ECC加密密鑰對(duì)原型ULONGDEVAPISKF_ImportECCKeyPaiPENVELOPEDKEYBLOBpEnvelopedKeyBlob)功能描述導(dǎo)入ECC公私鑰對(duì)。參數(shù)hContainerpEnvelopedKeyBlob[IN]受保護(hù)的原型ULONGDEVAPISKF_ECCSignData(ULONGulDataLen,PECCSIGNATUREBLOBpSig功能描述ECC數(shù)字簽名。采用ECC算法和指定私鑰hKey,對(duì)指定數(shù)據(jù)pbData進(jìn)行數(shù)字簽名。簽名后的結(jié)果存放到pSignature中。參數(shù)hContainer[IN]原型ULONGDEVAPISKF_ECCVerify(DEVHANDLEhDev,pECCPubKeyBlob,BYTE*pbData,ULONGulDataLen,PECCSIGNATURpECCPubKeyBlob[IpSignature原型ULONGDEVAPISKF_ECCExportSessionKey(HCONTulAlgId,ECCPUBLICKEYBLOB*pPubKey,PECCCIPHERBLOBpData,HAN功能描述生成會(huì)話密鑰并用外部公鑰加密導(dǎo)出。ulAlgIdpPubKey[IN]外部輸入的公鑰結(jié)構(gòu)。pData[OUT]會(huì)話密鑰密文。phSessionKey[OUT]返回值SAR_OK:成功。其他：錯(cuò)誤碼。原型ULONGDEVAPISKF_ExtECCEncrypt(DEVHANDLEhDECCPUBLICKEYBLOB*pECCPubKeyBlob,BYTE*pbPlainText,ULONGulPlain-TextLen,PECCCIPHERBLOBpCipherText)功能描述使用外部傳入的ECC公鑰對(duì)輸入數(shù)據(jù)做加密運(yùn)算并輸出結(jié)果。參數(shù)hDevpECCPubKeyBlob[IN]pbPlainTextulPlainTextLen[IN]pCipherText[其他：錯(cuò)誤碼。原型ULONGDEVAPISKF_GenerateAgreementDataWithECC(HCONTAINERhCon-ULONGulAlgId,ECCPUBLICKEYBLOB*pContaincrECCPubKeyBlob,ECCPUBLICKEYBLOB*pTempECCPubKeyBlob,BYTE*pbID,ULONGulIDLen,ulAlgIdpTempECCPubKeyBlob[OUT]發(fā)起方臨時(shí)ECC公鑰。pbID[IN]發(fā)起方的ID。phAgreementHandle[OUT]返回的密鑰協(xié)商句柄。原型：ULONGDEVAPISKF_GenerateKeyWithECC(HANDLEhAgreementHandle,ECCPUBLICKEYBLOB*pECCPuECCPUBLICKEYBLOB*pTempECCPBYTE*pbID,ULONGulIDLen,HAND參數(shù)：hAgreementHandlepECCPubKeyBlob[IN]外部輸入的響應(yīng)方ECC公鑰。pTempECCPubKeyBlob[IN]外部輸入的響應(yīng)方臨時(shí)ECC公鑰。pbID[IN]響應(yīng)方的ID。phKeyHandle[OUT]返回的密鑰句柄。原型：ULONGDEVAPISKF_GenerateAgreementDataAndKeyWithECC(HANDLEhCon-tainer,ULONGulAlgId,ECCPUBLICKEYBLOB*pSponsorECCPubKeyBlob,ECCPUBLICKEYBLOB*pSponsorTempECCPECCPUBLICKEYBLOB*pTempECCPBYTE*pbID,ULONGulIDLen,BYTE*pbSponsorID,ULONGulSponsorIDLen,參數(shù)：hContainerulAlgId[IN]會(huì)話密鑰算法標(biāo)識(shí)。pSponsorECCPubKeyBlob[IN]發(fā)起方的ECC公鑰。pSponsorTempECCPubKeyBlob[IN]發(fā)起方的臨時(shí)ECC公鑰。pTempECCPubKeyBlob[OUT]響應(yīng)方的臨時(shí)ECC公鑰。pbSponsorID[IN]發(fā)起方的ID。phKeyHandle[OUT]返回的對(duì)稱算法密鑰句柄。返回值SAR_OK:成功。原型ULONGDEVAPISKF_ExportPublicKey(HCONTAINERFlag,BYTE*pbBlob,ULONG*pulBpbBlob[OUT]指向RSA公鑰結(jié)構(gòu)(RSAPUBLICKEYBLOB),或ECC公鑰結(jié)構(gòu)(ECCPUBLICKEYBLOB),或SM9用戶標(biāo)識(shí)(BYTE數(shù)組),如果見附錄D。pulBlobLen[IN,O原型ULONGDEVAPISKF_ImportSessionKey(HCONTAINERhContainer,ULONGulAl-gId,BYTE*pbWrapedData,ULONGulWrapedLen,HANDLE*phKey)參數(shù)hContainerulAlgId[IN]會(huì)話密鑰算法標(biāo)識(shí)。密文數(shù)據(jù)PAIRKEYPACKAGEBLOB。原型ULONGDEVAPISKF_EncryptInit(HANDLEhKey,BLOCKCIPHERPARAMEn-ULONGDEVAPISKF_Encrypt(HANDLEhKey,BYTE*pbData,ULONGulDat-aLen,BYTE*pbEncryptedData,ULONG*pulEncryptedLen)于先調(diào)用SKF_EncryptUpda返回值SAR_OK:成功。其他：錯(cuò)誤碼。原型ULONGDEVAPISKF_EncryptUpdate(HANDLEhKey,BYTE*pbData,ULONGul-DataLen,BYTE*pbEncryptedData,ULONG功能描述多個(gè)數(shù)據(jù)包的加密操作。用指定加密密鑰對(duì)指定數(shù)據(jù)進(jìn)行加密，被加密的數(shù)據(jù)包含多個(gè)數(shù)據(jù)包，加密后的密文保存到指定的緩沖區(qū)中。SKF_EncryptUpdate對(duì)數(shù)據(jù)進(jìn)行加密，SKF_EncryptUpdate處理全部數(shù)據(jù)包之后，應(yīng)調(diào)用SKF_EncryptFinal結(jié)束加密操作。參數(shù)N]待加密數(shù)據(jù)。pbEncryptedData[OUT]加密后的數(shù)據(jù)緩沖區(qū)指針。pulEncryptedLen[OUT]返回加密后的數(shù)據(jù)長(zhǎng)度。其他：錯(cuò)醫(yī)碼原型功能描述結(jié)束多個(gè)分維數(shù)擁的加密，返，余加一果。先調(diào)用SKFBncryptmit初始化加密操作，再調(diào)用SkTErptOpdate對(duì)多個(gè)分組數(shù)據(jù)進(jìn)行加密取后調(diào)用SkFEncryptFinal結(jié)束多個(gè)分組數(shù)的加藍(lán)參數(shù)返回值[OUT]加密結(jié)果的緩沖區(qū)。[OUT]加密結(jié)果的長(zhǎng)度。原型ULONGDEVAPISKF_DecryptInit(HANDLEhKey,BLOCKCIPHERPARAMDe-功能描述數(shù)據(jù)解密初始化，設(shè)置解密密鑰相關(guān)參數(shù)。調(diào)用SKF_DecryptInit之后，可調(diào)用SKF_De-crypt對(duì)單個(gè)分組數(shù)據(jù)進(jìn)行解密，也可多次調(diào)用SKF_DecryptUpdate之后再調(diào)用SKF_De-cryptFinal完成對(duì)多個(gè)分組數(shù)據(jù)的解密。參數(shù)hKey[IN]解密密鑰句柄。的位長(zhǎng)度。返回值SAR_OK:成功。其他：錯(cuò)誤碼。原型ULONGDEVAPISKF_DecrypulEncryptedLen,BYTE*pbData,ULONG*pulDa于先調(diào)用SKF_DecryptUpda參數(shù)hKcy[IN]返回值SAR_OK:原型ULONGDEVAPISKF_DecryptUpdate(HANULONGulEncryptedLen,BYTE*pbData,ULONG*pulDapbData[OUT]指向解密后的數(shù)據(jù)緩沖區(qū)指針。返回值SAR_OK:原型ULONGDEVAPISKF_D參數(shù)hKey[I[OUT]指向解密結(jié)果的緩沖區(qū)，如果此參數(shù)為NUpulDecryptedDataLen返回解密結(jié)果的長(zhǎng)度。[IN,OUT]輸入時(shí)表示pbDecryptedData緩沖區(qū)的長(zhǎng)度，輸出時(shí)表示解密結(jié)果的長(zhǎng)度。返回值SAR_OK:成功。其他：錯(cuò)誤碼。原型ULONGDEVAPISKF_DigestInit(DEVHANDLEhDev,ULONGulAlgID,功能描述初始化密碼雜湊計(jì)算操作，指定計(jì)算密碼雜湊的算法。參數(shù)hDev[IN]連接設(shè)備時(shí)返回的設(shè)備句柄。ulAlgID[IN]密碼雜湊算法標(biāo)識(shí)。pFubKey[IN]簽名者公鑰。當(dāng)ulAlgID為SGD_SM3時(shí)有效。phHash00T]密碼雜湊對(duì)象何柄。其他：儲(chǔ)誤明。。7.6.29單包數(shù)據(jù)密碼雜湊uloNGIEVAPISKEDgstIHANDEEhlasb,BYTIGspbData,uLoNGulDat-原型aLen,BYTE*pbHashD功能描述對(duì)單包的消息進(jìn)行密碼雜湊計(jì)算。調(diào)用SKF_Digest之前，應(yīng)調(diào)用SKF_DigestInit初始化密碼雜湊計(jì)算操作。SKF_Digest等價(jià)于多次調(diào)用SKFDigestUpdate之后再調(diào)用SKF參數(shù)hHash[IN]密碼雜湊對(duì)象何柄。pbDataN]指向消息數(shù)據(jù)的緩神區(qū)。ulDataLen[IN]消息數(shù)據(jù)的長(zhǎng)度。pbHashData[OUT]密碼雜湊數(shù)據(jù)緩沖區(qū)指針，當(dāng)此參數(shù)為NULL時(shí)，由pul-HashLen返回密碼雜湊結(jié)果的長(zhǎng)度。pulHashLen[IN,OUT]輸入時(shí)表示結(jié)果數(shù)據(jù)緩沖區(qū)長(zhǎng)度，輸出時(shí)表示結(jié)果數(shù)據(jù)實(shí)際長(zhǎng)度。返回值SAR_OK:成功。其他：錯(cuò)誤碼。原型ULONGDEVAPISKF_DigestUpdate(HANDLEhHash,BYTE*pbData,ULONG功能描述對(duì)多個(gè)分組的消息進(jìn)行密碼雜湊計(jì)算。調(diào)用SKF_DigestUpdate之前，應(yīng)調(diào)用SKF_Di-gestInit初始化密碼雜湊計(jì)算操作；調(diào)用SKF_DigestUpdate之后，應(yīng)調(diào)用SKF_DigestFi-nal結(jié)束密碼雜湊計(jì)算操作。參數(shù)hHash[IN]密碼雜湊對(duì)象句柄。pbData[IN]指向消息數(shù)據(jù)的緩沖區(qū)。ulDataLen[IN]消息數(shù)據(jù)的長(zhǎng)度。原型ULONGbpEVAPISKF_DigestFinal(HANDLEhHash,BYTE*pHashDala,ULONG功能描述結(jié)束多個(gè)分組消息的密碼雜淡引算操作函密碼雜淡結(jié)果保存到脂定的緩沖區(qū)。LtasHLcn返回雜決的長(zhǎng)度果的長(zhǎng)度原型ULONGDEVARISKF_MacInit(HANDLEhKey,BLOCKCIPHERPARAM*pMa功能描述初始化消息鑒別碼計(jì)算操作，設(shè)置計(jì)算消息鑒別碼的初始參數(shù)，并返回消息鑒別碼句柄。參數(shù)hKey[IN]計(jì)算消息鑒別碼的密鑰句柄。pMacParam[IN]phMac[OUT]消息鑒別碼對(duì)象句柄。返回值SAR_OK:成功。其他：錯(cuò)誤碼。原型ULONGDEVAPISKF_Mac(HANDLEhMac,BYTE*pbData,ULONGulDataLen,BYTE*pbMacData,其他：錯(cuò)誤碼。原型ULONGDEVAPISKF_MacUpdate(HANDLEhMac,BYT原型ULONGDEVAP原型ULONGDEVAPISKF_HMACInit(HANDLE功能描述三步式帶密鑰的數(shù)據(jù)雜湊運(yùn)算的第一步。參數(shù)hKey[IN]密鑰句柄。phHMac[OUT]HMAC對(duì)象句柄。返回值SAR_OK:成功。其他：錯(cuò)誤碼。原型ULONGDEVAPISKF_HMAC(HANDLEhHMac,BYTE*pbData,ULONGulDataLength,BYTE*pbHashData,ULONG*pulHashLen)功能描述單包數(shù)據(jù)的帶密鑰的數(shù)據(jù)雜湊運(yùn)算，對(duì)輸入的明文進(jìn)行雜湊運(yùn)算。緩沖區(qū)指針，指向明文數(shù)據(jù)。明文數(shù)據(jù)的長(zhǎng)度。返回值puiHashLen其他：[OUT]密碼雜湊數(shù)據(jù)緩沖區(qū)指針，當(dāng)此參數(shù)為NULL時(shí)，由pulHash-Lcn返回密碼雜湊結(jié)果的長(zhǎng)度。fIN,OUT]輸人時(shí)表示結(jié)果數(shù)據(jù)緩沖區(qū)長(zhǎng)度，輸出時(shí)表示結(jié)果數(shù)據(jù)實(shí)際長(zhǎng)度。原型功能描述三步式帶密鑰的數(shù)據(jù)泵淡運(yùn)算的郅步對(duì)輸人的明文進(jìn)行雜淡運(yùn)算。參數(shù)HHMacDNIHMAC對(duì)象句柄。ulDataLength[IN]明文數(shù)據(jù)的長(zhǎng)度。返回值SAR_OK:成功。原型ULONGDEVAPISKF_HMACFinal(HANDLEhHMac,BYTE*pbHMac,ULONG功能描述三步式帶密鑰的數(shù)據(jù)雜湊運(yùn)算的第三步，雜湊運(yùn)算結(jié)束返回結(jié)果。參數(shù)hHMac[IN]HMAC對(duì)象句柄。pbHMac[OUT]緩沖區(qū)指針，指向雜湊計(jì)算結(jié)果。pulHMacLength[OUT]雜湊計(jì)算結(jié)果的長(zhǎng)度。返回值SAR_OK:成功。其他：錯(cuò)誤碼。參數(shù)hHandle[IN原型ULONGDEVAPISKF_GenExtRSAKey(DEVHANDLEhDev,ULONGulBitsLen,功能描述由設(shè)備生成RSA密鑰對(duì)并明文輸出。參數(shù)hDevpBlob[OUT]返回的私鑰數(shù)據(jù)結(jié)構(gòu)。功能描述ULONGDEVAPISKF_GenExtECCKey(DEVHANDLEhDev,ULONGulBitsLen,ECCPRIVATEKEYBLOB*pPrivate_key,ECCPUBLICKEYBLOB*pPhDev函數(shù)原型ULONGDEVAPISKF_ExtRSAPriKeyOperation(DEVHANDRSAPRIVATEKEYBLOB*pRSAPriKeyBlob,BYTE*pblnput,ULONGulInputLen,BYTE*pbOutput,ULONG*pulOutpRSAPriKeyBlob[IN]pbInput[IN]指向待運(yùn)算putLen返回運(yùn)算結(jié)果的實(shí)際長(zhǎng)度。pulOutputLenRSA私鑰運(yùn)算結(jié)果的實(shí)際長(zhǎng)度。返回值SAR_OK:成功。7.7.5ECC外來(lái)私鑰解密ECCPRIVATEKEYBLOB*pECCPriKeyBlob,PECCCIPHERBLOBBYTE*pbPlainText,ULONG*pulPlai功能描述使用外部傳入的ECC私鑰對(duì)輸入數(shù)據(jù)pbPlainText[IN]待解密的密文數(shù)據(jù)。pulPlainTextLen返回明返回值SAR_OK:成功。函數(shù)原型ULONGDEVAPISKF_ExtECECCPRIVATEKEYBLOB*pECCPriKeyBlob,BYTE*pbData,ULONGulDataLen,PECCSIGNATUREBLOBpSignaturc)參數(shù)hDevpECCPriKeyBlob[INpbData[IN]待簽名數(shù)據(jù)。函數(shù)原型ULONGDEVAPISKF_ExtKeyEncrypt(HANDLEhDev,BYTE*pbKey,ULONGulKeyLen,BYTE*pbData,ULONGulDataLen,BYTE*pbEncryptedData,ULONG參數(shù)hDevpbData[IN]待加密數(shù)據(jù)。函數(shù)原型ULONGDEVAPISKF_ExtKeyDecrypt(HANDLEhDev,BYTE*pbKey,ULONGulKeyLen,BYTE*pbData,ULONGulDataLen,BYTE*pbEncryptedData,ULONG參數(shù)hDev[IN]設(shè)備句柄。pbKeypbData原型ULONGDEVAPISKF_ExtHmac(HANDLEhDev,BYTE*pLength,BYTE*pbData,ULONGulDataLength,ULONGuAlgID,BYTE*pbHash-Data,ULONG*pulHashLen)ulDataLength[IN]明原型ULONGDEVAPISKF_Transmit(DEVHANDLEULONGulCommandLen,BYTE*pbData,ULONG*pulDataL參數(shù)hDevpbCommand[IN]ulCommandLen[IN]命令長(zhǎng)度。pbDatac)管理員權(quán)限：管理員PIN碼驗(yàn)證通過(guò)后，獲得管理員權(quán)限，管理員權(quán)限只作用于其所在的1)用戶PIN碼和管理員PIN碼均具有最大重試次數(shù)，在創(chuàng)建應(yīng)用時(shí)設(shè)定。當(dāng)驗(yàn)證PIN碼錯(cuò)誤h)用戶PIN碼的修改應(yīng)已取得用戶權(quán)限，管理員PIN碼的修改應(yīng)已a(bǔ))被認(rèn)證方調(diào)用SKF_GenRandom函數(shù)從設(shè)備獲取8字節(jié)隨機(jī)數(shù)RND,并用0x00將其填充至a)PIN碼長(zhǎng)度應(yīng)不少于6個(gè)字符；障方面應(yīng)符合GM/T0028—2014中第8章的規(guī)定。 (規(guī)范性)本文件定義的錯(cuò)誤代碼如表A.1所示。表A.1錯(cuò)誤代碼定義和說(shuō)明說(shuō)明成功失敗異常鋯誤不支持的服務(wù)文件操作錯(cuò)誤文件錯(cuò)誤未初始化內(nèi)存錯(cuò)誤生成隨機(jī)數(shù)錯(cuò)誤表A.1錯(cuò)誤代碼定義和說(shuō)明(續(xù))說(shuō)明對(duì)象未導(dǎo)出無(wú)事件錯(cuò)誤設(shè)備已移除沒(méi)有初始化用戶口令文件已經(jīng)存在空間不足文件不存在已達(dá)到最大可管理容器數(shù)密鑰已被鎖住容器不存在容器已存在密鑰未被使用文件操作權(quán)限錯(cuò)誤設(shè)備未認(rèn)證 (規(guī)范性)#defineSM9_MODULUS_BYTESLEN((SM9_MODULUSBITS_LEN+7)/8)typedefSM9MAsTPRIVATEKEYBLOBSM9SIGNMASTPRIVATEKEYBLOBtypedefSM9MASTPRIVATEREYBEOBSMOENCMASTPRIVATEKEYBLOB,*PSM9ENCMASTPRIV座Kb)數(shù)據(jù)項(xiàng)晶述見表B壓數(shù)據(jù)項(xiàng)意義模數(shù)的位長(zhǎng)度#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{ULONGulCompressTypc;ULONGulBitLen;BYTEcbXACoordinate[SM9_XCOORDINATE_BYTES_LEN];BYTEcbXBCoordinate[SM9_XCOORDINATE_BYTES_LEN];BYTEcbYACoordinate[SM9_YCOORDINATE_BYTES_LEN];BYTEcbYBCoordinate[SM9_YCOORDINATE_BYTES_LEN];typedefSM9KEYBLOB2SM9SIGNMASTPUBLICKEYBLOB,其中，SM9_XCOORDINATE_BYTES_LEN為SM9簽名主公鑰X坐標(biāo)的字節(jié)長(zhǎng)度，值為32;SM9_YCOORDINATE_BYTES_LEN為SM9簽名主公鑰Y坐b)數(shù)據(jù)項(xiàng)描述見表B.2。意義值為2、3或4。當(dāng)為4時(shí)cbYACoordinate、cbYACoordinate、cbYBBYTE數(shù)組曲線上點(diǎn)的X坐標(biāo)高維BYTE數(shù)組曲線上點(diǎn)的X坐標(biāo)低維BYTE數(shù)組曲線上點(diǎn)的Y坐標(biāo)高維BYTE數(shù)組曲線上點(diǎn)的Y坐標(biāo)低維a)類型定義typedefstructStruct_SM9KULONGulBitLen;BYTEcbXCoordinate[SM9_XCOORDINATE_BYTES_LBYTEcbYCoordinate[SM9_YCOORDINATE_BYTES_LtypedefSM9KEYBLOB1SM9ENCMASTPUBLICKE表B.3SM9加密主公鑰數(shù)據(jù)結(jié)構(gòu)意義值為2、3或4。當(dāng)為4時(shí)cbYCoordiBYTE數(shù)組曲線上點(diǎn)的X坐標(biāo)BYTE數(shù)組曲線上點(diǎn)的Y坐標(biāo)typedefSM9KEYBLOB1SM9USERSIGNPRIVATEKEYBLOB,b)數(shù)據(jù)項(xiàng)描述見表B.4。表B.4SM9用戶簽名密鑰數(shù)據(jù)結(jié)構(gòu)意義值為2、3或4。當(dāng)為4時(shí)cbYCoordinatc有效，當(dāng)BYTE數(shù)組曲線上點(diǎn)的X坐標(biāo)BYTE數(shù)組曲線上點(diǎn)的Y坐標(biāo)a)類型定義typedefSM9KEYBLOB2SM9USERENCPRIVATEKEYBLOB,b)數(shù)據(jù)項(xiàng)描述見表B.5。表B.5SM9用戶加密密鑰數(shù)據(jù)結(jié)構(gòu)意義值為2、3或4。當(dāng)為4時(shí)cbYACoordinate、cbYBCoordinate有效，當(dāng)為其他值時(shí)cbYACoordinate、cbYBBYTE數(shù)組曲線上點(diǎn)的X坐標(biāo)高維BYTE數(shù)組曲線上點(diǎn)的X坐標(biāo)低維BYTE數(shù)組曲線上點(diǎn)的Y坐標(biāo)高維BYTE數(shù)組曲線上點(diǎn)的Y坐標(biāo)低維typedefstructh[SM9_MODULUS_BYTES_LcbSXCoordinate[SM9_XCOORDINATEcbSYCoordinate[SM9_XCOORDINATEb)數(shù)據(jù)項(xiàng)描述見表B.6。意義hBYTE數(shù)組BYTE數(shù)組typedefstructStruct_SM9CIPHERBLOB{ULONGulAsymAlgId;BYTEcbXCoordinate[SM9_XCOORDINATE_BYTES_LEN];BYTEcbYCoordinate[SM9_YCOORDINATE_BYTES_LEN];BYTEcbC3[32];ULONGulC2Len;b)數(shù)據(jù)項(xiàng)描述見表B.7。數(shù)據(jù)項(xiàng)意義typedefstructStruct_SM9KEYPACKAGEBLOB{BYTEcbXCoordinate[SM9_XCOORDINATE_BYTES_LEN];BYTEcbYCoordinate[SM9_YCOORDINAb)數(shù)據(jù)項(xiàng)描述見表B.8。意義BYTE數(shù)組BYTE數(shù)組typedefstructSM9KEYPACKAGEBLOBkey}SM9SIGNENCAPSULATEDKEYBLOB,*PSM9b)數(shù)據(jù)項(xiàng)描述見表B.9。數(shù)據(jù)項(xiàng)意義版本號(hào)，本版本為1一補(bǔ)滿)對(duì)稱算法加密的用戶簽名私鑰KGC用于生成用戶簽名私鑰的簽名主公鑰公鑰用戶標(biāo)識(shí)用戶標(biāo)識(shí)長(zhǎng)度用臨時(shí)加密主公鑰和用戶的對(duì)稱密鑰的封裝密文度的對(duì)稱密鑰typedefstructStruct_SM9SIGNENVELOPEDKEYBLOB{}SM9SIGNENVELOPEDKEYBLOB,*Pb)數(shù)據(jù)項(xiàng)描述見表B.10。數(shù)據(jù)項(xiàng)類型意義備注應(yīng)為ECB模式(不填充補(bǔ)滿)KGC用于生成用主公鑰密主公鑰用戶標(biāo)識(shí)用戶標(biāo)識(shí)長(zhǎng)度typedefstructSKF_SM9ENCENCAPS