1

第1章 使用受控API   

BlackBerry 受控API 代码签名

在本指南中描述的BlackBerry API访问是受限制的.使用了受限API的应用程序可以在模拟器上运行.尽管这样,在将这些应用程序加载到BlackBerry设备之前,你必须从RIM(Reseach In Motion)获得代码签名.参看8页的”代码签名”以获得更多信息.

BlackBerry API 包	描述
net.rim.blackberry.api.browser	此包允许应用程序可以调用BlackBerry浏览器，为了得到更多信息，参看51页的”在浏览器中显示内容”。
net.rim.blackberry.api.invoke	此包允许应用程序调用BlackBerry应用程序，如任务，消息，备忘以及电话。为了得到更多信息，参看83页的”启动BlackBerry应用程序”。
net.rim.blackberry.api.mail	此包允许应用程序和BlackBerry消息进行交互,发送,接收和打开消息为获得更多信息,.参看15页的”操作消息”.
net.rim.blackberry.api.mail.event	定义了消息事件以及监听者（Listener）接口来管理邮件事件。为了得到更多信息，参看15页的”邮件事件”.
net.rim.blackberry.api.menuitem	允许你增加客户定制的菜单项到BlackBerry的应用程序中，例如地址本，日历以及消息。为了得到更多信息，参看84页的”增加菜单项到BlackBerry应用程序中”.
net.rim.blackberry.api.options	允许应用程序在BlackBerry设备的选项中增加选项条目。为了得到更多信息，参看47页”增加选项”.
net.rim.blackberry.api.pdap	允许应用程序和BlackBerry个人信息管理（PIM）交互，PIM包括地址本，任务，日历。MIDP包javax.microedition.pim提供了大部分类似的功能。为了得到更多信息，参看 25页的”PIM API”.
net.rim.blackberry.api.phone	提供了访问电话程序的高级特性的功能。为了得到更多信息，参看 77页的”Phone API”.
net.rim.blackberry.api.phone.phonelogs	提供了访问电话呼叫历史记录的功能。为了得到更多信息,参看79页的”访问和管理电话记录”.
net.rim.device.api.browser.field	允许程序在界面上显示浏览器的字段。为了得到更多信息,参看51页的”在一个浏览器field上显示web内容”.
net.rim.device.api.browser.plugin	允许程序将对附加MIME类型的支持增加到BlackBerry浏览器上。为了得到更多信息,参看66页的”支持附加的MIME类型”.
net.rim.device.api.crypto.*	这些包提供数据安全的能力,包括数据加密和解密,数字签名,数据认证,以及认证管理.为获得更多信息,参看”API 参考”.
net.rim.device.api.io.http	此包允许应用程序作为一个或多个URL的提供者注册BlackBerry浏览器.为获得更多信息,参看71页的”作为一个HTTP 过滤项注册”.
net.rim.device.api.notification	提供方法来触发事件的通知以及响应系统和程序的事件。为了得到更多信息,参看115页的”通知API”.
net.rim.device.api.servicebook	允许程序增加，删除，以及访问服务预定接口，为了得到更多信息,参看113页的”访问安装和配置信息”.
net.rim.device.api.synchronization	此包允许应用程序执行备份和恢复客户数据的操作.为了解更多信息,参看104页的”增加备份持久数据的支持”.
net.rim.device.api.system	此包提供了一些类,这些类支持一些功能,例如持久数据存储,交互通信(interprocess communication),SMS,使用数据报的网络连接,以及应用程序管理. 为了解更多信息,参看129页的”应用程序管理器”. 为了解更多信息,参看111页的”使用数据报连接”. 为了解更多信息,参看89页的”存储持久数据”.

代码签名

在BlackBerry JDE中,因为安全和导出原因,RIM跟踪一些敏感API的使用.在API参考中,一个锁住的图标或者需要签名的文本,指明了敏感的类或方法.在文档中,对于一个包含签名方法的类,在页的顶部选择或清除SHOW Signed选项来查看或隐藏签名的方法.

如果你在你的应用程序中使用签名的类和方法,那么在你将.cod文件加载到BlackBerry设备中之前,这些.cod文件必须数字化签名.

