(整理自網絡)國密SKF標準資料 1 1 11.2、基本類型 2 3 3 32.2、設備信息 4 52.4、RSA私鑰數據結構 62.5、ECC公鑰數據結構 7 82.7、ECC密文數據結構 82.8、ECC簽名數據結構 92.9、分組密碼參數 2.10、ECC加密密鑰對保護結構 2.11、文件屬性 2.12、權限類型 2.13、設備狀態 3.2、取消等待設備插拔事件 3.3、枚舉設備 —2— 3.6、獲取設備狀態 3.7、設置設備標簽 3.8、獲取設備信息 3.9、鎖定設備 3.10、解鎖設備 4.1、修改設備認證密鑰 4.2、設備認證 4.4、獲取PIN信息 4.5、校驗PIN 4.7、清除應用安全狀態 五、應用管理函數 5.1、創建應用 5.2、枚舉應用 5.3、刪除應用 5.4、打開應用 5.5、關閉應用 226.1、創建文件 6.2、刪除指定文件 6.5、讀文件 6.6、寫文件 7.3、打開容器 7.5、枚舉容器 8.1、生成隨機數 29 30 31 8.14、ECC生成并導出會話密鑰 8.15、ECC外來公鑰加密 8.16、ECC外來私鑰解密 8.18、ECC外來公鑰驗簽 8.19、ECC生成密鑰協商參數并輸出 8.20、ECC產生協商數據并計算會話密鑰 8.23、導入會話密鑰 8.26、單組數據加密 8.27、多組數據加密 8.28、結束加密 8.30、單組數據解密 8.31、多組數據解密 8.33、密碼雜湊初始化 8.34、單組數據密碼雜湊 448.35多組數據密碼雜湊 45 8.37、消息鑒別碼運算初始化 8.38、單組數據消息鑒別碼運算 8.39、多組數據消息鑒別碼運算 8.40、結束消息鑒別碼運算 8.41、關閉密碼對象句柄 九、設備的安全要求 9.1、設備使用階段 489.2、權限管理 48 499.4、設備抗攻擊要求 4911.1.1、分組算法標識分組密碼算法標識包含密碼算法的類型和加密模式。分組密碼算法標識的編碼規則為：從低位到高位，第0位到第7位按位表示分組密碼算法工作模式，第8位到第31位按位表示分組密碼算法類型，分組密碼算法的標識如表1所示。表1分組密碼算法標識表SM1算法ECB加密模式SM1算法CBC加密模式SMI算法CFB加密模式SM1算法0FB加密模式SMI算法MAC運算SSF33算法ECB加密模式SSF33算法CBC加密模式SSF33算法CFB加密模式2SSF33算法OFB加密模式SSF33算法MAC運算SMS4算法ECB加密模式SMS4算法CBC加密模式SMS4算法CFB加密模式SMS4算法OFB加密模式SMS4算法MAC運算非對稱密碼算法標識僅定義了密碼算法的類型，在使用非對稱算法進行數字簽名運算時，可將非對稱密碼算法標識符與密碼雜湊算法標識符進行“或”運算后使用，如“RSAwithSHAl”可表示為SGD_RSA|SGD_SHA1,即0x00010002,“|”表示“或”運算。非對稱密碼算法標識的編碼規則為：從低位到高位，第0位到第7位為0,第8位到第15位按位表示非對稱密碼算法的算法協議，如果所表示的非對稱算法沒有相應的算法協議則為0,第16位到第31位按位表示非對稱密碼算法類型，非對稱密碼算法的標識如表2所示。表2非對稱密碼算法標識表SGD_SM2_1SGD_SM2_2SGD_SM2_33密碼雜湊算法標識符可以在進行密碼雜湊運算或計算MAC時應用，也可以與非對稱密碼算法標識符進行“或”運算后使用，表示簽名運算前對數據進行密碼雜湊算法標識的編碼規則為：從低位到高位，第0位到第7位表示密碼雜湊算法，第8位到第31位為0,密碼雜湊算法的標識如表3所示。表3密碼雜湊算法標識表SM3密碼雜湊算法基本數據類型定義如表4所示：表4基本數據類型定義有符號8位整數有符號16位整數有符號32位整數無符號8位整數4無符號16位整數無符號32位整數布爾類型，取值為TRUE或字節類型，無符號8位整數字符類型，無符號8位整數短整數，有符號16位無符號16位整數長整數，有符號32位整數長整數，無符號32位整數無符號32位整數字類型，無符號16位整數雙字類型，無符號32位整數標志類型，無符號32位整數8位字符串指針，按照UTF8格式存儲及交換句柄，指向任意數據對象的起始地址設備句柄應用句柄容器句柄51.3、常量定義表5常量定義常量名布爾值為真 0管理員PIN類型1用戶PIN類型typedefstructStruct_Version{(2)數據項描述參見表6:6表6版本定義數據項意義主版本號Version1.0,主版本號為1,次版本號為0;Version2.10,主版本號為2,次版本號為1次版本號(1)類型定義：typedefstructStruct_DEVINFO{CHARManufacturer[64CHARLabel[32];VERSIONFirmwareVersi7BYTEReserved[64];(2)數據項描述參見表7:表7設備信息描述數據項意義版本號數據結構版本號，本結構的版本號為1.0設備廠商信息以'\0'為結束符的ASCII字符串發行廠商信息以'\0'為結束符的ASCII字符串設備標簽以‘\0'為結束符的ASCII8字符串序列號以'\0'為結束符的ASCII字符串設備硬件版本設備本身固件版本分組密碼算法標識非對稱密碼算法標識密碼雜湊算法標識設備認證使用的分組密碼算法標識設備總空間大小用戶可用空間大小保留擴展(1)類型定義：typedefstructStruct_RSAPUBLICKEYBLOB{BYTEModulus[MAX_RSA_MODULUS_LEN];9(2)數據項描述參見表8:表8版本定義數據項意義算法標識號模數的實際位長度必須是8的倍數數組實際長度為BitLen/8字節#defineMAX_RSA_MODU#defineMAX_RSA_EXPO數組公開密鑰e一般為00010001(1)類型定義：typedefstructStruct_RSAPRIVATEKEYBLOB{BYTECoefficient[MAX_RSA(2)數據項描述參見表9:數據項意義算法標識號模數的實際位長度必須是8的倍數模數n=p*q實際長度為公開密鑰e一般為00010001實際長度為素數p實際長度為素數q實際長度為dmod(p-1)的值q模p的乘法逆元(1)類型定義：typedefstructStruct_ECCPUBLICKEYBLOB{BYTEXCoordinate[ECC_MAX_xCOORDINATE_BITS_LEN/8];BYTEYCoordinate[ECC_MAX_YCOORDINATE_BITS_LEN/8];(2)數據項描述參見表10:表10ECC公鑰數據結構數據項意義模數的實際位長度曲線上點的X坐標有限域上的整數曲線上點的Y坐標有限域上的整數ECC_MAX_YCOORDINATE_(1)類型定義：typedefstructStruct_ECCPRIVATEKEYBLO(2)數據項描述參見表11表11ECC私鑰數據結構數據項意義模數的實際位長度必須是8的倍數私有密鑰有限域上的整數typedefstructStruct_ECCCIPHERBLOB{BYTEXCoordinate[ECC_MAX_XCOORDINATE_BITS_LEN/8];BYTEYCoordinate[ECC_MAX_xCOORDINATE_BITS_LEN/8];ULONGCipherLen;(2)數據項描述參見表12表12ECC密文數據結構數據項意義組與y組成橢圓曲線上的點(x,組與x組成橢圓曲線上的點(x,明文的雜湊值組密文數據長度組密文數據2.8、ECC簽名數據結構(1)類型定義：typedefstructStruct_ECCSIGNATUREBLOB{ECC_MAX_MODULUS_BITS_LEN為ECC算法模數的最大長度；(2)數據項描述參見表13:表13ECC簽名數據結構數據項意義r簽名結果的r部分S簽名結果的s部分2.9、分組密碼參數(1)類型定義：typedefstructStruct_BLOCKCIPHERPARAM{(2)數據項描述參見表14:表14分組密碼參數意義組初始向量，填充方式，0表示不填充，1表示按照反饋值的位長度(按位計算)只針對OFB、2.10、ECC加密密鑰對保護結構(1)類型定義：ULONGVersion;//當前版本為1ULONGulSymmAlgID;//對稱算法標識，限定ECB模式ULONGulBits;//加密密鑰對的密鑰位長度BYTEcbEncryptedPriKey[64];//加密密鑰對私鑰的密文(2)數據項描述參見表15:表15分組密碼參數數據項意義版本號，本版本為1對稱算法標識必須為ECB加密密鑰對的密鑰位長對稱算法加密的加密私鑰，加密私鑰的原文為ECCPRIVATEKEYBLOB結構中的PrivateKey。其有效長度為原文的(ulBits加密密鑰對的公鑰用保護公鑰加密過的對稱密鑰密文(1)類型定義：typedefstructStruct_FILEATTRIBUTE{(2)數據項描述參見表16:表16文件屬性意義組文件名以'\0'結束的ASCII字符串，最大長度為32文件大小創建文件時定義的文件大小讀取權限讀取文件需要的權限寫入權限寫入文件需要的權限權限類型的定義參見表17:表17權限類型說明不允許管理員權限用戶權限設備狀態的定義參見表18:說明設備存在設備狀態未知設備管理主要完成設備的插拔事件處理、枚舉設備、連接設備、斷開連接、獲取設備狀態、設置設備標簽、獲取設備信息、鎖定設備、解鎖設備和設備命令傳輸等操作。設備管理系列函數如表19所示：表19設備管理系列函數等待設備插拔事件取消等待設備插拔事件枚舉設備連接設備斷開連接獲取設備狀態設置設備標簽獲取設備信息鎖定設備設備命令傳輸功能描述：該函數等待設備插入或者拔除事件。szDevName返回發生事件的設備參數：szDevName:[OUT]發生事件的設備名稱。pulDevNameLen:[IN/OUT]輸入/輸出參數，當輸入時表示緩沖區長度，輸出時表示設備名稱的有效長度，長度包含字符串結束符。pulEvent:[OUT]事件類型。1表示插入，2表示拔出。其他：錯誤碼。函數原型：ULONGDEVAPISKF_CancelWaitForDevEve功能描述：該函數取消等待設備插入或者拔除事件。參數：無其他：錯誤碼。備注：使本進程正在執行的SKF_WaitForDevEvent函數立即返回。功能描述：獲得當前系統中的設備列表。參數：bPresent:[IN]為TRUE表示取當前設備狀態為存在的設備列表。為FA表示取當前驅動支持的設備列表。szNameList:[OUT]設備名稱列表。如果該參數為NULL,將由pulSize返回所需要的內存空間大小。每個設備的名稱以單個‘\0’結束，以雙表示列表的結束。pulSize:[IN,OUT]輸入時表示設備名稱列表的緩沖區長度，輸出時表示szNameList所占用的空間大小。其他：錯誤碼。功能描述：通過設備名稱連接設備，返回設備的句柄。參數：szName:[IN]設備名稱。phDev:[OUT]返回設備操作句柄。其他：錯誤碼。功能描述：斷開一個已經連接的設備，并釋放句柄。參數：hDev:[IN]連接設備時返回的設備句柄。返回值：SAR_0K:成功。其他：錯誤碼。備注：如果該設備已被鎖定，函數應首先解鎖該設備。斷開連接操作并不影響設備的權限狀態。函數原型：ULONGDEVAPISKF_GetDev功能描述：獲取設備是否存在的狀態。參數：szDevName:[IN]設備名稱。pulDevState:[OUT]返回設備狀態。返回值：SAR_0K:成功。其他：錯誤碼。功能描述：設置設備標簽。參數：hDev:[IN]連接設備時返回的設備句柄。szLabel:[IN]設備標簽字符串。該字符串應小于32字節。返回值：SAR_0K:成功。其他：錯誤碼。功能描述：獲取設備的一些特征信息，包括設備標簽、廠商信息、支持的算法等。參數：hDev:[IN]連接設備時返回的設備句柄。pDevInfo:[0UT]返回設備信息。返回值：SAR_0K:成功。其他：錯誤碼。功能描述：獲得設備的獨占使用權。參數：hDev:[IN]連接設備時返回的設備句柄。ulTimeOut:[IN]超時時間，單位為毫秒。如果為0xFFFFFFFF表示無限等待。其他：錯誤碼。功能描述：釋放對設備的獨占使用權。參數：hDev:[IN]連接設備時返回的設備句柄。其他：錯誤碼。3.11、設備命令傳輸函pulDataLen:[IN,OUT]輸入時表示結果數據緩沖區長度，輸出時表示結四、訪問控制函數概述系列函數如表20所示：表20訪問控制系列函數設備認證獲得PIN碼信息清除應用安全狀態4.1、修改設備認證密鑰功能描述：設備認證是設備對應用程序的認證。參數：hDev:[IN]連接時返回的設備句柄。pbAuthData:[IN]認證數據。ulLen:[IN]認證數據的長度。返回值：SAR_0K:成功。其他：錯誤碼。功能描述：調用該函數可以修改AdministratorPIN和UserPIN的值。如果原PIN碼錯誤導致驗證失敗，該函數會返回相應PIN碼的剩余重試次數，當剩余次數為0時，表示PIN已經被鎖死。參數：hApplication:[IN]應用句柄。pulRetryCount:[OUT]出錯后重試次數。功能描述：獲取PIN碼信息，包括最大重試次數、當前剩余重試次數，以及當前PIN碼是否為出廠默認PIN碼。參數：hApplication:[IN]ulPINType:[IN]PIN類型。pulMaxRetryCount:[OUT]最大重試次數。pulRemainRetryCount:[OUT]當前剩余重試次數，當為0時表示已鎖死。pbDefaultPin:[OUT]是否為出廠默認PIN碼。功能描述：校驗PIN碼。校驗成功后，會獲得相應的權限，如果PIN碼錯誤，會返回PIN碼的重試次數，當重試次數為0時表示PIN碼已經鎖死。ulPINType:[IN]PIN類型。功能描述：當用戶的PIN碼鎖死后，通過調用該函數來解鎖用戶PIN碼。解鎖后，用戶PIN碼被設置成新值，用戶PIN碼的重試次數也恢復到原szAdminPIN:[IN]管理員PIN碼。szNewUserPIN:[IN]新的用戶PIN碼。pulRetryCount:[OUT]管理員PIN碼錯誤時，返回剩余重試次數。其他：錯誤碼。備注驗證完管理員PIN才能夠解鎖用戶PIN碼，如果輸入的AdministratorPIN不正確或者已經鎖死，會調用失敗，并返回AdministratorPIN的重試次數。函數原型：ULONGDEVAPISKF_ClearSecureState(HAPPLICATIONhApplication)功能描述：清除應用當前的安全狀態。參數：hApplication:[IN]應用句柄。其他：錯誤碼。概述應用管理主要完成應用的創建、枚舉、刪除、打開、關閉等操作。應用管理系列函數如表21所示：表21應用管理系列函數創建應用枚舉應用刪除應用打開應用關閉應用zUserPin,DWORDdwUserPinRetryCount,DWORDdwCreatHAPPLICATION*phAppli功能描述：創建一個應用。參數：hDev:[IN]連接設備時返回的設備句柄。szAppName:[IN]應用名稱。szAdminPin:[IN]管理員PIN。dwAdminPinRetryCount:[IN]管理員PIN最大重試次數。dwUserPinRetryCount:[IN]用戶PIN最大重試次數。dwCreateFileRights:[IN]在該應用下創建文件和容器的權限，為各種權限的或值。phApplication:[OUT]應用的句柄。其他：錯誤碼。回所需要的內存空間大小。每個應用的名稱以單個‘\0'結束，以雙pulSize:[IN,OUT]輸入時表示應用名稱的緩沖區長度，輸出時返回參數：hDev:[IN]連接設備時返回的設備句柄。六、文件管理函數概述文件管理函數用以滿足用戶擴展開發的需要，包括創建文件、刪除文件、枚舉文件、獲取文件信息、文件讀寫等操作。文件管理系列函數如表22所示：表22文件管理系列函數枚舉文件獲取文件信息寫文件szFileName,ULONGulFileSize,ULONGulRead功能描述：創建文件時要指定文件的名稱，大小，以及文件的讀寫權限。參數：hApplication:[IN]應用句柄。szFileName:[IN]文件名稱，長度不得大于32個字節。ulReadRights:[IN]文件讀權限。可為各種權限的或值。ulWriteRights:[IN]文件寫權限。可為各種權限的或值。返回值：SAR_0K:成功。其他：錯誤碼。備注：創建文件需要應用指定的創建文件權限。函數原型：ULONGDEVAPISKF_DeleteFile(HAPPLICATIONhApplication,功能描述：文件刪除后，文件中寫入的所有信息將丟失。文件在設備中的占用參數：hApplication:[IN]參數：hApplication:[IN]szFileList:[OUT]返回文件名稱列表，該參數為空，由pulSize返回文件信息所需要的空間大小。每個文件名稱以單個'\0'結束，以雙'\0'pulSize:[IN,OUT]輸入時表示數據緩沖區的大小，輸出時表示實際文功能描述：獲取文件信息：獲取應用文件的屬性信息，例如文件的大小、權限等。文件所在應用的句柄。文件名稱。文件信息，指向文件屬性結構的指針。其他：錯誤碼。函數原型：ULONGDEVAPISKF_ReadFile(HAPPLICATIONhApplication,szFileName,ULONGu10ffset,ULONGulSize,BYT功能描述：讀取文件內容。參數：hApplication:[IN]應用句柄。szFileName:[IN]文件名。ulOffset:[IN]文件讀取偏移位置。ulSize:[IN]要讀取的長度。pbOutData:[OUT]返回數據的緩沖區。pul0utLen:[IN,OUT]輸入時表示給出的緩沖區大小；輸出時表示實際讀取返回的數據大小。其他：錯誤碼。備注：權限要求：須具備對該文件的讀權限。函數原型：ULONGDEVAPISKF_WriteFile(HAPPLICATIONhApplicszFileName,ULONGul0ffset,BYTE*pbData,ULONGulSize)功能描述：寫數據到文件中。參數：hApplication:[IN]應用句柄。szFileName:[IN]文件名。ulOffset:[IN]寫入文件的偏移量。pbData:[IN]寫入數據緩沖區。ulSize:[IN]寫入數據的大小。其他：錯誤碼。備注：權限要求：須具備該文件的寫權限。概述本規范提供的應用管理用于滿足各種不同應用的管理，包括創建、刪除、枚舉、打開和關閉容器的操作。容器管理系列函數如表23所示：表23容器管理系列函數枚舉容器打開容器關閉容器獲得容器類型導入數字證書導出數字證書函數原型：ULONGDEVAPISKF_CreateContainer(HAPPLICATIONhApplication,LPSTRszContainerName,HCONTAINER*p功能描述：在應用下建立指定名稱的容器并返回容器句柄。參數：hApplication:[IN]szContainerName:[IN]ASCII字符串，表示所建立容器的名稱，容器名稱的最大長度不能超過64字節。szContainerName:[IN]指向刪除容器的名稱。函數原型：ULONGDEVAPISKF_OpenContainer(HAPPLICATIONhApplication,LPSTRszContainerName,HCONTAINER*p功能描述：獲取容器句柄。參數：hApplication:[IN]應用句柄。szContainerName:[IN]容器的名稱。phContainer:[OUT]返回所打開容器的句柄。其他：錯誤碼。函數原型：ULONGDEVAPISKF_CloseContainer(HCONTAINERhContainer)功能描述：關閉容器句柄，并釋放容器句柄相關資源。參數：hContainer:[IN]容器句柄。返回值：SAR_0K:成功。其他：錯誤碼。功能描述：枚舉應用下的所有容器并返回容器名稱列表。時，返回容器名稱列表，每個容器名以單個‘\0'為結束，列表以雙'\0'結束。pulSize:[IN,OUT]輸入時表示szContainerName緩沖區的長度，輸出其他：錯誤碼。SKF_GetContianerType(HCONTAI功能描述：獲取容器的類型pulContainerType:[OUT]獲得的容器類型。指針指向的值為0表示未定、尚未分配類型或者為空容器，為1表示為RSA容器，為2表示為ECC容7.7、導入數字證書7.8、導出數字證書功能描述：從容器內導出數字證書。參數：hContainer:[IN]容器句柄。bSignFlag:[IN]TRUE表示簽名證書，FALSE表示加密證書。表示返回數據所需要緩沖區的長度，如果此參數不為NULL時，返回數字證書內容。pulCertLen:[IN/OUT]輸入時表示pbCert緩沖區的長度，輸出時表示證書內容的長度。其他：錯誤碼。概述密碼服務函數提供對稱算法運算、非對稱算法運算、密碼雜湊運算、密鑰管理、消息鑒別碼計算等功能。密碼服務系列函數如表24所示：表24密碼服務系列函數生成隨機數生成外部RSA密鑰對生成RSA簽名密鑰對導入RSA加密密鑰對RSA簽名RSA生成并導出會話密鑰生成ECC簽名密鑰對導入ECC加密密鑰對ECC簽名ECC生成并導出會話密鑰ECC外來公鑰加密ECC外來私鑰解密ECC外來私鑰簽名SKF_GenerateAgreemenECC生成密鑰協商參數并輸出ECC計算會話密鑰SKF_GenerateAgreementDataAECC產生協商數據并計算會話密鑰導出公鑰導入會話密鑰明文導入會話密鑰單組數據加密多組數據加密結束加密單組數據解密多組數據解密結束解密密碼雜湊初始化單組數據密碼雜湊多組數據密碼雜湊結束密碼雜湊消息鑒別碼運算初始化單組數據消息鑒別碼運算多組數據消息鑒別碼運算結束消息鑒別碼運算關閉密碼對象句柄功能描述：產生指定長度的隨機數。參數：hDev:[IN]設備句柄。pbRandom:[OUT]返回的隨機數。ulRandomLen:[IN]隨機數長度。返回值：SAR_OK:成功。其他：錯誤碼。8.2、生成外部