GM-T 0127-2023 移动终端密码模块应用接口规范

中华人民共和国密码行业标准移动终端密码模块应用接口规范国家密码管理局发布I 4缩略语 2 25.2模块的应用结构 2 3 36.2基本数据类型定义 36.3复合数据类型定义 4 77.1概述 77.2密码算法实现要求 7 87.4密码应用接口定义 87.5密码模块类 8 97.7模块接口 7.8应用接口 7.9容器接口 7.12消息鉴别码接口 7.13带密钥的杂凑运算接口 8安全要求 8.1模块使用阶段 8.2权限管理 8.3其他安全要求 附录A(规范性)异常码预定义值和说明 Ⅲ本文件按照GB/T1.1—2020《标准化工作导则第1部分：标准化文件的结构和起草规则》的规定起草。请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。本文件由密码行业标准化技术委员会提出并归口。本文件起草单位：中国科学院数据与通信保护研究教育中心、中国科学技术大学、中国科学院信息工程研究所、北京数字认证股份有限公司、北京理工大学、长春吉大正元信息技术股份有限公司、北京交通大学、中国信息通信研究院、北京信安世纪科技股份有限公司、中国人寿保险股份有限公司研发中心、国家计算机网络应急技求处理协调中心、中国电子技术标准化研究院、中国工业互联网研究院、中电科网络安全科技股份有限公司、格尔软件股份有限公司、北京中电华大电子设计有限责任公司、北京创原天地科技有限公司、北京小雷科技有限公司、北京国脉信安科技有限公司、财付通支付科技有限公司、北京炼石网络技术有限公司、深信服科技股份有限公司、北京路云天网络安全技术研究院有限公司。汪宗斌、徐丽娟、张晓娜、黄晶品、本理工里建、刘丽敏工伟。生量姣，赵欣怡吕娜雷灵光、钱文飞、唐明环、于成丽、张立廷、尹一型赵丽丽、黄福飞李涛在移动终端上调用各类密码模块实现密码服务的方式已逐渐普及，本文件目密码模块的实现提供统一的应用接口规范，进一步推动密码算法在移动终端1移动终端密码模块应用接口规范1范围本文件规定了移动终端密码模块的结构模型、数据类型定义、应用接口及安全要求。本文件适用于移动终端密码模块产品的研制和使用，以及基于该类密码产品的应用开发与检测。2规范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本(包括所有的修改单)适用于本文件。GB/T15852.1信息技术安全技术消息鉴别码第1部分；采用分组密码的机制GB/T32905信息安全技术SM3密码杂凑算法GB/T32907信息安全技术SMI分组密两算法GB/T33560信息安全技水密码应用标规范GB/T35276信息安全技木SM2密码章法使用规范GB/T37092信息安全技密码模块安全要求GM/To017-2023智能密码钥匙密码应用接口数据格式规范GM/Z4001密码术语3术语和定义GM/Z4001界定的以及下列术语和定义适用于本文件。密码模块cryptographicmodule实现了安全功能的硬件、软件和/或固件的集合，并目被包含在密码边界内。模块鉴别moduleauthentication移动终端密码模块对应用程序的鉴别。模块鉴别密钥moduleauthenticationkey用于模块鉴别的密钥。容器container密码模块中用于保存密钥所划分的唯一性存储空间。包括PIN、文件和容器的一种结构，具备独立的权限管理。2图1所示。移动终端密码模块应用接口:3定义4bytemajor}主版本号和次版本号以“.”分隔，例如，Versio次版本号VersionfirmwareVersion;}数据项描述见表35定义发行厂商信息非对称密码算法标识模块总空间大小用户可用空间大小能够处理的SM2加密数据大小能够处理的分组运算和杂凑运算的数据大小表4文件属性定义文件名文件大小创建文件时定义的文件大小写入权限写文件所需要的权限6longmaxRetryCount;}定义0为管理员PIN;1为用户PIN当值为0时，PIN码被锁定认PINtrue表示是出厂默认PIN;值说明模块状态未知7权限类型值说明管理员权限用户权限classBlockCipherPar}数据项描述见表8。表e版本定义定只针对CFB、OFB模式6.3.8SM2算法相关数据格式SM2私钥数据、SM2公钥数据、SM2加密数据、SM2签名数据以及SM2密钥对保护数据均以字节数组的方式进行传输，其数据格式均遵循GB/T35276。7移动终端密码模块应用接口本章以Java技术方案为例描述了移动终端密码模块中SM2/3/4系列算法的应用接口规范，使用SM2/3/4系列算法的应用可以调用这些应用接口以实现相应的密码功能。7.2密码算法实现要求在移动终端密码模块中，SM2椭圆曲线公钥密码算法实现应遵循GB/T32918(所有部分),SM3密码杂凑算法实现应遵循GB/T32905,SM4分组密码算法实现应遵循GB/T32907,消息鉴别码算法实现应遵循GB/T15852.1。8密码应用包定义见表9,密码应用包包含密码模块抽象类与密码应用接口。移动密码模块产品实项定义包名1次版本号0定义密码模块抽象类(GMCryptoMod),具体类定义classjava.lang.object—classcom.mob.crypto.GMCr提供模块连接接口(IModuleConnection)、模块接口(IModule)、应用接口(IApplication)、容器接口com.mob.crypto.IModu接口方法异常码应按照附录A进行定义和说明。接口方法描述仅列出常见异常，在密密码模块抽象类(GMCryptoMod)是移动终端密码模块的基类，所有密码模块的实现应扩展这个GMCryptoMod类成员变量见表10。9定义说明为0时表示该模块为硬件密码模块；为0时表示该模块不需要进行模块鉴别；为1时表示该模块需要进行模块鉴别模块连接接口主要完成对移动终端中的密码模块进行管理(包连接模更枚举模IModuleConmection接自系列方法见表方法声明IModuleSSF_ConneetMod()throwsResultCodeE功能描述连接一个模块。返回值IModule接口实现类对象抛出异常ResultCodeException.SSF_UNKNOWNERRResultCodeException.SSF_MOD方法声明List(String>SSF_EnumMod()throwsResultCodeE异常错误无sultCodeException.SSF_UNKRResultCodeException.SResultCodeException.SSF_MO异常错误定义说明断开模块获取模块信息模块鉴别修改模块鉴别密钥创建应用枚举应用删除应用打开应用备份应用恢复应用)throwsResultCodeException功能描述断开一个已经连接的模块抛出异常ResultCodeException.SSF_UNKNOWNERR异常错误ResultCodeException.SSF_MODLOCKED模块已锁定功能描述设置模块标签。抛出异常ResultCodeException于32字节ModInfosSSF_GetModI无ResultCodeException.SSF_UNKNOWNERR异常错误无ResultCodeException.SSF_UNKN无无抛出异常ResultCodeException.SSF_UNKNOWNERR异常错误抛出异常ResultCodeException.SSF_UNKNOWNERR异常错误抛出异常ResultCodeException.SSF_UNKNOWERR异常错误功能描述voidSSF_ChangeModAutbyte[]keyCipher无ResultCodeException.SSF_UNK权限要求：模块鉴别成功后才能使用。新模块鉴别密钥的密文通过使用原模块鉴别密钥对新模块鉴别密钥进行ECB加密得到。报文鉴别码由原模块鉴别密钥对含有keyCipher的数据进行CBC加密得到。报文鉴别码的计算过程应符合)throwsResultCo功能描述创建一个应用。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。定义说明关闭应用获取PIN相关信息SSF_EnumContainer除文件获取及件信息7.8.2关闭应用方法声明voldSSF_CloseApplication()throwsResultCodeException参数返回值抛出异常无无ResultCodeException.SResultCodeException.SSF_UNKN失败异常错误备注此方法不影响应用的安全状态。7.8.3修改PIN方法声明longSSF_ChangePIN(功能描述调用该方法可以修改管理员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参数adminPINnewUserPIN新的用户PIN值返回值管理员PIN码错误时，返回剩余重试次数抛出异常ResultCodeException.SSF_PININCORRECTResultCodeException.SSF_PResultCodeException.SSF_PINResultCodeException.SSF_NOTSUPPORPIN不正确PIN长度错误不支持的服务备注验证完管理员PIN才能够解锁用户PIN码，如果输入的管理员PIN不正确或者已经锁死，会调用失败，并返回管理员PIN的重试次数。7.8.7清除应用安全状态方法声明voidSSF_ClearSecureState(功能描述清除应用当前的安全状态。参数无返回值无抛出异常ResultCodeException.SSF_NOTSUPPORTYETERR方法声明IContainerSSpGroateConanerC功能描述创建一个容器参数containerNan返回值IContainer接自现类对象方法声明功能描述参数返回值抛出异常备注voidSSF_DeleteContaine删除容器。无ResultCodeException.SSF_CONTAINE不支持的服务容器名称容器已经存在容器名称容器不存在方法声明List(String>SSF_EnumCo功能描述枚举所有已经创建的容器。参数无返回值容器名称列表抛出异常ResultCodeException.SSF_UNKN异常错误功能描述打开一个容器。参数containerNameResultCodeException.SSF_CONTAINERlongwriteRights功能描述创建文件。readRights文件读权限(见6.3.6,可为各种权writeRights文件写权限(见6.3.6,可为)throwsResultCode功能描述枚举所有已经创建的文件。无文件名称列表ResultCodeException.SResultCodeException.SSF_UNKNResultCodeException.SSF_F方法声明)throwsResultCode功能描述获取文件信息。ResultCodeException.SSF_FILENResultCodeException.SSF_F方法声明byte[]SSF_ReadFile()throwsResultCode功能描述读取文件。文件数据ResultCodeException.SSF_FILEN方法声明voidSSF_WriteFile()throwsResultCode功能描述写文件。参数fileName返回值抛出异常返回值抛出异常备注无ResultCodeException.SSF_READ权限要求：须具备对该文件的写权限。偏移量，不可超过文件大小且大于待写入的数据写文件错误读文件错误7.9容器接口7.9.1概述容器接口(IContainer)主要完成数字证书的导入导出以及密码相关操作。移动终端与云服务协同数字签名是移动终端密码模块的重要实现方式，在容器接口中引入基于SM2的协同签名和解密系列方法(包括生成协同密钥对，SM2协同签名、SM2协同解密等功能)。各功能均可调用一次或多次请求生成与响应处理方法，通过协同密码机制标识参数以确定所使用的协同密码算法，并确定对相关参数的解析方法，从而实现对各类协同密码机制的兼容支持。IContaimer接口系列方法见表14表14IContainer接日系列方法说明SSF地p定理fcate是大数弯书导雷数字证书SM2签名SM2外部私钥解密(仅测试)SM2外部私钥签名(仅测试)SSF_GenerateAgreementDSM2生成密钥协商参数并输出SSF_GenerateAgreementDataAndSSF_genThresholdKeyPSSF_genThresholdKeyPairRespo定义说明SSF_thresholdSignDatSSF_thresholdSignDataResponSSF_thresholdDecryptRespon导出公钥外来对称密钥加密(仅测试)外来对称密钥解密(仅测试)导入会话密钥)throwsResultCodeException功能描述关闭容器。无无ResultCodeException.SSF_UNK)throwsResultCodeException无voidSSF_ImportCertifibooleansignFlag,无ResultCodeException.SSF_UNK7.9.5导出数字证书方法声明byte[]SSF_ExportCertificate(功能描述导出证书数据。参数signFlagtrue表示签名证书，false表示加密证书返回值证书数据抛出异常ResultCodeException.SSF_CERTNOTFOUNDERR证书未发现方法声明voidSSF_GenSM2KeyPair()throwsResultCodeExc参数algId算法标退(只支持SGD_SM2_1算法)返回值无抛出异常ResultCodeLxceptonS8F_UNKNOWNERR异常谱误备注权限要求：需要用意权限。7.9.7导入SM2加密密钥对功能描述导入SM2公私钥对。参数sm2EnvelopedKey受保护的加密密钥对，不能为空抛出异常ResultCodeException.SSF_UNKNOWNERR异常错误备注权限要求：需要用户权限。sm2EnvelopedKey数据格式为SM2密钥对的保护数据格式(见6.3.8)。7.9.8SM2签名方法声明byte[]SSF_SM2SignDat功能描述SM2签名(对原始数据的杂凑值进行签名)。参数返回值SM2签名值抛出异常ResultCodeException.SResultCodeException.SSF_UNKN计算错误异常错误备注权限要求：需要用户权限。输入数据为待签数据的杂凑值。当使用SM2算法时，该输入数据为待签数据经过ResultCodeException.SSF备注输入数据为待签数据的杂凑值。当使用SM2算法时，该输入数据为待签数据经过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备注输入数据为待签数据的杂凑值。当使用SM2算法时，该输入数据为待签数据经过功能描述byte[]SSF_GenerateAgreementDataWit发起方发起方ID,长度应不大于32字节ResultCodeException.SResultCodeException.SSF_UNKNbyte[]tempSM2PublicK功能描述响应方的临时SM2公钥响应方ID,长度应不大于32字节ResultCodeException.SSF_FAIL失败ResultCodeException.SSF_OBJ方法声明ISessionKeySSF_Generatbyte[]sponsorSM2PublicKbyte[]sponsorTempSM2PublicKbyte[]sponsorId,sponsorSM2PublicKeysponsorldID响应抛出异常ResultCodeException.SSF_FAILResultCodeException.SSF_UNKNOWNERR异常错误方法声明byte[]SSF_genThresholdKe功能描述生成SM2协同密钥对生成的请求数据。signFlag密钥对，false表示生成加密密抛出异常ResultCodeException.SSF_UNKNOWNERR方法声明yoidSSF_genThresholdKeyPairResponseProcess(对)无ResultCodeException.SSF_UNKN方法声明byte[]SSF_thresholdSignResultCodeException.SSF_COM输入数据为待签数据的杂凑值。当使用SM2算法时，该输入方法声明byte[]SSF_thresholdSignDataRe抛出异常ResultCodeException.SSF_COMPUTEERR计算错误方法声明byte[]SSF_thresholdDe功能描述生成SM2协同解密的请求数据。参数返回值抛出异常SM2协同解密请求数据ResultCodeExceptionsSF_DECRYPTERR协同解密机制标识待解密的密文数据协同解密机制所需参数解密错误7.9.23SM2协同解密响应处理方法声明bote[]sSF_thresholdDecryptResponseProcess()throwsResaliCorlelxc功能描述处理服务端反可的SM2J回解密响应消息，生成解密结果参数algId协同解密机制标识responseMS协同解密服务端响应消息返回值SM2协同解密运算结果抛出异常ResultCodeEtepron.SSFRYPT解密错误备注权限要求：需要用直权限。7.9.24导出公钥方法声明bye]SSFFxportPabliekey(XthrowsResultCodeException功能描述导出公钥。参数signFlagtrue表示导出签名公钥，false表示导出加密公钥返回值SM2公钥数据抛出异常ResultCodeException.SSF_FAIL失败ResultCodeException.SSF_UNKNOWNERR异常错误备注返回值SM2公钥数据格式为SM2公钥数据格式(见6.3.8)。7.9.25外来对称密钥加密方法声明byte[]SSF_ExtKeyEncrypt(功能描述使用外来加密密钥对指定数据进行加密，被加密的数据只包含单一分组，输出加密后的ResultCodeException.SResultCodeException.SSF_ENC抛出异常ResultCodeException.SSF_FAIL方法声明ISessionKeySSF_I抛出异常ResultCodeException.SSF_FAIL失败ResultCodeException.SSF_UNKNResultCodeException.SSF_OBJERR表15ISessionKey接口系列方法定义说明多包数据加密结束加密多包数据解密结束解密BlockCiphoiPuanbloakCpherParam功能描述对称加密祖始化段置对称经算法的相关参数。参数blockCipherPara分组密码参数返回值无抛出异常ResultCodeEecpfonSSF_FResultCodctrecptonStUNKNOWNERR常需送ResultCodeExcepton.7.10.3单包数据加密方法声明byte]SSF_Encrypt(功能描述对单一分包的消息进行加密，并输出加密结果。参数待加密数据待加密数据长度返回值密文数据抛出异常ResultCodeException.SSF_ENCRResultCodeException.SSF_ENCRYPTResultCodeException.SSF_ResultCodeException.SSF_INVALIDResultCodeException.SSF_NOTINITI加密错误加密填充错误对象错误无效的参数未初始化抛出异常ResultCodeException.SSF_NOTIResultCodeException.SSF_OBJERRbyte[]SSF_EncryptFin无抛出异常ResultCodeExceptionBlockCipherParamblockCi无ResultCodeException.SResultCodeException.SSF_UNKNResultCodeException.SSF_ResultCodeException.SSF_INVALID抛出异常ResultCodeExceptResultCodeException.SSF_NOTResultCodeException.SSF_NOTI无ResultCodeException.SSF_UNKN定义说明多包数据密码杂凑结束密码杂凑功能描述杂凑初始化。为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接口系列方法定义说明多包数据消息鉴别码运算方法声明voidSSF_MacInit()throwsResultCodeException参数keymacParam消息鉴别计算相关参数，包括初始返回值无抛出异常ResultCodeException.SSF_FAILResultCodeException.SSF_UNKNOWNERR异常错误ResultCodeException.SSF_