【YD通讯标准】 网络电子身份标识 eID 移动应用接口技术要求

ICS35.110
中华人民共和国通信行业标准
YD/T3152-2016
网络电子身份标识eID移动应用接口技术要求
TechnicalRequirementsforelDMobileApplicationInterface2016-07-11发布
2016-10-01实施
中华人民共和国工业和信息化部发布前
范围·
2规范性引用文件
3术语、定义和缩略语
4eID移动应用服务
5eID移动应用注册要求·
6eID移动应用接口
附录A（资料性附录）接口调用示例附录B（资料性附录）
附录C（规范性附录）
参考文献
移动应用接口函数交互图·
错误码定义
YD/T3152-2016
YD/T3152-2016
本标准属于网络电子身份标识eID相关服务与应用接口系列标准之一，该系列标准包括：《网络电子身份标识eID桌面应用接口技术要求》《网络电子身份标识eID移动应用接口技术要求》《网络电子身份标识eID验证服务接口技术要求》《网络电子身份标识eID桌面应用接口测试方法》《网络电子身份标识eID移动应用接口测试方法》《网络电子身份标识eID验证服务接口测试方法》本标准依据GB/T1.1-2009给出的规则起草。请注意本文件的某些内容可能涉及专利，本文件的发布机构不承担识别这些专利的责任本标准由中国通信标准化协会提出并归口。本标准由公安部第三研究所、中国科学院软件研究所、北京中电华大电子设计有限责任公司、国防科学技术大学计算机学院、北京邮电大学、中国科学院信息工程研究所等单位起草。本标准主要起草人：邹翔、杨明慧、汪志鹏、倪力舜、赵宏伟、高志刚、兰天，李树栋、落红卫、高峰、柳扬、全拥、邓璐、许晋、周薇、戴娇。Ⅱ
iiiKAoNiKAca
YD/T3152-2016
本技术要求旨在规范接口的命名：统一接口调用方式，方便eID移动应用接入；减少多个功能库的共用接口，减小维护成本：方便在此基础上添加新的功能接口。本文件主要描述第三方应用通过移动终端访问eID卡的接口。第三方应用后台与eID服务平台的交互参见《网络电子身份标识eID验证服务接口技术要求》Ⅲ
TiiKAoNiKAca
1范围
网络电子身份标识eID移动应用接口技术要求本标准规范了eID应用于移动应用的相关接口技术要求。本标准适用于eID移动应用接口。2规范性引用文件
YD/T3152-2016
下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅注日期的版本适用于本文件，凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。YD/T3150-2016网络电子身份标识eID验证服务接口技术要求YD/T2592-2013身份管理(IdM)术语3术语、定义和缩略语
3.1术语和定义
YD/T2592-2013界定的以及下列术语和定义适用于本文件。3.1.1
片elDmobileapplicationclientelD移动应用客户端
在移动终端上实现eID实名认证、账号保护和安全登录服务的客户端软件。3.2缩略词
下列缩略语适用于本文件。
eIDAuth
idCarrier
electronic Identity
Near Field Communicationwww.bzxz.net
Personal Identification NumberResultInfo
Software DevelopmentKit
4elD移动应用服务
4.1基本功能
网络电子身份标识
eID认证对象
杂凑算法
载体唯一标识符
近距离无线通信
个人识别码
返回结果对象
软件开发工具包
eID移动应用服务主要为eID移动应用提供三个功能：实名认证、账号保护、安全登录。eID移动应用通过接口技术方法与eID交互，使用以下这三个服务功能。4.2移动实名认证
TiiKAoiKAca
YD/T3152-2016
eID移动实名认证为eID移动应用提供安全便捷的移动端实名认证服务。用户下载eID移动应用客户端，安装并绑定自已的eID卡后，用户即可通过手机刷eID卡的方式进行eID移动应用的实名认证业务4.3移动账号保护
4.3.1基本功能
eID的账号保护，即自建立eID第三方应用账号和eID之间的绑定关系起，一旦发生用户账号被盗或忘记口令的情况时，用户只需要刷eID卡就可以重置账号信息，让账号重新回到用户手中，eID账号保护包括账号绑定和账号找回两个过程。4.3.2账号绑定
eID移动账号绑定为eID移动应用提供安全便捷的移动端账号绑定服务。用户下载eID移动应用客户端并安装后，即可通过手机刷eID卡的方式进行eID移动应用的账号绑定业务。4.3.3账号找回
eID移动账号找回为eID移动应用提供安全便捷的移动端账号找回服务。用户下载eID移动应用客户端，安装并绑定自已的eID卡后，用户即可通过手机刷eID卡并输入PIN码的方式进行eID移动应用的账号找回业务。
4.4移动安全登录
eID移动安全登录为eID移动应用提供安全便捷的移动端登录服务。用户下载eID移动应用客户端，安装并绑定自已的eID卡后，用户即可通过手机刷eID卡的方式进行eID移动应用的登录业务。5elD移动应用注册要求
第三方应用接入eID系统前，需联系eID服务平台进行注册。具体的规范描述见YD/T3150-2016《网络电子身份标识eID验证服务接口技术要求》。6elD移动应用接口
6.1接口函数列表
通过调用eID移动应用接口，eID移动应用可以实现eID基本服务功能的接入使用与应用改造。对于eID移动应用，可以通过以下两种层次访问eID卡：—API层访问
一应用层访间
通过这两种方式访问eID卡的应用接口函数如表1所示，接口函数交互图详见附录C。表1elD移动应用接口函数列
函数名
isSupportNFC
openDevice
closeDevice
geteDNO
getldCarrier
verifyPIN
privateKeySign
检测设备是否支持且开启NFC
打开设备
关闭设备
eID序列号获取
idCarrier获取
PIN码校验
杂凑算法
私钥签名
对应章节
TiiKAoNiKAca
函数名
publicKeyVerify
getCertInfo
getErrorDescription
getInstance
isEIDAppInstalled
elDAppEventListener
addListenter
removeListenter
startEIDApp
isEIDAppSupportAPI
getVersion
getEIDAppSupportAPI
getEIDAppVerCode
getEIDAppVerName
6.2API层访问
API层访问接口方法
公钥验证签名
获取证书信息
获取结果码描述
表1（续）
eIDAuth实例获取
eID移动应用客户端安装判断
监听器实现
监听器添加
监听器删除
eID移动应用客户端启动
最低版本要求
SDK版本获取
eID移动应用客户端最低版本号获取eID移动应用客户端版本号获取
eID移动应用客户端版本名获取
YD/T3152-2016
对应章节
API层访问方式是将对eID卡的操作嵌入到移动应用中，由移动应用直接访问eID卡的方式。其接口是嵌入式SDK接口。对eID卡的操作方法包括：检测设备是否支持且开启NFC
打开设备
一关闭设备
获取eID序列号
一获取idCarrier
校验PIN码
—一杂凑算法
私钥签名
一一公钥验证签名
获取证书信息
获取结果码描述
检测设备是否支持且开启NFC
函数名：isSupportNFC。
输入：当前上下文环境。
输出：返回结果。
说明：为0表示支持NFC：1表示不支持NFC：2表示支持但未开启NFC。6.2.3打开设备
函数名：openDevice。
输入：NFC发现的卡。
HiiKAoNiKAca
YD/T3152-2016
输出：返回结果对象ri。
说明：例如，ri.errorCode为o表示成功；非o表示失败。6.2.4关闭设备
函数名：closeDevice。
输入：无。
输出：返回结果对象ri。
说明：例如，ri.errorCode为o表示成功；非o表示失败。6.2.5获取elD序列号
函数名：geteIDNO
输入：无。
输出：返回结果对象ri。
说明：例如，ri.errorCode为0表示成功，可通过ri.result得到eID序列号信息（48字节）：非0表示失败。6.2.6获取idCarrier
函数名：getIdCarrier。
输入：无。
输出：返回结果对象ri。
说明：例如，ri.errorCode为0表示成功，可通过ri.result得到idCarrier信息（12字节）：非0表示失败。6.2.7校验PIN码
函数名：verifyPIN。
输入：string类型的待验证eID卡的PIN码值，一般是412位数字。输出：返回结果对象ri。
说明：例如，ri.errorCode为0表示该PIN码与卡实际PIN一致：非0表示不一致6.2.8杂算法
函数名：hash
输入：字符型或字符串类型的签名模式，需要根据具体的要求计算杂凑值。输出：返回结果对象ri。
说明：例如，ri.errorCode为o表示计算hash值成功，可通过ri.result得到新的签名：非o表示计算hash值失败。
6.2.9私钥签名
函数名：privateKeySign。
输入：要签名的十六进制字符串或字节类型数组。输出：返回结果对象ri。
说明：例如错误代码ri.errorCode为o表示签名成功，可以通过result拿到签名结果：非零表示签名失败。
6.2.10公钥验证签名
函数名：publicKeyVerify。
输入：原文数据的十六进制字符串，和验签数据的十六进制字符串。4
HiiKAoNiKAca
返回：返回结果对象ri。
说明：例如ri为true表示验签成功，false表示验签失败。6.2.11获取证书信息
函数名：getCertInfo。
输入：获取到的证书信息。
输出：返回结果对象ri。
YD/T3152-2016
说明：例如，错误代码ri.errorCode为o表示获取证书信息成功：非零表示获取证书信息失败。6.2.12获取结果码的描述
函数名：getErrorDescription。输入：结果码errorCode。
返回：返回结果码描述的字符串。说明：结果码参考附录C《错误码定义》。6.3应用层访问
6.3.1应用层访问接口方法
应用层访问方式是由移动应用调用eID移动应用客户端以访问eID卡的方式。其接口是交互式SDK接口。接口方法包括：
获取eIDAuth实例
一判断eID移动应用客户端是否安装实现监听器
一添加监听器
一删除监听器
一一启动eID移动应用客户端
一一判断当前安装的eID移动应用客户端是否符合SDK所支持的最低版本要求一一获取SDK版本
-获取SDK所支持的eID移动应用客户端最低版本号一一获取当前安装的eID移动应用客户端版本号获取当前安装的eID移动应用客户端版本名6.3.2elDAuth获取
eIDAuth是eID认证对象，是调用者与eID移动应用客户端之间传递数据的桥梁。函数名：getInstance。
输入：context类型的当前elD移动应用客户端的运行上下文。输出：eIDAuth实例。
6.3.3elD移动应用客户端安装判断函数名：isEIDAppInstalled。
输入：无。
输出：布尔类型的返回值，true表示安装；false表示未安装。5
HiiKAoNiKAca
YD/T3152-2016
说明：建议在启动eID移动应用客户端之前作检查，判断eID移动应用客户端是否安装。6.3.4监听器实现
应通过实现下列接口来监听eID移动应用客户端事件消息：函数名：eIDAppEventListener。输入：string类型的第三方应用包名，启动eID移动应用客户端时传入的：integer类型的eID移动应用客户端事件消息结果码。
输出：无。
说明：建议先检查传入的第三方应用包名字符串是否与自已的应用包名完全一致，如果一致，则处理；如果不一致，则可以忽略。6.3.5监听器添加
函数名：addListenter。
输入：string类型的移动应用的包名；eID移动应用客户端事件消息监听器（6.3.4中所述）。输出：integer类型的返回码，0表示成功；非0表示失败。说明：如果用户需要监听，应增加一个派生类实现EIDAppEventListener接口，从而通过其参数获取事件消息。添加监听器后可以收到eID移动应用客户端的事件消息，例如认证结果信息。6.3.6监听器删除
接removeListenter。
输入：无。
输出：无。
说明：当不再监听eID移动应用客户端事件消息时，必须删除监听器。6.3.7elD移动应用客户端启动
函数名：startEIDApp。
输入：string类型的待授权认证的数据字串；string类型的保留字段。输出：integer类型的返回码，0表示成功：非0表示失败。6.3.8最低版本要求
函数名：isEIDAppSupportAPI。输入：无。
输出：布尔类型的返回码，true表示符合；false表示不符合。说明：判断当前安装的eID移动应用客户端是否符合SDK所支持的最低版本，建议先调用isEIDAppInstalled来判断eID移动应用客户端是否已安装。6.3.9SDK版本获取
函数名：getVersion。
输入：无。
输出：string类型的版本字符串，形如1.0.0.0。6.3.10最低版本号获取
函数名：getEIDAppSupportAPI。输入：无。
输出：int类型的版本号。
说明：获取SDK所支持的eID移动应用客户端最低版本号。6.3.11eID移动应用客户端版本号获取函数名：getEIDAppVerCode
输入：无。
输出：int类型的版本号值，如果未安装，则返回错误码。说明：获取当前安装的eID移动应用客户端版本号。2elD移动应用客户端版本名获取6.3.12
函数名：getEIDAppVerName
输入：无。
输出：string类型的版本字符串，如果未安装，则返回null。说明：获取当前安装的eID移动应用客户端版本名称YD/T3152-2016
YD/T3152-2016
附录A
（资料性附录）
接口调用示例
用java语言编写的接口调用简单示例如下（应用层访问方式）：package com.example.test:
import com.trimps.eid.sdk.openapi.EIDAppEventListener:import com.trimps.eid.sdk.openapi.EIDAuth;....
public class MainActivity
extends Activity
implements EIDAppEventListener private static final String TAG=MainActivity.class.getNameO:EIDAuthauth=null;
protected void onCreate(Bundle savedInstanceState) super.onCreate(savedInstanceState):setContentView(R.layout.activity_main):auth = EIDAuth.getInstance(this):auth.addListenter(this.getPackageName(),this):booleancode=auth.isEIDAppInstalledOLog.d(TAG, \eID App installed :\+ code);code = auth.isEIDAppSupportAPIO:Log.d(TAG,\can be supported by SDK :\+ code);int verCode= auth.getEIDAppVerCodeO:Log.d(TAG, \verCode =\+ verCode):String verName = auth.getEIDAppVerNameO:Log.d(TAG,\verName=\+
verName)：
int ret=auth.startEIDApp(\subo4110\,\):Log.d(TAG,\ret=\+ret);
public booleanonCreateOptionsMenu(Menu menu) getMenulnflaterO.inflate(R.menu.main, menu);return true:
public void onError(String argo, int argl) Log.d(TAG, \onError - yourPkgName=\ + argo ):Log.d(TAG,\onError-code=\+argl):protected void onDestroyO
auth.removeListenterO:
super.onDestroyO;
小提示：此标准内容仅展示完整标准里的部分截取内容，若需要完整标准请到上方自行免费下载完整标准文档。