Testing and Deployment

[#1]

Research In Motion® (RIM) must track the use of sensitive APIs noted as signed when used by applications for security and export control reasons. If you use these controlled classes or methods in your applications, your application must be signed with a key or a signature provided by RIM before you can load the application .cod files onto the BlackBerry® smartphone.  All applications created using the BlackBerry® WebWorks™ Application Platform make use of secured APIs internally, and therefore must be signed.  All applications built for the BlackBerry® Tablet OS must also be signed before the .bar files can be run on physical hardware.

Code signing is not required when applications are loaded and tested on a BlackBerry Smartphone Simulator.

Developers order code signing keys from RIM, and receive a set of files that are then installed on their development machine.  The BlackBerry development tools are then able to provide these key files to the BlackBerry Signature Tool when the developer requests that their application be signed.  The BlackBerry Signature applies a unique signature, representing the identity of the developer, to all *.cod files that compose a BlackBerry application.  Developers should not share their code signing keys with others.

As explained below, the complete steps for setting up and using BlackBerry code signing process are:

1. Order Code Signing Keys from RIM
2. Install Code Signing Keys
3. Sign Application using the BlackBerry development tools

1. Order Code Signing Keys

Developers can register their code signing keys online.  As part of the registration process, developers must choose and provide a PIN that they will use while installing their code signing keys.  BlackBerry Code Signing keys are free of charge.  Once registered, a set of 3 keys and installation instructions will each be delivered in a separate email.  Code signing keys do not have any form of expiry, and can be used indefinitely to sign many BlackBerry applications.  

Typically, registration for code signing keys is processed within 2 hours.  If you haven’t received your keys within 2 hours of submitting the registration form, please check your spam filters, the keys will be addressed from websigner@ws-smtp.rim.net.  If you are unable to locate them contact BlackBerry support at CodeSigningOrders@BlackBerry.com.

2. Install BlackBerry Code Signing Keys

An email will be sent to the address used during the registration process.  This email will include attached code signing key files, and instructions for how these files should be installed.

All code signing keys received need to be installed on the same PC.  The same password must be specified for all keys on the same PC.  You should receive each key/.csi file in a separate email message.

To register the attachment, please follow the instructions below:

BlackBerry® Java® Plug-in for Eclipse®:

1. Save all 3 .csi files, sent via email, into the same directory.
2. Start Eclipse®.
3. Click on the Window® menu item and then Preferences.  Expand the BlackBerry Java Plug-in and select "Install new Keys...".
4. Select one of the 3 .csi files saved in step 1 and click Open.
5. Click "Yes" to create a new key pair file.
6. Type a password for your private key of at least 8 characters, and type it again to confirm.  This is your private key password, which protects your private key. Please remember this password as you will be prompted for it each time signing is attempted or a signature key is installed.
7. Move your mouse to generate date for a new private key.
8. In the "Registration PIN" field, type the PIN number that you supplied when purchasing signature keys.
9. In the Private Key password field, type the password created in step 6.
10. Click "Register".
11. Click "Exit".
12. Repeat this process for the other csi files.

BlackBerry WebWorks SDK; BlackBerry® WebWorks® Plug-in for Eclipse®; BlackBerry WebWorks Plug-in for Microsoft® Visual Studio®:

1.  At the command prompt, navigate to the bin folder within the BlackBerry WebWorks Packager installation directory.  Default directories are:
BlackBerry WebWorks SDK and BlackBerry WebWorks Plug-in for Microsoft Visual Studio:
C:\Program Files\Research In Motion\BlackBerry Widget Packager\bin  

BlackBerry WebWorks Development Plug-in for Eclipse:
<Eclipse Installation>\plugins\ net.rim.browser.tools.wcpc\ wcpc\bin C:\Program Files\Research In Motion\BlackBerry Widget Packager\bin

2. Type the following command, including the full path of the .csi file:
java -jar SignatureTool.jar <.csi file path>

3.  If a dialog that a private key cannot be found appears, perform the following actions:
a. Click Yes.
b. Type a password for the private key.
c. Type the password to confirm it.
d. Click OK.
e. Move the mouse to generate data for the new private key.

4. In the Registration PIN field, type the PIN number that you supplied when purchasing signature keys.

5.  In the Private Key Password field, type a password of at least eight characters. This is the private key password.
6. Click Register.
7. Click Exit.

3. Sign Application using the BlackBerry Development Tools

The BlackBerry Signature Tool is used to apply a code signature to BlackBerry applications. For ease of use it has been integrated into all of the BlackBerry development tools.  Steps to sign your application using any of the following BlackBerry development tools are listed below:

When entering your signing authority password, ensure that you have correctly entered your registration PIN number.  If you enter the incorrect PIN 5 times, your keys will be deactivated.

Using the BlackBerry Java Plug-in for Eclipse:

1. Right click on your project in the Package Explorer window
2. Expand the "BlackBerry" menu item
3. Select "Sign with Signature Tool"
4. When prompted, enter the signing password you defined when installing your signature keys.

Using the BlackBerry WebWorks Plug-in for Eclipse:

1. Right click on your project in the Package Explorer window
2. Select "Build and Sign BlackBerry WebWorks Project"
3. When prompted, enter the signing password you defined when installing your signature keys.

Using the BlackBerry WebWorks Plug-in for Microsoft Visual Studio 2008:

1. Open "Configuration Manager" from the Build menu
2. Change the configuration type of your project to "Release Signed"
3. Press CTRL+SHIFT+B to build you application
4. When prompted, enter the signing password you defined when installing your signature keys.

Using the BlackBerry WebWorks Packager:

1. Open the command line prompt
2. Package your application like you normally would, except specify the "/g" argument, followed by your signing password.  You will not be prompted to enter your password, as it was included in the command line.

Once the code signing password has been provided, the development tool will launch the BlackBerry Signature Tool which will open in a new window.  You will see any necessary code signing keys applied to all COD files created as part of your application.

More Info

For further information on BlackBerry Controlled APIs and signing of applications, please refer to the BlackBerry Signature Tool Developer Guide.

If you are having difficulty installing or registering your signature keys please check the Signature Key and Code signing section of the Developer Knowledge Base.

If you continue to experience issues please use the code signing self-help form.

For more information on code signing, controlled APIs and signature keys, see Controlled APIs and Code Signing.