中国移动TSM平台接入开发指引.docx

中国移动TSM平台接入开发指引.docx

《中国移动TSM平台接入开发指引.docx》由会员分享，可在线阅读，更多相关《中国移动TSM平台接入开发指引.docx（46页珍藏版）》请在冰豆网上搜索。

中国移动TSM平台接入开发指引

多应用开放平台

应用接入开发指引

目录

1术语5

2平台概况5

2.1平台概述5

3开发范围5

3.1应用模式5

3.2应用客户端6

3.3NFC-SIM卡应用6

3.4业务平台6

4开发流程6

5流程说明7

5.1应用流程7

5.1.1下载7

5.1.2删除9

5.1.3应用更新10

6卡应用开发指南11

6.1卡应用开发模式11

6.2卡应用开发要求12

6.3密钥交换流程12

6.4卡应用开发12

6.5卡应用发布更新12

7客户端开发指南12

7.1应用客户端开发要求12

7.2客户端开发准备12

7.3设置开发环境13

7.4客户端开发16

7.4.1创建工程16

7.4.2编写AndroidManifest.xml文件16

7.4.3手机客户端开发编码17

7.4.4代码示例18

3.1客户端发布更新18

4业务平台开发指南18

4.1接口描述18

4.1.1WebService名字空间18

4.1.2接口列表18

4.1.3数据类型说明19

4.1.4数据域说明19

4.1.5消息类型描述21

5.5.1.CreateSSDReq25

5.5.2.CreateSSDReqResponse25

5.5.3.DeleteSSDReq25

5.5.4.DeleteSSDReqResponse26

5.5.5.UpdateDomainKeyReq26

5.5.6.UpdateDomainKeyReqResponse26

5.5.7.DownloadApplicationReq27

5.5.8.DownloadApplicationReqResponse27

5.5.9.ApplicationAPDUReq27

5.5.10.ApplicationAPDUReqResponse28

5.5.11.DeleteApplicationReq28

5.5.12.DeleteApplicationReqResponse29

5.5.13.LockApplicationReq29

5.5.14.LockApplicationReqResponse29

5.5.15.AcquireTokenReq29

5.5.16.AcquireTokenReqResponse30

5常见问题30

1术语

术语

解释

BOSS

BusinessOperationSupportSystem业务运营支撑系统

2平台概况

2.1平台概述

NFC手机钱包是中国移动向各个应用合作方开放的一套完整的NFC业务端到端的解决方案，可以向应用合作方开放NFC手机终端非接式卡模拟能力、多应用管理平台（TSM）业务接口、NFC-SIM上的安全存储空间、和包客户端集成接口等NFC应用各个环节上所需的资源，帮助各个应用合作方根据自身业务流程开发出支持不同业务的NFC应用，并集成在中国移动NFC手机钱包这个大的业务平台中，统一向所有中国移动的用户进行推广。

本文档是用于对各应用合作方开发各自的NFC应用进行一个基础性的技术指引，明确产品开发的一个基本流程，提供开发过程中可能需要用到的各类技术文档的索引，并对开发过程中可能遇到的技术问题进行解答。

本文档适用于NFC手机钱包应用产品开发技术人员阅读

3开发范围

3.1应用模式

NFC应用包含几下几种模式，每次模式对应的开发范围也是不一样的，几种应用模式开发范围如下：

1、纯客户端模式

应用所有功能均直接由应用客户端实现，应用的相关数据没有安全存储要求，均可随客户端一起直接存储于手机的存储空间中。

典型应用有：

NFC名片应用。

2、客户端结合卡应用模式

应用的业务功能由应用客户端与NFC-SIM卡应用交互完成，应用中涉及用户敏感数据，需要将其存储在NFC-SIM的安全存储空间中，确保数据安全。

典型应用有：

简单公交卡应用（不支持空中开卡、空中充值）、旅游卡、电子门票等。

3、客户端、卡应用加业务平台模式

应用的业务功能由应用客户端与NFC-SIM卡应用、业务平台交互完成，客户端本地与NFC-SIM交互，实现应用数据在SIM卡上的安全存储，客户端远端通过移动互联网与业务平台交互，实现相应的业务功能。

典型应用有：

