Signing page

Before you can distribute your application for use on a BlackBerry PlayBook tablet, you must sign your application. The signing tool included with the BlackBerry Native SDK for Tablet OS adds cryptographic hash values to your application package (.bar file) during the signing process. The hash files help verify the authorship of your application to users and the BlackBerry PlayBook OS.

  • Your application .bar files must be signed by BlackBerry to run on a device (on the Source page for the bar-descriptor.xml file, your application must have <action system="true">run_native</action> declared as a system capability). This capability ensures that the Signing Authority was able to confirm access to native application development.

    An application must be signed so that the platform can validate the integrity of the application; however, this doesn't apply to the simulator environment (there is no signing check performed on the simulator).

  • We recommend that you use the BlackBerry Tablet OS Deployment Setup Wizard to configure your computer for signing. For advanced configuration, use the Signing preferences page.

If you want to test your application on a device without signing it, you can create and install a debug token on the device (not required for the simulator). For more information about debug tokens, see Running unsigned applications using a debug token in the BlackBerry Native SDK for Tablet OS Getting Started Guide.

This page includes the following areas:

  • RIM Signing Authority
  • Developer Certificate
  • Backup and Restore
  • Debug Tokens

RIM Signing Authority

To distribute an application for use on a BlackBerry PlayBook tablet, you must first sign your application. The code signing keys also allow you to create a debug token. Debug Tokens are for tablet devices, not for the simulator.

  • If you're an individual developer, or a corporate lead responsible for signing and distribution of applications, to request a signing account, you can request permission to sign BlackBerry PlayBook OS applications by completing the web form at https://www.blackberry.com/SignedKeys . Once your application is accepted, you'll receive two CSJ registration files by email (a RIM Development Key (client-RDK-<id>.csj) file to sign the application, and a PlayBook debug token (client-PBDT-<id>.csj) file to generate debug tokens).
  • If you work for a corporation, your organization would own the signing account. In this case, you need to obtain a debug token from your corporate lead for your device.

Since debug tokens allow you to deploy unsigned applications to your device, you'll need to save these registration files on your computer; you'll need them when you configure your environment for application deployment. After you receive your CSJ registration files, you can configure your computer to create debug tokens. When you create a debug token, you specify the PIN for each tablet on which the token can be used. You can distribute the debug tokens you create to developers to install on those tablets, or install them yourself. You are limited to a total of 100 tablet PINs across all of your debug tokens that are currently active.

If you create debug tokens that address 100 PINs, you must wait for some of your debug tokens to expire before you create more.

Option Description
Registered Show whether you are registered; in order to create debug tokens and to sign applications, you must be registered with the RIM Signing Authority. If you've successfully registered, the IDE will update the Registered field from No to Yes.
Register Open the Register dialog to register with the RIM Signing Authority. You will tell the IDE where the two keys are located on your machine: the client-RDK-<id>.csj and client-PBDT-<id>.csj files.
  1. Click Browse to locate the RIM Developer Key (client-RDK-<id>.csj).
  2. Click Browse to locate the PlayBook Debug Token ( client-PBDT-<id>.csj)
  3. Type the PIN you provided to BlackBerry to obtain the keys.
  4. In the CSK Password field, type the password that you used when you registered for signing.
  5. Click OK.
  6. In the RIM Signing Authority area, verify that it now reads Yes (instead of No) opposite the Registered label.
  7. Click OK.

    Now, you will receive two emails from BlackBerry upon successful registration.

Unregister Change the registration from Yes to No. This means that you can't create debug tokens to sign applications, and you're no longer registered.

Developer Certificate

A developer certificate uniquely identifies you or your company as the author of your application.

You can use the signing tool to create a Developer Certificate, or to provide an existing Developer Certificate from another source. If you create a Developer Certificate using the signing tools, ensure that the author name (user or company name) field matches what you enter in the Author field on the registration form. If you have an existing Developer Certificate you use to sign your applications, ensure that the name you enter in the Author field on the registration form matches the name of your existing certificate. You won't be able to sign your BlackBerry PlayBook OS application if these names do not match.

In general, the developer certificate is created automatically when you click the Register.

Option Description
Path The location of the .p12 file containing your certificates:
  • For Windows XP, %HOMEPATH%\Local Settings\Application Data\Research In Motion
  • For Windows Vista and Windows 7, %HOMEPATH%\AppData\Local\Research In Motion
  • For Mac OS, ~/Library/Research In Motion
  • For Unix and Linux, ~/.rim

By default, %HOMEPATH% is C:\Documents and Settings on Windows XP, and C:\Users\<your_User_Id> on Windows Vista and Windows 7. You choose the file name and location of the author.p12 file when you create your Developer Certificate.