[注: 在接收代码签名之前为了测试你的代码,使用模拟器.为了部署到BlackBerry设备,代码必须签名。

 
签名工具和BlackBerry JDE一起安装,使用此工具为你的.cod文件请求合适的签名.
  注: 永远不要将你的实际代码发给RIM.签名工具发送一个代码文件的SHA-1哈希,以至签名中心系统可以生成一个需要的签名.

代码签名验证

代码签名验证类型	描述
连接时(Linktime)验证	当你加载一个签名.cod文件到BlackBerry设备时,VM将此.cod文件域API库连接,并且检验.cod文件是否需要签名.如果没有签名,VM停止连接,并且不再加载应用程序.
运行时(Runtime)验证	当用户在BlackBerry设备上使用应用程序时,如果应用程序调用了一个需要签名的方法时,VM验证应用程序是否包含必要的签名.如果签名没有提供,将会抛出一个ControlledAccessException异常,并且要求的操作也不会执行.

为获得更多关于.csi文件的信息,参看10页的”注册代码签名”.为获得更多关于.csl和.cso文件的信息,参看11页的”请求代码签名”.

代码签名请求过程

1.         签名工具打开一个和签名认证系统的HTTP连接,并发送一个请求.这个请求包括了.csl和.cso文件中代码的哈希.不会把实际的代码发送到RIM.

2.         签名认证系统验证请求是否有效,并且将一个RIM私有键应用到每个.cod文件的哈希上,以创建一个签名.

3.         签名认证系统返回签名给签名工具,并关闭HTTP连接.

4.         签名工具将签名加到每个.cod文件中.

当文件签名以后,每个.cod文件的Status栏显示Signed.

如果在签名请求中有任何问题发生,Status栏显示Failed-See Details.

当你的.cod文件签名之后,你可以将它们加载到BlackBerry设备中.为获得更多信息,参看”BlackBerry应用程序开发者指南 第二卷高级 第一卷–基础”.

可选签名

在没有.cso文件签名下,你可以将应用程序加载到BlackBerry设备上.如果它们对应的方法在运行时被调用,那么仅仅需要这些签名.

当应用程序调用一个需要签名的方法时,VM验证应用程序是否有了这个认证.如果VM没有发现这些可选的签名,应用程序将会停止.

签名限制

存在着有几种情形,在这几种情形里,代码签名处理不会完成:

客户参数

签名认证管理员通过指定使用时间或者频率参数的限制,可以限制你访问签名.这些参数在你的.csi文件中有定义.当应用签名时注意这些可能的限制.

参数	定义
# of Request	本参数设置你可以使用指定.csi文件请求的次数.在使用了最大的请求次数之后,csi文件变为无效,并且你不可以再使用此文件请求签名.联系你的签名认证管理员应用另外一个.csi文件. 因安全原因请求受限制,尽管如此, 签名认证管理员可以允许你请求无限次.
Expiry Date	本参数设置你的csi文件的过期日期.在你的.csi文件过期后,你不能再使用此文件请求签名. 联系你的签名认证管理员应用另外一个.csi文件.

为了请求改变这些.csi参数, 联系你的签名认证管理员.

丢失数据

没有.csi文件,你不能请求任何代码签名.你的注册键在你的csi文件中存储. 如果签名工具不能找到此键,并通过此键处理你的请求,你的签名请求没有一个可以发送到签名认证系统.

如果你的系统停止响应,并且你丢失了数据,甚至整个文件结构,你可能会发现你也失去了完成签名请求的能力.如果你丢失了,csi文件,签名工具不能和签名认证系统进行通信,

如果你丢失了.csi文件,联系你的签名认证管理员,请求一个新的.

为代码签名注册

对于每台需要键的计算机,你需要一组独立的代码签名键.一旦这些键安装在一台计算机上,你不能重新安装或转移到其他的计算机上.

为代码签名注册

为了为代码签名注册，你必须有HTTP访问Internet的能力.

1.       为了激活你的帐户,完成在BlackBerry开发区里的注册表:

http://www.blackberry.com/developers.

2.       当你在一个来自RIM的email里接收到.csi文件时,将它们保存到你本地计算机.

3.       双击一个.csi文件

如果一个对话框显示一个私有键不能找到,在继续之前完成下面的操作

l         单击Yes创建一个新的值对文件.

l         为你的私有键输入一个密码,重新输入确认此密码.

l         单击OK.

l         移动你的鼠标,为新的私有值对生成数据.

4.       在Registration PIN域,输入签名请求表或者RIM提供的PIN值.

5.       在Private Key Password域里,输入至少8个字符的密码.这就是你的私有密码,它保护你的私有键.

注:保护好你的私有键密码. 如果你丢失了这个密码,你必须在RIM重新注册.如果你的密码被偷了,立即联系RIM撤销你的键阻止其他人使用你的身份请求签名.

6.       单击Register.

7.       单击Exit.

修改你的私有键密码

你必须有HTTP访问Internet的能力,以至你能修改你的私有键密码.

1.       在BlackBerry JDE bin文件夹里,双击SignatureTool.jar.

2.       在Old Password域里,输入你当前的私有键密码.

3.       单击Verify.

4.       <输入和确认新密码.

5.       单击OK.

请求代码签名

在IDE中请求一个代码签名

1.       编译你的项目

在IDE里的Build菜单里,单击Build All.IDE创建下列3个文件,它们放在和工程.jdp文件相同的目录下面,对于每个项目:

文件扩展名     描述

.cod文件       将加载到BlackBerry设备的已编译的项目.

.csl文件        需要的连接时签名列表.

.cso文件        如果应用程序调用受控API,可能在运行时需要的签名列表.

2.       在Build菜单,单击Request signatures.

     警告: 如果你已经通过以前的SDK为代码签名注册了,在安装一个新的BlackBerry JDE版本之前,备份这些文件,它们在BlackBerry JDE bin目录下.

    l Sigtool.db

l Sigtool.csk

          如果这些文件丢失,你必须通过RIM重新注册.

3.       单击Add.

4.       在Look In下拉列表里,单击.cod文件所在的目录.

5.       单击一个.cod文件.

6.       单击Open.

7.       单击Request

8.       输入私有键密码.

9.       单击OK.

在命令行强求签名

   1.       在命令行里,已到包含签名工具软件的目录.

   2.       输入下面的命令行

java -jar SignatureTool.jar [-a] [-c] [-C] <file>:

在这里:

[-a] 当你想程序自动请求签名时使用.

[-c] 当你想程序在请求签名没有发生错误后关闭时使用.

[-C] 当你想程序不考虑它的 成功时关闭时使用.

<file> 可以为一个(仅有一个).csi文件,或一个或多个.cod文件的名字.

  l         .csi:.csi文件包含了客户注册信息以及客户允许应用的签名列表.你仅可以一次使用一个.csi文件.

  l         .cod:.cod文件时编译的应用程序,在所以需要的签名到位后,它可以加载到BlackBerry设备.你可以传入你想要的.cod文件数.

• Last Updated：2007年01月22日
• Last Updated:   2006年04月28日