金融PBOC应用、公交卡应用（支持空中开卡、空中充值）。

3.2应用客户端

应用客户端开发包含应用客户端的界面交互设计、客户端业务处理逻辑以及对NFC-SIM卡的访问逻辑。

3.3NFC-SIM卡应用

NFC-SIM卡上应用处理逻辑，包括卡应用文件结构定义与实现、卡应用与客户端交互指令的定义与实现、卡应用与非接受理机具交互指令的定义与实现。

3.4业务平台

实现NFC应用业务平台侧的相关处理功能，通过与TSM平台对接，可以由业务平台侧获取到用户手机号状态变更、业务订购关系变化等通知信息，以便进行相应的业务处理。

4开发流程

5流程说明

5.1应用流程

5.1.1下载

正常流程：

1、用户在和包客户端卡应用超市点击应用下载。

2、和包客户端向多应用开放平台发送应用下载请求。

3、多应用开放平台向业务平台发起“预操作请求”（SessionType为1）。

4、业务平台审核用户下载请求，如果审核通过返回0000；否则返回错误码和错误信息，预处理响应中ProviderSessionID字段不能为空，该值由业务平台生成并保证唯一性。

5、多应用开放平台向和包客户端返回写卡指令。

6、和包客户端和多应用开放平台多次交互完成辅助安全域创建、辅助安全域初始密钥加载、SE应用下载、安装。

7、多应用开放平台向业务平台发起“SE操作反馈请求”，SessionID与“预操作响应”的ProviderSessionID一致。

8、业务平台返回结果。

9、下载应用客户端插件。

10、和包客户端主界面显示新下载的应用图片。

11、用户点击卡片图片启动客户端插件。

12、用户在客户端插件中申请卡片。

13、客户端插件向银行后台发送用户申请请求。

14、通知用户申请通过。

15、用户再次进入客户端插件。

16、客户端插件从银行获取个人化数据对应用进行个人化。

17、完成应用下载。

说明：

1、如果辅助安全域在SIM卡上已经存在，不会重复创建辅助安全域

5.1.2删除

1、用户在客户端插件中发起注销卡请求。

2、银行业务平台处理用户注销卡请求，并通过客户端插件处理卡上余额。

3、用户在和包客户端应用管理界面请求删除应用。

4、和包客户端向多应用开放平台发送应用删除请求。

5、多应用开放平台向业务平台发起“预操作请求”（SessionType为2，SessionID为新生成）。

6、业务平台审核用户下载请求，如果审核通过返回0000；否则返回错误码和错误信息，预处理响应中ProviderSessionID字段不能为空，该值由业务平台生成并保证唯一性。

7、多应用开放平台向和包客户端返回写卡指令。

8、和包客户端和多应用开放平台多次交互完成SE应用删除。

9、多应用开放平台向业务平台发起“SE操作反馈请求”，SessionID与“预操作响应”的ProviderSessionID一致。

10、业务平台返回结果

11、和包客户端删除应用的客户端

12、应用删除完成

说明：

1、用户卡片个人化后未进行注销操作，银行业务平台应该在“预操作请求”时返回错误信息提示用户先进行注销，避免卡上有余额造成用户损失。

2、完成应用删除后如果辅助安全域中没有其他应用，将会删除该辅助安全域。

5.1.3应用更新

1、用户在手机钱包客户端主界面请求更新应用。

2、手机钱包客户端向多应用开放平台发送应用更新请求。

3、多应用开放平台向业务平台发起“预操作请求”（SessionType为3，SessionID为新生成）。

4、业务平台审核用户下载请求，如果审核通过返回0000；否则返回错误码和错误信息，预处理响应中ProviderSessionID字段不能为空，该值由业务平台生成并保证唯一性。

5、多应用开放平台向手机钱包客户端返回写卡指令。

6、手机钱包客户端和多应用开放平台多次交互完成SE应用更新。

7、多应用开放平台向业务平台发起“SE操作反馈请求”，SessionID与“预操作响应”的ProviderSessionID一致。

8、业务平台返回结果，如果需要进行个人化，响应报文中含个人化数据

9、如果业务平台响应报文中不含个人化数据，跳到15，否则。

10、多应用开放平台向手机钱包客户端返回个人化指令。