Author The name of the author for the purposes of running your application on a device using a debug token. This is the name that you used to request your code signing key (for example, your company name).
Create Certificate Create a new developer certificate:
Certificate Path
The location where you would like to store your code signing certificate. Click Browse to locate the certificate path to use.
Author
Type the name of the author of the application. This is the same name that you used to request your code signing key, for example, your company name. Ensure that this value matches the author element in your bar-descriptor.xml file. For more information about the bar-descriptor.xml file, see Configure application packaging in the bar-descriptor.xml file
Keystore Password
Specify the password for the Keystore; a password to control access to the certificate.
Confirm Keystore Password
Type the keystore password again to confirm.
Save Password
Save the password that you specify (you will be prompted for this password when performing various signing activities throughout your development process).
Select Certificate Select an existing developer certificate. Navigate to locate the certificate to use, and then click Open.

Backup and Restore

The .csj file is used to install your code signing keys. These keys can be used only once; they're disabled after a successful installation, which makes it important to back up your code signing keys after they've been installed.

Code signing keys can be restored on the original PC they were installed to, or restored on another computer. You can also use these steps to transfer your code signing keys to multiple computers and sign from any of them.
Option Description
Backup Back up your code signing keys after they have been installed. The files that need to be backed up are your author.p12, barsigner.csk and barsigner.db. These files are stored in a zip file in a central location in the user's profile directory, and they are used by all BlackBerry PlayBook OS development tools. Their location will vary based on the operating system you use (see Restore below).
Restore Restore the backed up code signing keys to the original PC where they were installed, or restore them to another computer.

To restore your code signing keys, copy the files back to the directory outlined below.

  • Windows XP, %HOMEPATH%\Local Settings\Application Data\Research In Motion
  • Windows Vista and Windows 7, %HOMEPATH%\AppData\Local\Research In Motion
  • Mac OS, ~/Library/Research In Motion
  • Unix and Linux, ~/.rim

By default, %HOMEPATH% is C:\Documents and Settings on Windows XP, and C:\Users\<your_login_Id> on Windows Vista and Windows 7. You chose the file name and location of the author.p12 file when you create your Developer Certificate. If a path is not specified, it will be placed in the directories outlined above. This file should also be backed up. However, a new .p12 file can be created without requesting a new set of BlackBerry PlayBook OS code signing keys from BlackBerry.

Debug Tokens

You can run unsigned applications on a BlackBerry tablet by using a debug token. Debug tokens allow you to separate the process of application creation and publication. A developer can create and test an application using a debug token, then deliver the application for signing and publication.

  1. In the Debug Tokens section, in the list of debug tokens, select the debug token you want to install on the tablet.
  2. Click Upload.
  3. On the Upload Debug Tokens to Devices screen, select the tablet where you want to install the debug token.
  4. Click OK.

    The tablet is now ready to accept unsigned applications.

    The debug token is not for a specific application. You can use the same debug token for as many applications as you like. The debug token is on a per author basis, which means that you can have the same debug token on different devices, as long as you specify all of the different PINs when creating it.
Option Description
Path Location of the debug token for a specified device.
Device PINs Each BlackBerry device is assigned a unique personal identification number (PIN).
Expiry Show the expiry information for the debug token. Debug tokens are valid for 30 days. When a debug token expires, the BlackBerry PlayBook OS no longer allows unsigned applications that rely on that token to run.
Create Open a dialog to create debug tokens. Required to test your application on a device without signing it. You can create and install a debug token on the device; however one is not required for the simulator.
Edit Modify an existing debug token from the list.
Renew Renew a debug token that has expired.
Import Import an existing debug token to allow you to separate the process of application creation and publication. You'll be prompted to provide the location of the debug token you were assigned (a .bar file), and then click Open. On the Preferences screen, in the Debug Tokens section, in the list of debug tokens, you should see the token you imported.
Upload Upload a debug token for the device.
  1. In the upper-right corner of the Home screen on your BlackBerry tablet, press the gear icon:

    The Gear icon.

    To open the BlackBerry tablet options.

  2. In the list of options, press Security.
  3. In the list of security options, press Development Mode.
  4. Press Upload Debug Token.
  5. In the IDE, click Windows > Preferences and then expand BlackBerry Tablet OS > Signing .
  6. In the Debug Tokens section, in the list of debug tokens, select the debug token you want to install on the tablet.
  7. Click Upload.
  8. On the Upload Debug Tokens to Devices screen, select the tablet where you want to install the debug token.
  9. Click OK.

    The tablet is now ready to accept unsigned applications.

Remove Remove a debug token from the list.
Details Show detailed information about the selected debug token.