《GM-T0127-2023 移动终端密码模块应用接口规范.docx》由会员分享，可在线阅读，更多相关《GM-T0127-2023 移动终端密码模块应用接口规范.docx（14页珍藏版）》请在课桌文档上搜索。
1、ICS35.0341CCS1.80中华人民共和国1行业标准GM/T01272023移动终端密码模块应用接口规范Mobi1.etermina1.cryptographicmodu1.eapp1.icationinterfacespecification20206-012023T2-04发布国家密码管理局发布目次前言III引吉IV1范围12规范性引用文件13术语和定义I4缩略谓25结构模型25.1 层次关系25.2 模块的应用结构26数据类型的定义36.1 算法标识和数据类型定义说明36.2 卷本数据类型定义36.3 受合数据类型定义47移动终端赛码模块应用接口77.1 概述77.2 密码算法实现
2、要求77.3 密码应用包定义87.4 密码应用接口定义87.5 密码模块类87.6 模块连接接口97.7 模块接口107.8 应用接口147.9 容器接11207.10 会话密馆接11297.11 密玛杂凑接口327.12 消息鉴别码接口347.13 带谢钊的杂凑运算接口368安全要求378.1 模块使用阶段378.2 权限管理378.3 其他安全要求38附录AaJe范性）异常码预定义值和说明39前三本文件按照GB，T1.12020必不准化工作9则第1部分：标准化文件的结构和起草规则的规定起草.请注意本文件的某些内容可能涉及专利.本文件的发布机构不承担识别专利的责任.本文件由密玛行业标准化技术
3、委员会提出并日口。本文件起审单位；中国科学院数据与通信保护研究教育中心、中国科学技术大学、中国科学院信息工程研究所、北京数字认证股份有限公司、北京理工大学、长春告大正元信国技术股份有限公司、北京交通大学、中国信息通侑研究院、北京信安世纪科技股份有限公司、中国人寿保险股价由限公司研发中心、国家计尊机网络应急技术处理例调中心、中国电子技术标准化研究院、中国工业互联网研究院、中电科网燃安全科技股份有限公司、格尔软件股份有限公司、北京中电华大电子设计有限近任公司、北京创原天地科技有限公司、北京小雷科技行限公司、北京国脉信安科技有限公司、财付支村科技有限公司北京炼石同络技术有限公司、深宙服科技股份有限公
4、司、北京路云天网络安全技术研究院有限公司.本文件主要起草人：林身辎、贾世杰、郑昉昱、徐博文、马咏及鲁宇、肛冰冰.王安、岛旭、攀训、徐秀、汪宗福、徐丽娟、张晓娜、黄晶品、李琳、王平建、刘丽敏、王伟、牛莹蚊、赵欣怡、吕娜、雷灵光、钱文飞、典明坏、于成期、张立廷、尹一桦、赵雨明、街福1.李涛、王柞、肖云松、柳增寿、裳嶂、何畅、吴怡、白小明、鲍旭华、孔勇.在移动终涉上调用各类密码帙块实现宓玛服务的方式已逐渐普及，本文件目标是为各类移动终端密玛模块的实现提供统一的应用接口焜范，进一步推动密码律法在移动终端上的f署和应用。为移动终淘密码模块的开发、使用及检测提供标准依据和指导,有利于提高移动终端第码模块的
5、产品化.标准化和系列化水平.IV移动终端密码模块应用接口规范19本文件规定了移动终端密码模块的结构模型、数据类基定义、应用接口及安全要求。本文件适用于移动终端密码模块产品的研制和使用，以及基于该类密码产品的应用开发与检测。2短范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款.其中.注H期的引用文件，仅该日期对应的版本适用于本文件：不让日期的引用文件，其最痂成本(包括所有的修改维)适用于本文件.GB/T15852.1信息技术安全技术消息鉴别码第1部分：采用分组密码的机制GB32905信息安全技术SM3密眄杂凌驾法GBT32907信息安全技术SM4分组密码算法GB.T32
6、918(所有部分)信息安全技术SM2椭即曲践公钥密码算法GH/T33560信恩安全技术密码应用标识规范GB.T35276信息安全技术SM2密码算法使用规范GBfT37092信息安全技术密码模块安全要求GM(X)17-2023智能密码钥匙密码应用接口数据格式规范GM/Z4(X)1密码术谙3*XGMTZ41.界定的以及下列术语和定义适用于本文件.3.1密码模块CTyPIograPhiCmodu1.e实现了安全功能的硬件、软件和/或固件的集合，并且被包含在密码边界内，3.2Bodu1.eauthentication移动终端的码模块对应用程序的膝别.33模块鳖别宙的Bodu1.eauthenticat
7、ionkey用于模块鉴别的密的.3.4容SScontainer密码模块中用于保存密钥所划分的唯一性存储空间.35应用app1.ication包括PIN、文件和容潺的一种结构，具备独立的权限管理.4下列缩略谱适用于本文件.MAC:消息鉴别码(MeSSagCAuthcnticutionCode)PIN:个人身份识别码(PerSOnidIdemi1.kUtionNumber)55.1 次关系在移动终端中，移动终端密码模坡应用接口位于移动终端应用程序和移动终端密码模块之间，如EHI所示.B1移动弊由卫费央或用接口的位量移动绻蠲海网模块安装在移动线瓶中.支持密钢管理、轮码计算和取感信史存收等功能，移动终
8、端中的应用程序通过调用移动终端密码模块应用按1.1.执行相应的操作“5.2 ,伏的应用It构模块中存在模块鉴别密钥和多个应用，应用之间相互独立.应用由管理员P【N、用户PIN、文件和容器等组成，一个应用中可以存在多个文件和多个容器，一个应用中的文件、容器隔于同一个用户.个用户可使用个应用或者多个应用进行文件甘理与密钥管理等操作.婚个应用维护各自的与管理员PIN和用户P1.N相关的权限状态.应用的遗辑结构见图2。7.11.2 MfNrft方法声明voidSSFeDigesiInW1.onga1.gid,byte(IpubKey,byteIpucID)throwsRcsuhcodcExccptio
9、n功能描述杂凑初始化。参数a1.gid密码杂漆算法标识pubKcy签名者公份J当密码杂次尊法标识为SGD_SM3时有效pucID签名者ID做，当密码杂漆算法标识为SGD_SM3时有效返回值无抛出异常Resu1.tCkExceptin.SSF_FAI1.失败RCSUhCOdeEXCCPtionsS匕UNKNoWNERR异常tH误ResUitCOdCEXCCPtionSS卜KVA1.IDPARAMERR无效的参数ResuhCxfeExxpiion.SSF,NOTSUPPORT1.G不支持的标识备注当密码杂凑蚱法标识为SGD_SM3H.签名#ID值长度不为0的情况卜，PUbKCy和puc1.D有效,
10、执行DM2算法签名预处理1操作.计算过程遵循GB/T35276.7.11.3 单包敷m*方法声明bytc11SSF.Dgcst(byiedaia,)th11)wsRcsu1.tCtKkExccption功能描述对单一分包的消息进行诙码杂凑计算，并输出结果，参数data待计算数据，不能为空data1.en特计算数据长度返I可慎杂凑伯她出异常Resu1.icodeExcepiionfSF-HASHERR杂漆运算错误ResuhCodeExcption.SSF_NOTINIT1.A1.iZEERR未初始化7.11.4 4Mumw*w方法声明voidSSF.DigcstUpda(c(byte(data.
11、intdataifset.)1.hn)wsResuIICodeExccption功能描述对多个分包的消息诳行密码朵凑计兜，不怆出结果，参数daa待计算数据，不能为空dataffse待计算数据儡移data1.en待计算数据长度品注消息签别玛采用分组加率算法CBC模式，将加密结果的破后一块作为计算结果。侍计算数据的长度应是分组加密算法块长的倍数.接1.1.内部不做数据填充.7.12.3单包岫清方法声明byc11SSF.Mac(bytedata.)throwsRcsu1.tCodcExccption功能描述计算单一分包数据的消息鉴别码.并输出结果.参数data待计算数据返回返抛出异常da1.a1.e
12、n消息貌别码ReshCxteExcepdon.SSF.FAI1.恃计算数据长度失败需注Resu1.tcodeException.SsF-NOTIN1.TbX1.IZEERR未初始化调用SSF-MaC之前,应调用SSF_MaC1.niI消息签别码运算初始化操作，SSF_MaC等价于多次调用SSEYaC1.Pda1。之后再调用SSFMacFinaK7.12.4多包我提常皿胸运算方法声明voidSSF-MacUpdaiMbytcdata,intdataffsd.)th11)wsRcsu1.tCfcException功能描述计算多个分包数据的消息鉴别码，不输出结果。参数data待计算数据返回侑岫出异常
13、da1.aOfsc1.无Resu1.tCo1.eISSF-MacFinaK)throwsRcsu1.tCodcExccption功旎描述结束多个分包数据的消息签别码计算操作,输市消息鉴别码.多数无返回但消息签别码岫出异常Rcsu1.tCodcExccption.SSF_FAI1.失败Rcsu1.tcodcException-SSF-UNKNOWNERR异常错误备注SSF-MacFinaI应在SSF.MacUpdaie之后。SS7.13/密胡的杂，遗尊接口7.13.1 概建带烹用的杂次运算接口(IHMAe)主要完成带密期的杂凑运算的初始化、计算.IHMAC接口系列方法见表18.18IHMC三MW
14、SE类型定义说明voidSSFJMAC1.ni1.带空阴的杂潦运算初始化voidSSF.11MAOJpdate带密桃的多包杂次运电by1.cSSFJMACFirmi带玄的的杂渣运算结束7.13.2 ,击的泉帆撑初始化方法声明voidSSF-HMACInWbyickeyMhrowsRCSUhCodCEXCePtiOn功能描述三步式带密钥的数据杂浓运源的第一步.参数key密钢返回值无她出井常Rcsu1.tcodcExccption-SSF-FA1.1.失败RcsuitcodcExccption-SSF,Unknownerr异常错误Resu1.tCodeE.xcq)1.ion.SSF_OBJERR对
15、象他误7.13.3 帝国的的多包胡运算方法声明voidSSF_HMACUpdatc(byte(WaIa,intJ)throwsRcsu1.tCodcExccp1.ion功能描述三步式带密的的数据杂次运算的第二步,对输入的明文进行杂次运算,参数data特计算数擀daia1.en特计。数据长度返网也无她出异常RCSU1.ICodCEXCCPIiOn.SSF-FAI1.失败RCSUkCodCEXCCPtion.SSF_UNKNOWNERR异常错误ResukCodeException.SSFNoT1.NITIA1.1.ZEERR未初始化7.13.4 常密，的初运IUm方法声明byic11SSFHMAC
16、FinaK)throwsResu1.icodeExcepiion功能描述三步式带密包的数据杂次运算的第二.步.东凑运灯结束返PI结果.多数无返回值杂凑计簿结果附出异常Rcsu1.tcodcExccption-SSP-FA1.1.失败RCw1.1.COdCEXCCPtion.SSF_UNKNowNERR异常错误8安全要求&1模块使用阶段模块的使用分成两个阶段.a）出厂阶段：模块出厂时,预置模块鉴别密钥,在此阶段除修改模块鉴别密钥以及创建应用操作外，禁止其他操作.b）应用阶段：已创建门立用的模块进入应用阶段.在此阶段,可进行所有操作.&2wm&21枚JR分类权限分为模块权限、用户权限和管理员权限.
17、a）模块权限：通过模块鉴别后获得模块权限.b）用户权限：用户PIN码验证通过后,获得用户权限,用户权限只作用于其所在的应用.c）管理员权限：管理员P1.N码脸证通过后.获电管理员权限,管理员权限只作用于其所在的丽&22权限的使用遵新以下要求：a）模块权限仅用于创建应用、删除应用和修改模块盥别密钥：b）创建和删除容器需要用户权附；C）创建文件的权限在创建应用时指定：d）文件的读写权限在创建文件时指定：O容器内私钥的使用需要用户权限：0用户PIN码和管理员PIN码均具有最大重试次数，在创建应用时设定，当验证P1.N码错误次数达到点3人重试次数后,PIN吗即锁死：g）用户PIN码的解锁需要管理员权限
18、：h）用户P1.N码的修改需要用户权的.管理要PiN码的修改需要管理员权限.&23WMO应通过模块签别后才能在模块内创建和刷除应用。模块鉴别使用SM4分组密码律法和模块鉴别密知进行鉴别的流程如下：a被鉴别方调用模块按口的SSF-GenRandom方法从模块获取8字节1.机数RND.并用OXOO符其填充至密码算法的分块长度,组成数据块EXtb）被赛别方为Do加密，得到加密结果D1.,并调用模块接口的SSF-ModAuh将D1.发送至模块：C）模块收到DI后,验证DI是否正确.正确则通过模块签别否则模块鉴别失败.2.4PIN网安全要求PIN码安全要求如下：a) PIN码长度不少于6个字节：b) P
19、IN玛花模块和本接口之间的传输过程中应采取保护措施，防止P1.N码泄露:C)P1.N码在模块中应安全存i.不可从模块中导出.8.3其他安全要求移动终端密码模块的其他安全性设计应遵循GBa37092中的相关安全要求。（IR效性）鼻借码S1.盒义值加说明密码模块接口方法中异常用预定义值和说明见表A.UA.I鼻借码畏定义值和说明弁常玛预定义值说明SSF-FAI1.0x01)000001失败SSF1.SKNOWNhKR0x01)000002畀常钳误SSFNoTsUPPORTYETERROXODOoo003不支持的服务SSF-FI1.EERROxODOOOOai文件操作出误SSFINVAUDPARAYE
20、RROxODOOO5无效的参数ssF.redfi1.eerr0x01)000006读文件情误SSFUR1.TEF1.1.EERR(IXODoO(1007写文件错误SSFKME1.ENERR0x01)000008名称长度惘误SSFKEYVSMiEERR0x01)000009密期使用忸江SSPMO(XJ1.uS1.EM承ROxODOOOOO模的长度错误SSFNotinitia1.izeerrOxOI)OOOOOB未初始化SSF.0BJERROxODOOO(K)C-对象的误SSFMemoryhrr0x01)000001)内存错误ssFTimeoiiterrOxODOOOOOE超时SSi-Indata
21、1.exerrOxODOOOOOF输入数据长度忸误SsfjndataerrOxODOOOO1.O输入收据错误SSFGENRAXDERROxODOOOO11生成随机数错误ssFhshobjerrOxODOOOO12杂凑对象错误SSFHASHERR0x01)000013杂次运弟忸误ssFHashwtewa1.err0x01)000014杂凑值不相等SS1.-KEYNnTFo(N)ERR0x01X)00015密的未发现SSF工HnWFOINDERR0x01)000016证书未发现ssFNotexporterrOxODOOOO17对望未导出SSF-DeCRYPTPADERROxODOOOO18解密时做
22、补丁操作SSFMAC1.EXERR0x01X)00019MAC长度忸误ssFBiffertoosma1.1.Ox01)D0001缓冲区不足SSFj(EYINfotypeerrOxODOOOOIB密期类4?他误SSFYOTEVENTERROxODOOOO1.C无事件懵谋SSFM(X)Removederr0x01)00001D模块已移除*.1鼻常码黑定义值和说明续）异常码预定义值说明SSF_P1NINCORRECTOxODOOOOIEP1.N不正确SsF_PIN1.OCKEDOxO(X)OOOIFPIN被锁死SSFPININVA1.ID0x01.)000020P1.N无效SSF-PJN1.Eff1
23、.ANGEOXODooO021PIN长度错误SsFUSERA1.READY1.oGGEDIN0x01.)000022用户已经登录SSF,USERPINNOTINITIAI.IZEDOXQMK)I)023没有初始化用户口令SSFMoo1.ocked0x01)000024模块已锁定SSFiUSERTYPEINVAuD0x0XK)0025P1.N类熨错课ssbApp1.icatiosmmeinva1.id0x0D0026应用名称无效SSFAPP1.1CT1OEXISTS0x00X)0027险用已经存在SSFUSERN(Xn.OGGEDINOXODooO028用户没有登录SSFapp1.ication
24、otexists0x0DW0029应用不存在SSFJH1.ea1.readyexisisOxOD00002A文件已经存在SSF.NOROOM0x0XK)002B空间不足SSF-EH.ErX1.S-IS0x0D002C文件不存在SSFREAaRMXCoMAINERCouNTOxOOX)OD2D已达到量大可管理容器致SSFTOONOTEX1.ST0x01.XX002E模块不存在SSFCONTA1.NERXOTEKIST0x0XK)002F容港不存在Ssf_containera1.readyexist0x0)000030容器已经存在SSFPINERROXODOOO031PIN错误SSF_USERCA
25、NCE1.ERROXoDOoO032用户取消错误ssf_APP1.aIqna1.readyopened0x0XM)0033应用己经打开SSF_CQNTAINERA1.READYOPdEDOXODoOOo34容器己羟打开ssFEncrypterr0x0DW0035加密错误SsF一ENCRYpTPADERR0x01.)000036加密填充恰误SSF)ECRYPTERROXQDa)D037解密播课SSFJ1ARSEERR0x01)000038解析错误SSF_COMPtTEERROx。RoOOO39计算将设SSFHarwareerr0x0DOO003饿件情误ssFDatakeyerrOxO(XX)OOBB加密密钥错误SSFOTAITHoRIZIn)0x0D0O003C未签别ssFNotsipporta1.g0x0D0O003D不支持的标识