11、手机钱包客户端依次向SE发送个人化APDU指令，直到所有APDU执行完毕，或卡片返回错误（SW不为9000）。

12、手机钱包客户端向多应用开放平台返回最后一条APDU执行结果。

13、多应用开放平台向业务平台发起“SE操作反馈请求”，SessionID与“预操作请求”时一直，通过CardPOR发送最后一条APDU执行结果。

14、重复9到13步直到个人化过程完成。

15、多应用开放平台向手机钱包客户端返回结果。

16、应用更新完成。

异常处理

1、第4步时，业务平台对本次更新请求审核不通过，向用户提示业务平台返回的错误信息，流程结束。

2、第5-6步过程中出现异常，用户可以在手机钱包主界面重新请求更新应用，重新更新应用时会再次向业务平台发起“预操作请求”。

3、卡片执行个人化指令时，指令执行的结果通过“SE操作反馈请求”发送给业务平台，由业务平台判断当指令执行状态字（SW）不为9000时是否继续执行。

4、第7-14步过程中发生错误，用户可以在手机钱包主界面对该应用进行删除操作，或在应用超市界面重新下载该应用。

用户在应用超市重新下载改应用时，多应用平台会重新发起预处理请求，然后删除实例并重新创建，再重新执行7-14步的流程。

6卡应用开发指南

6.1卡应用开发模式

●移植模式

如果卡应用之前已经在IC卡上实现，那么只需要将原卡应用的文件结构，指令定义提交给NFC-SIM卡的卡商，便可由卡商协助完成卡应用的移植工作。

●委托开发模式

如果卡应用需全新开发，可以将卡应用的需求描述清楚，委托NFC-SIM卡的卡商进行开发。

因为卡应用开发需要对卡片有一定了解，具有较强的专业性，建议采用委托卡商开发的模式来完成卡应用开发。

现阶段，各家卡商为了推广卡片，提升市场占有率，一般会比较积极的接收开发需求。

6.2卡应用开发要求

1、空间要求：

金融类卡应用对RAM空间占用不超过1.5K，其他卡应用对RAM空间占用不超0.5K。

2、卡应用返回码要求：

除61xx-6Fxx&9xxx外的返回码都是非法的状态字，可能会对卡片产生影响，卡应用需严格控制。

6.3密钥交换流程

如果卡应用有申请独立的辅助安全域，则需要对辅助安全域的初始密钥者约定，密钥约定有两种操作模式，一种是由应用合作方提供初始密钥，将密钥码单通过密码信封提供给电子商务基地，另一种是电子商务基地生成初始密钥，并将密钥码单通过密码信封提供给应用合作方。

6.4卡应用开发

一个典型的JavaCard设备有一个8或16位的运行在3.7MHz的中央处理器，带有1K的RAM和多于16K的非易失性存储器（可编程只读存储器或者闪存）。

高性能的智能卡带有单独的处理器和加密芯片，以及用于加密的内存，并且有一些还带有32位的中央处理器。

JavaCard技术规范目前是2.2版，由三部分组成：

1.JavaCard虚拟机规范，定义了用于智能卡的Java程序语言的一个子集和虚拟机。

2.JavaCard运行时环境规范，进一步定义了用于基于Java的智能卡的运行期行为。

3.JavaCard应用编程接口规范，定义了用于智能卡应用程序核心框架和扩展Java程序包和类。

6.4.1JavaCard开发教程之程序元素

完整的JavaCard应用程序由一个后端应用程序和系统、一个主机（卡外）应用程序、一个接口设备（读卡器）和卡上小应用程序、用户证书和支持软件组成。

所有的这些元素共同组成一个安全的端到端应用程序：

　　一个典型的JavaCard应用程序不是孤立的，而是包含卡端、读取端和后端元素。

让我们更详细的讲述一下每个元素。

后端应用程序和系统

后端应用程序提供了支持卡上Java小应用程序的服务。

例如，一个后端应用程序可以提供到安全系统和卡上的证书的连接，提供强大的安全性。

在一个电子付款系统中，后端应用程序可以提供到信用卡及其他付款信息的访问。

读取端主应用程序

主应用程序存在于一个例如个人计算机这样的台式机或者终端、电子付款终端、手机或者一个安全子系统中。

