GM-T 0127-2023 移動終端密碼模塊應用接口規(guī)范

中華人民共和國密碼行業(yè)標準移動終端密碼模塊應用接口規(guī)范國家密碼管理局發(fā)布I 4縮略語 2 25.2模塊的應用結(jié)構(gòu) 2 3 36.2基本數(shù)據(jù)類型定義 36.3復合數(shù)據(jù)類型定義 4 77.1概述 77.2密碼算法實現(xiàn)要求 7 87.4密碼應用接口定義 87.5密碼模塊類 8 97.7模塊接口 7.8應用接口 7.9容器接口 7.12消息鑒別碼接口 7.13帶密鑰的雜湊運算接口 8安全要求 8.1模塊使用階段 8.2權(quán)限管理 8.3其他安全要求 附錄A(規(guī)范性)異常碼預定義值和說明 Ⅲ本文件按照GB/T1.1—2020《標準化工作導則第1部分：標準化文件的結(jié)構(gòu)和起草規(guī)則》的規(guī)定起草。請注意本文件的某些內(nèi)容可能涉及專利。本文件的發(fā)布機構(gòu)不承擔識別專利的責任。本文件由密碼行業(yè)標準化技術(shù)委員會提出并歸口。本文件起草單位：中國科學院數(shù)據(jù)與通信保護研究教育中心、中國科學技術(shù)大學、中國科學院信息工程研究所、北京數(shù)字認證股份有限公司、北京理工大學、長春吉大正元信息技術(shù)股份有限公司、北京交通大學、中國信息通信研究院、北京信安世紀科技股份有限公司、中國人壽保險股份有限公司研發(fā)中心、國家計算機網(wǎng)絡應急技求處理協(xié)調(diào)中心、中國電子技術(shù)標準化研究院、中國工業(yè)互聯(lián)網(wǎng)研究院、中電科網(wǎng)絡安全科技股份有限公司、格爾軟件股份有限公司、北京中電華大電子設計有限責任公司、北京創(chuàng)原天地科技有限公司、北京小雷科技有限公司、北京國脈信安科技有限公司、財付通支付科技有限公司、北京煉石網(wǎng)絡技術(shù)有限公司、深信服科技股份有限公司、北京路云天網(wǎng)絡安全技術(shù)研究院有限公司。汪宗斌、徐麗娟、張曉娜、黃晶品、本理工里建、劉麗敏工偉。生量姣，趙欣怡呂娜雷靈光、錢文飛、唐明環(huán)、于成麗、張立廷、尹一型趙麗麗、黃福飛李濤在移動終端上調(diào)用各類密碼模塊實現(xiàn)密碼服務的方式已逐漸普及，本文件目密碼模塊的實現(xiàn)提供統(tǒng)一的應用接口規(guī)范，進一步推動密碼算法在移動終端1移動終端密碼模塊應用接口規(guī)范1范圍本文件規(guī)定了移動終端密碼模塊的結(jié)構(gòu)模型、數(shù)據(jù)類型定義、應用接口及安全要求。本文件適用于移動終端密碼模塊產(chǎn)品的研制和使用，以及基于該類密碼產(chǎn)品的應用開發(fā)與檢測。2規(guī)范性引用文件下列文件中的內(nèi)容通過文中的規(guī)范性引用而構(gòu)成本文件必不可少的條款。其中，注日期的引用文件，僅該日期對應的版本適用于本文件；不注日期的引用文件，其最新版本(包括所有的修改單)適用于本文件。GB/T15852.1信息技術(shù)安全技術(shù)消息鑒別碼第1部分；采用分組密碼的機制GB/T32905信息安全技術(shù)SM3密碼雜湊算法GB/T32907信息安全技術(shù)SMI分組密兩算法GB/T33560信息安全技水密碼應用標規(guī)范GB/T35276信息安全技木SM2密碼章法使用規(guī)范GB/T37092信息安全技密碼模塊安全要求GM/To017-2023智能密碼鑰匙密碼應用接口數(shù)據(jù)格式規(guī)范GM/Z4001密碼術(shù)語3術(shù)語和定義GM/Z4001界定的以及下列術(shù)語和定義適用于本文件。密碼模塊cryptographicmodule實現(xiàn)了安全功能的硬件、軟件和/或固件的集合，并目被包含在密碼邊界內(nèi)。模塊鑒別moduleauthentication移動終端密碼模塊對應用程序的鑒別。模塊鑒別密鑰moduleauthenticationkey用于模塊鑒別的密鑰。容器container密碼模塊中用于保存密鑰所劃分的唯一性存儲空間。包括PIN、文件和容器的一種結(jié)構(gòu)，具備獨立的權(quán)限管理。2圖1所示。移動終端密碼模塊應用接口:3定義4bytemajor}主版本號和次版本號以“.”分隔，例如，Versio次版本號VersionfirmwareVersion;}數(shù)據(jù)項描述見表35定義發(fā)行廠商信息非對稱密碼算法標識模塊總空間大小用戶可用空間大小能夠處理的SM2加密數(shù)據(jù)大小能夠處理的分組運算和雜湊運算的數(shù)據(jù)大小表4文件屬性定義文件名文件大小創(chuàng)建文件時定義的文件大小寫入權(quán)限寫文件所需要的權(quán)限6longmaxRetryCount;}定義0為管理員PIN;1為用戶PIN當值為0時，PIN碼被鎖定認PINtrue表示是出廠默認PIN;值說明模塊狀態(tài)未知7權(quán)限類型值說明管理員權(quán)限用戶權(quán)限classBlockCipherPar}數(shù)據(jù)項描述見表8。表e版本定義定只針對CFB、OFB模式6.3.8SM2算法相關(guān)數(shù)據(jù)格式SM2私鑰數(shù)據(jù)、SM2公鑰數(shù)據(jù)、SM2加密數(shù)據(jù)、SM2簽名數(shù)據(jù)以及SM2密鑰對保護數(shù)據(jù)均以字節(jié)數(shù)組的方式進行傳輸，其數(shù)據(jù)格式均遵循GB/T35276。7移動終端密碼模塊應用接口本章以Java技術(shù)方案為例描述了移動終端密碼模塊中SM2/3/4系列算法的應用接口規(guī)范，使用SM2/3/4系列算法的應用可以調(diào)用這些應用接口以實現(xiàn)相應的密碼功能。7.2密碼算法實現(xiàn)要求在移動終端密碼模塊中，SM2橢圓曲線公鑰密碼算法實現(xiàn)應遵循GB/T32918(所有部分),SM3密碼雜湊算法實現(xiàn)應遵循GB/T32905,SM4分組密碼算法實現(xiàn)應遵循GB/T32907,消息鑒別碼算法實現(xiàn)應遵循GB/T15852.1。8密碼應用包定義見表9,密碼應用包包含密碼模塊抽象類與密碼應用接口。移動密碼模塊產(chǎn)品實項定義包名1次版本號0定義密碼模塊抽象類(GMCryptoMod),具體類定義classjava.lang.object—classcom.mob.crypto.GMCr提供模塊連接接口(IModuleConnection)、模塊接口(IModule)、應用接口(IApplication)、容器接口com.mob.crypto.IModu接口方法異常碼應按照附錄A進行定義和說明。接口方法描述僅列出常見異常，在密密碼模塊抽象類(GMCryptoMod)是移動終端密碼模塊的基類，所有密碼模塊的實現(xiàn)應擴展這個GMCryptoMod類成員變量見表10。9定義說明為0時表示該模塊為硬件密碼模塊；為0時表示該模塊不需要進行模塊鑒別；為1時表示該模塊需要進行模塊鑒別模塊連接接口主要完成對移動終端中的密碼模塊進行管理(包連接模更枚舉模IModuleConmection接自系列方法見表方法聲明IModuleSSF_ConneetMod()throwsResultCodeE功能描述連接一個模塊。返回值IModule接口實現(xiàn)類對象拋出異常ResultCodeException.SSF_UNKNOWNERRResultCodeException.SSF_MOD方法聲明List(String>SSF_EnumMod()throwsResultCodeE異常錯誤無sultCodeException.SSF_UNKRResultCodeException.SResultCodeException.SSF_MO異常錯誤定義說明斷開模塊獲取模塊信息模塊鑒別修改模塊鑒別密鑰創(chuàng)建應用枚舉應用刪除應用打開應用備份應用恢復應用)throwsResultCodeException功能描述斷開一個已經(jīng)連接的模塊拋出異常ResultCodeException.SSF_UNKNOWNERR異常錯誤ResultCodeException.SSF_MODLOCKED模塊已鎖定功能描述設置模塊標簽。拋出異常ResultCodeException于32字節(jié)ModInfosSSF_GetModI無ResultCodeException.SSF_UNKNOWNERR異常錯誤無ResultCodeException.SSF_UNKN無無拋出異常ResultCodeException.SSF_UNKNOWNERR異常錯誤拋出異常ResultCodeException.SSF_UNKNOWNERR異常錯誤拋出異常ResultCodeException.SSF_UNKNOWERR異常錯誤功能描述voidSSF_ChangeModAutbyte[]keyCipher無ResultCodeException.SSF_UNK權(quán)限要求：模塊鑒別成功后才能使用。新模塊鑒別密鑰的密文通過使用原模塊鑒別密鑰對新模塊鑒別密鑰進行ECB加密得到。報文鑒別碼由原模塊鑒別密鑰對含有keyCipher的數(shù)據(jù)進行CBC加密得到。報文鑒別碼的計算過程應符合)throwsResultCo功能描述創(chuàng)建一個應用。userPIN用戶PIN值ResultCodeException.SSF_APPLICATIONEXIS)throwsResultCo拋出異常ResultCodeException.SSF_FAIL失敗ResultCodeException.SSF_UNKNOWNERR異常錯誤ResultCodeException.SSF_OBJERR對象錯誤無ResultCodeException.SSF_APPLICATIONResultCodeException.SResultCodeException.SSF_ResultCodeException.SSF_FResultCodeException.SSF_APPLICATIONResultCodeException.SResultCodeException.SSF_UNKN方法聲明voidSSF_BackupApplication(拋出異常ResultCodeExceptionResultCodeException.SSF_APPLICATION功能描述恢復應用。返回值ResultCodeException.SSF_UNKNResultCodeException.SSF_GENRIApplication接口系列方法見表13。定義說明關(guān)閉應用獲取PIN相關(guān)信息SSF_EnumContainer除文件獲取及件信息7.8.2關(guān)閉應用方法聲明voldSSF_CloseApplication()throwsResultCodeException參數(shù)返回值拋出異常無無ResultCodeException.SResultCodeException.SSF_UNKN失敗異常錯誤備注此方法不影響應用的安全狀態(tài)。7.8.3修改PIN方法聲明longSSF_ChangePIN(功能描述調(diào)用該方法可以修改管理員PIN和用戶PIN的值。如果原PIN碼錯誤導致驗證失原PIN值ResultCodeException.SSF_PResultCodeException.SSF_PINResultCodeException.SSF_NOTSUPPOR功能描述)throwsResultCodeExceptionResultCodeException.SSF_NOTSUPPOR7.8.5校驗PINlongpinType,)throwsResultCodeExceptionpinResultCodeException.SSF_PINResultCodeException.SSF_PResultCodeException.SSF_NOTSUPPOR7.8.6解鎖PIN參數(shù)adminPINnewUserPIN新的用戶PIN值返回值管理員PIN碼錯誤時，返回剩余重試次數(shù)拋出異常ResultCodeException.SSF_PININCORRECTResultCodeException.SSF_PResultCodeException.SSF_PINResultCodeException.SSF_NOTSUPPORPIN不正確PIN長度錯誤不支持的服務備注驗證完管理員PIN才能夠解鎖用戶PIN碼，如果輸入的管理員PIN不正確或者已經(jīng)鎖死，會調(diào)用失敗，并返回管理員PIN的重試次數(shù)。7.8.7清除應用安全狀態(tài)方法聲明voidSSF_ClearSecureState(功能描述清除應用當前的安全狀態(tài)。參數(shù)無返回值無拋出異常ResultCodeException.SSF_NOTSUPPORTYETERR方法聲明IContainerSSpGroateConanerC功能描述創(chuàng)建一個容器參數(shù)containerNan返回值IContainer接自現(xiàn)類對象方法聲明功能描述參數(shù)返回值拋出異常備注voidSSF_DeleteContaine刪除容器。無ResultCodeException.SSF_CONTAINE不支持的服務容器名稱容器已經(jīng)存在容器名稱容器不存在方法聲明List(String>SSF_EnumCo功能描述枚舉所有已經(jīng)創(chuàng)建的容器。參數(shù)無返回值容器名稱列表拋出異常ResultCodeException.SSF_UNKN異常錯誤功能描述打開一個容器。參數(shù)containerNameResultCodeException.SSF_CONTAINERlongwriteRights功能描述創(chuàng)建文件。readRights文件讀權(quán)限(見6.3.6,可為各種權(quán)writeRights文件寫權(quán)限(見6.3.6,可為)throwsResultCode功能描述枚舉所有已經(jīng)創(chuàng)建的文件。無文件名稱列表ResultCodeException.SResultCodeException.SSF_UNKNResultCodeException.SSF_F方法聲明)throwsResultCode功能描述獲取文件信息。ResultCodeException.SSF_FILENResultCodeException.SSF_F方法聲明byte[]SSF_ReadFile()throwsResultCode功能描述讀取文件。文件數(shù)據(jù)ResultCodeException.SSF_FILEN方法聲明voidSSF_WriteFile()throwsResultCode功能描述寫文件。參數(shù)fileName返回值拋出異常返回值拋出異常備注無ResultCodeException.SSF_READ權(quán)限要求：須具備對該文件的寫權(quán)限。偏移量，不可超過文件大小且大于待寫入的數(shù)據(jù)寫文件錯誤讀文件錯誤7.9容器接口7.9.1概述容器接口(IContainer)主要完成數(shù)字證書的導入導出以及密碼相關(guān)操作。移動終端與云服務協(xié)同數(shù)字簽名是移動終端密碼模塊的重要實現(xiàn)方式，在容器接口中引入基于SM2的協(xié)同簽名和解密系列方法(包括生成協(xié)同密鑰對，SM2協(xié)同簽名、SM2協(xié)同解密等功能)。各功能均可調(diào)用一次或多次請求生成與響應處理方法，通過協(xié)同密碼機制標識參數(shù)以確定所使用的協(xié)同密碼算法，并確定對相關(guān)參數(shù)的解析方法，從而實現(xiàn)對各類協(xié)同密碼機制的兼容支持。IContaimer接口系列方法見表14表14IContainer接日系列方法說明SSF地p定理fcate是大數(shù)彎書導雷數(shù)字證書SM2簽名SM2外部私鑰解密(僅測試)SM2外部私鑰簽名(僅測試)SSF_GenerateAgreementDSM2生成密鑰協(xié)商參數(shù)并輸出SSF_GenerateAgreementDataAndSSF_genThresholdKeyPSSF_genThresholdKeyPairRespo定義說明SSF_thresholdSignDatSSF_thresholdSignDataResponSSF_thresholdDecryptRespon導出公鑰外來對稱密鑰加密(僅測試)外來對稱密鑰解密(僅測試)導入會話密鑰)throwsResultCodeException功能描述關(guān)閉容器。無無ResultCodeException.SSF_UNK)throwsResultCodeException無voidSSF_ImportCertifibooleansignFlag,無ResultCodeException.SSF_UNK7.9.5導出數(shù)字證書方法聲明byte[]SSF_ExportCertificate(功能描述導出證書數(shù)據(jù)。參數(shù)signFlagtrue表示簽名證書，false表示加密證書返回值證書數(shù)據(jù)拋出異常ResultCodeException.SSF_CERTNOTFOUNDERR證書未發(fā)現(xiàn)方法聲明voidSSF_GenSM2KeyPair()throwsResultCodeExc參數(shù)algId算法標退(只支持SGD_SM2_1算法)返回值無拋出異常ResultCodeLxceptonS8F_UNKNOWNERR異常譜誤備注權(quán)限要求：需要用意權(quán)限。7.9.7導入SM2加密密鑰對功能描述導入SM2公私鑰對。參數(shù)sm2EnvelopedKey受保護的加密密鑰對，不能為空拋出異常ResultCodeException.SSF_UNKNOWNERR異常錯誤備注權(quán)限要求：需要用戶權(quán)限。sm2EnvelopedKey數(shù)據(jù)格式為SM2密鑰對的保護數(shù)據(jù)格式(見6.3.8)。7.9.8SM2簽名方法聲明byte[]SSF_SM2SignDat功能描述SM2簽名(對原始數(shù)據(jù)的雜湊值進行簽名)。參數(shù)返回值SM2簽名值拋出異常ResultCodeException.SResultCodeException.SSF_UNKN計算錯誤異常錯誤備注權(quán)限要求：需要用戶權(quán)限。輸入數(shù)據(jù)為待簽數(shù)據(jù)的雜湊值。當使用SM2算法時，該輸入數(shù)據(jù)為待簽數(shù)據(jù)經(jīng)過ResultCodeException.SSF備注輸入數(shù)據(jù)為待簽數(shù)據(jù)的雜湊值。當使用SM2算法時，該輸入數(shù)據(jù)為待簽數(shù)據(jù)經(jīng)過byte[]SSF_SM2ExportSessionKResultCodeException.SSF_ENCResultCodeException.SSF_DATAResultCodeException.SSF_ENCResultCodeException.SSF_DATAbyte[]sm2Cipher拋出異常ResultCodeException.SSF_DECRYPTERR拋出異常ResultCodeException.SSF_FAIL失敗ResultCodeException.SS功能描述使用外部傳入的SM2公鑰做簽名驗證。ResultCodeException.SResultCodeException.SSF_KEYINFOResultCodeException.SSF_UNKN備注輸入數(shù)據(jù)為待簽數(shù)據(jù)的雜湊值。當使用SM2算法時，該輸入數(shù)據(jù)為待簽數(shù)據(jù)經(jīng)過功能描述byte[]SSF_GenerateAgreementDataWit發(fā)起方發(fā)起方ID,長度應不大于32字節(jié)ResultCodeException.SResultCodeException.SSF_UNKNbyte[]tempSM2PublicK功能描述響應方的臨時SM2公鑰響應方ID,長度應不大于32字節(jié)ResultCodeException.SSF_FAIL失敗ResultCodeException.SSF_OBJ方法聲明ISessionKeySSF_Generatbyte[]sponsorSM2PublicKbyte[]sponsorTempSM2PublicKbyte[]sponsorId,sponsorSM2PublicKeysponsorldID響應拋出異常ResultCodeException.SSF_FAILResultCodeException.SSF_UNKNOWNERR異常錯誤方法聲明byte[]SSF_genThresholdKe功能描述生成SM2協(xié)同密鑰對生成的請求數(shù)據(jù)。signFlag密鑰對，false表示生成加密密拋出異常ResultCodeException.SSF_UNKNOWNERR方法聲明yoidSSF_genThresholdKeyPairResponseProcess(對)無ResultCodeException.SSF_UNKN方法聲明byte[]SSF_thresholdSignResultCodeException.SSF_COM輸入數(shù)據(jù)為待簽數(shù)據(jù)的雜湊值。當使用SM2算法時，該輸入方法聲明byte[]SSF_thresholdSignDataRe拋出異常ResultCodeException.SSF_COMPUTEERR計算錯誤方法聲明byte[]SSF_thresholdDe功能描述生成SM2協(xié)同解密的請求數(shù)據(jù)。參數(shù)返回值拋出異常SM2協(xié)同解密請求數(shù)據(jù)ResultCodeExceptionsSF_DECRYPTERR協(xié)同解密機制標識待解密的密文數(shù)據(jù)協(xié)同解密機制所需參數(shù)解密錯誤7.9.23SM2協(xié)同解密響應處理方法聲明bote[]sSF_thresholdDecryptResponseProcess()throwsResaliCorlelxc功能描述處理服務端反可的SM2J回解密響應消息，生成解密結(jié)果參數(shù)algId協(xié)同解密機制標識responseMS協(xié)同解密服務端響應消息返回值SM2協(xié)同解密運算結(jié)果拋出異常ResultCodeEtepron.SSFRYPT解密錯誤備注權(quán)限要求：需要用直權(quán)限。7.9.24導出公鑰方法聲明bye]SSFFxportPabliekey(XthrowsResultCodeException功能描述導出公鑰。參數(shù)signFlagtrue表示導出簽名公鑰，false表示導出加密公鑰返回值SM2公鑰數(shù)據(jù)拋出異常ResultCodeException.SSF_FAIL失敗ResultCodeException.SSF_UNKNOWNERR異常錯誤備注返回值SM2公鑰數(shù)據(jù)格式為SM2公鑰數(shù)據(jù)格式(見6.3.8)。7.9.25外來對稱密鑰加密方法聲明byte[]SSF_ExtKeyEncrypt(功能描述使用外來加密密鑰對指定數(shù)據(jù)進行加密，被加密的數(shù)據(jù)只包含單一分組，輸出加密后的ResultCodeException.SResultCodeException.SSF_ENC拋出異常ResultCodeException.SSF_FAIL方法聲明ISessionKeySSF_I拋出異常ResultCodeException.SSF_FAIL失敗ResultCodeException.SSF_UNKNResultCodeException.SSF_OBJERR表15ISessionKey接口系列方法定義說明多包數(shù)據(jù)加密結(jié)束加密多包數(shù)據(jù)解密結(jié)束解密BlockCiphoiPuanbloakCpherParam功能描述對稱加密祖始化段置對稱經(jīng)算法的相關(guān)參數(shù)。參數(shù)blockCipherPara分組密碼參數(shù)返回值無拋出異常ResultCodeEecpfonSSF_FResultCodctrecptonStUNKNOWNERR常需送ResultCodeExcepton.7.10.3單包數(shù)據(jù)加密方法聲明byte]SSF_Encrypt(功能描述對單一分包的消息進行加密，并輸出加密結(jié)果。參數(shù)待加密數(shù)據(jù)待加密數(shù)據(jù)長度返回值密文數(shù)據(jù)拋出異常ResultCodeException.SSF_ENCRResultCodeException.SSF_ENCRYPTResultCodeException.SSF_ResultCodeException.SSF_INVALIDResultCodeException.SSF_NOTINITI加密錯誤加密填充錯誤對象錯誤無效的參數(shù)未初始化拋出異常ResultCodeException.SSF_NOTIResultCodeException.SSF_OBJERRbyte[]SSF_EncryptFin無拋出異常ResultCodeExceptionBlockCipherParamblockCi無ResultCodeException.SResultCodeException.SSF_UNKNResultCodeException.SSF_ResultCodeException.SSF_INVALID拋出異常ResultCodeExceptResultCodeException.SSF_NOTResultCodeException.SSF_NOTI無ResultCodeException.SSF_UNKN定義說明多包數(shù)據(jù)密碼雜湊結(jié)束密碼雜湊功能描述雜湊初始化。為SGD_SM3時有效拋出異常ResultCodeException.SSF_FAILResultCodeException.SSF_UNKNOWNERR異常錯誤ResultCodeException.SSF_NOTSUPPORTALG不支持的標識備注當密碼雜湊算法標識為SGD_SM3且簽名者ID值長度不為0的情況下，pubKey和ResultCodeException.SSF_NOTI返回值返回值ResultCodeException.SSF_HResultCodeException.SSF_NOTINITI未初始化方法聲明byte[]SSF_DigestFin無返回值雜湊值ResultCodeException.SResultCodeException.SSF_UNKNSSF_DigestFinal應用于SSF_DigestUpdate之后。IMac接口系列方法見表17。表17IMac接口系列方法定義說明多包數(shù)據(jù)消息鑒別碼運算方法聲明voidSSF_MacInit()throwsResultCodeException參數(shù)keymacParam消息鑒別計算相關(guān)參數(shù)，包括初始返回值無拋出異常ResultCodeException.SSF_FAILResultCodeException.SSF_UNKNOWNERR異常錯誤ResultCodeException.SSF_