主应用程序处理用户、JavaCard小应用程序和供应商的后端应用程序之间的通讯。

读取端卡片接受设备

卡片接受设备（CAD）是处于主应用程序和JavaCard设备之间的接口设备。

一个CAD为卡片提供电力，以及与之进行电子或者射频通信。

一个CAD可能是一个使用串行端口附于台式计算机的读卡器，或者可能被整合到终端内，例如饭店或者加油站内的电子付款终端。

接口设备从主应用程序到卡片转送应用程序协议数据单元（ApplicationProtocolDataUnit，简称APDU）命令（在后面讨论），并且从卡片向主应用程序转送响应。

一些CAD有用于输入个人识别号码的键盘，有的可能还有显示屏。

卡片端小应用程序和环境

JavaCard平台是一个多应用程序环境。

卡片上可能存在一个或多个JavaCard小应用程序，还有支持软件--卡片的操作系统和JavaCard运行时环境（JCRE）一起。

JCRE由JavaCard虚拟机、JavaCardFramework和应用程序编程接口以及一些扩展应用程序编程接口组成。

所有的JavaCard小应用程序扩展Applet基本类，并且必须实现install（）和process（）方法；JCRE在安装小应用程序的时候调用install（），并且在每次有一个进入的用于小应用程序的APDU的时候调用process（）。

JavaCard小应用程序在被装载的时候实例化，并且在断电的时候保持运行。

JavaCard小应用程序起一个服务器的作用，并且是无源的。

在一张卡片被加电以后，每个小应用程序都保持非运行的状态直到它被选择，在此时可能会做初始化。

小应用程序只有在一个APDU被发送给它以后才被激活。

与JavaCard小应用程序通讯（访问智能卡）

可以使用两种模型中的任何一种来在一个主应用程序和一个JavaCard小应用程序之间通信。

第一个模型是基本消息传送模型，第二种是基于JavaCard远程方法调用（JCRMI），这是J2SERMI分布式对象模型的一个子集。

此外，SATSA通过一个基于更加抽象的应用编程接口的普通连接框架（GenericConnectionFramework，简称GCF）应用编程接口，让你要么使用消息传递要么使用JCRMI来访问智能卡。

6.5卡应用发布更新

1准备客户端信息

实例如果有多个,则需要填写多个实例信息,模块AID,实例AID安装参数也需要一并提供

a）应用AID

b）cap包数量

c）文件下载顺序

d）文件删除顺序

e）填写应用名称

f）文件AID

g）文件加载参数

h）实例数量

i）实例1

i.模块AID

ii.实例AID

iii.安装参数

j）……

k）实例N

2填写《TSM应用发布提交物列表》。

3提交到中国移动电子商务有限公司等待发布

7客户端开发指南

7.1应用客户端开发要求

应用客户端必须集成于和包客户端启动运行，要求不能有独立的启动入口，需对安装过程中的打开按钮进行屏蔽，并且不能生成桌面图标。

和包客户端在启动应用客户端时，会为应用客户端提供手机号、SEID等信息，以更应用客户端进行相应的业务处理。

7.2客户端开发准备

●首先开发者要有必须的Java开发基础，如果需要相关的知识，可以参考一下JavaTutor:

●配置Eclipse集成开发环境，如果没有Eclipse的话，到Eclipse的官方网站上去下载http:

//www.eclipse.org/

●安装了Eclipse后，还要在Eclipse下安装ADT插件。

如果没有ADT插件，下载地址为：

●开发者必须要具有Android应用的开发经验。

想获取更多的Android开发知识，请参考：

●开发用的设备必须支持OpenMobileAPI，是否支持这个API跟Android系统的版本和编译情况有关系。

目前支持NFC功能的终端设备，多数都支持此API。

比如三星S3、S4、Note3；HTCM7；小米3等等

●SIM卡的支持，在手机上开发和钱包的应用客户端，需要跟SIM卡的安全模块通信，所以需要办理支持NFC功能的SWP-SIM。

具体办理方式可以咨询10086，测试SIM卡的办理，可以联系移动电子商务基地。

7.3设置开发环境

●Eclipse的开发环境需要配置一下，以便能够使用Google官方最新的SDK版本。

开发者安装ADT的过程如下：

⏹点击Help菜单，选择InstallNewSoftware…

⏹在Install的对话框里，选择AddRepository，点Archive，选中你已经下载好的ADT插件，根据Wizard的提示，完成安装工作

●然后可以通过SDKManager去下载相应的SDK版本，手机钱包客户端要求Android的版本不低于2.2，APILevel最低为8：

●运行SDKManager，选中要安装的SDK即可，这些SDK必须要支持OpenMobileAPI。

具体操作方法如下：

⏹运行AndroidSDKManager

⏹点击 Tools -> ManageAdd-onSites...

⏹选择UserDefinedSites点击New，添加URL:

http:

//seek-for-

⏹不同的Android版本，对应着不同的APIlevels:

◆15--APIlevel15,Android4.0.3

◆16--未发布

◆15--APIlevel17,Android4.2.2

⏹重新加载Package列表：

在菜单上选择：

Packages->Reload

⏹Package列表刷新后，选择OpenMobileAPIunderAndroid4.2.2并且安装这个add-onpackage

⏹通过SDKManager安装OpenMobileAPIaddonpackage，接下来就可以开发安全模块（SecureElement）相关的应用程序了.

⏹OpenMobileAPI的相关文档参见下面附件：

●完成安装后，重启Eclipse，就可以使用下载好的SDK了。

●注意：

如果下载的AndroidSDK中没有OpenMobileAPI的Addon，可以直接以第三方jar包的方式引入openMobileAPI.jar文件。

需要注意的是在编译apk的时候，不要把此jar文件打入到apk中。

●具体的做法是：

在工程的JavaBuildPath中，创建一个UserLibrary，在此Library中添加openMobileApi.jar，做法如下图，这样在导出的apk中就不包含openMobileApi.jar的内容了。

在此处该jar只做编译用，运行时调用手机系统自己的相关类文件。

●在OrderandExport设置中，选择不导出包含OpenMobileAPI的的lib。

具体做法如下图：

●OpenMobileAPI的jar文件只做编译用，文件如下：

7.4客户端开发

下面简单介绍和包客户端开发过程。

7.4.1创建工程

1.使用Eclipse的wizard,创建新的Android工程，选择AndroidApplicationProject，点击Next之后，填充工程的基本属性。

2.选择CreateActivity->BlankActivity点击Next。

3.输入activity名称:

MainActivity点击完成，创建新的工程。

7.4.2编写AndroidManifest.xml文件

1在Android应用程序中，使用Manifest.xml文件来描述应用程序的基本属性。

在编写Manifest的时候应该注意两点个需要声明uses-permission，获得smarcard操作的相关权限。

如果用的NFC相关的API，还需要声明NFC相关的权限。

2另外一个就是声明uses-library，使用系统的OpenMobileAPI相关的lib。

这个地方required为true和false都行。

这个标签主要用于应用市场过滤应用程序。

如果为true，则对不支持OpenMobileAPI的手机屏蔽此应用。

3关于AndroidManifest声明的相关方法，请参考uses-libraryelement的官方文档，地址为：

7.4.3手机客户端开发编码

编码还需要实现具体业务的APPLICATION类与工具类

APPLICATION类实现

1.DEMO中创建了SlaveApp类，主要目的是为整个应用提供一个重要的全局变量：

SlaveClient类变量。

在该类中，先定义了一个成员变量。

2.在Application的onCreate函数中对这个成员变量初始化。

其中ConnectService函数完成对手机钱包服务的通信连接。

3.在完成初始化之后，对外提供函数，以便使用SlaveClient变量。

4.在使用完SlaveClient后，需要释放资源。

所以在Application的提供了exitApp（）函数。

此函数中，调用SlaveClient的shutDown函数。

5.实现这个三个主要函数后，SlaveApp的功能就基本实现了。

工具类的实现

1.整个Demo中，最重要的部分就是这个工具类，即SIMCardUtil类。

首先看该类的实现方式：

由于该类时用于打开逻辑通道，跟安全模块进行通信的，所以该类设计为单实例的。

2.在此类中，定义了三个成员变量：

a）privateSEServicemSEService;

b）privateSessionmSession;

c）privateStringerrMsg;

3.mSEService是创