Setting up your computer for debugging and signing

Before you can test your app on a BlackBerry 10 device or sign it for distribution through BlackBerry World, you need to set up your computer for debugging and signing. To get your computer set up, you need use your BlackBerry ID to request a BlackBerry ID token. You can then use that BlackBerry ID token to create a developer certificate.

Before you begin:

To request a BlackBerry ID token, you first need a BlackBerry ID. A BlackBerry ID identifies you to BlackBerry, whether you are accessing BlackBerry websites, apps, or services from your computer or your device. End users as well as developers need to have a BlackBerry ID. If you don't already have one, you can get one at http://us.blackberry.com/bbid.html.

Using the BlackBerry ID token is new in BlackBerry WebWorks 2.0. If you are updating an app created using an earlier version of WebWorks, you can link your legacy token (barsigner.csk) to your new BlackBerry ID token (bbidtoken.csk) to maintain continuity. For more information, see Linking your BlackBerry ID token to a signing authority account.

Questions about signing and debugging? Check out the Frequently Asked Questions.

Request your BlackBerry ID token

  1. Go to https://developer.blackberry.com/codesigning and login using your BlackBerry ID credentials.
    You can also access this page from the Certificates page of SDK web tool.
  2. Enter and confirm the password you want to use to secure your BlackBerry ID token, and then click Get Token. The password is also used to create your developer certificate. Provide this password whenever you want to sign a completed app, or test an unsigned app on a BlackBerry 10 device.

    If you forget this password, we can't retrieve or reset it for you. To recover from a forgotten password, you must request another BlackBerry ID token, then recreate your developer certificate.

  3. Accept the license agreement and click Get Token.
After you finish:

The Signing Authority Service uses thisBlackBerry ID token (bbidtoken.csk) file for authentication when you sign your app using the associated developer certificate. Signing your app helps verify the integrity and authenticity of your app to users and to the BlackBerry 10 OS. The BlackBerry 10 WebWorks SDK also uses the BlackBerry ID token to create a debug token that allows you to test your unsigned apps on a BlackBerry 10 device.

Your BlackBerry ID token is valid for one year. When it expires, you need to request a new one.

Create your developer certificate

To sign apps and create debug tokens, you must use your BlackBerry ID token to create a developer certificate. Each time you request a new BlackBerry ID token, you must create a new developer certificate.

Create your developer certificate using the SDK web tool

  1. On the Start menu, click BlackBerry >BlackBerry WebWorks <version>. A new browser window opens, displaying the BlackBerry 10 WebWorks SDK web tool.
  2. In the navigation panel, click Certificates.
  3. In the Location field of the Install group, enter the full path to your bbidtoken.csk file. For example, c:\users\<name>\downloads\bbidtoken.csk.
  4. Click Install Signing Token. The signing key (bbidtoken.csk) is installed to the following location:
    • Windows XP: %HOMEPATH%\Local Settings\Application Data\Research In Motion
    • Windows Vista, Windows 7, and Windows 8: %HOMEPATH%\AppData\Local\Research In Motion
    • Mac OS: ~/Library/Research In Motion
    • Ubuntu: ~/.rim
  5. In the Keystore Password field, enter your BlackBerry ID token password.
  6. In the Company name field, type the name of the organization you want to associate with the developer certificate.
  7. Click Create Certificate. The developer certificate (the author.p12 file) is created in the same location as your signing key.

Create your developer certificate from the command line

  1. Copy your BlackBerry ID token (bbidtoken.csk) to the following directory:
    • Windows XP: %HOMEPATH%\Local Settings\Application Data\Research In Motion
    • Windows Vista, Windows 7, and Windows 8: %HOMEPATH%\AppData\Local\Research In Motion
    • Mac OS: ~/Library/Research In Motion
    • Ubuntu: ~/.rim
  2. From the command line, navigate to the cordova-blackberry/bin/dependencies/bb-tools/bin subfolder of your BlackBerry 10 WebWorks SDK installation folder.
  3. Run the blackberry-keytool command to create your developer certificate (author.p12 file).
    blackberry-keytool -genkeypair -storepass <bbidtoken_pw> -dname "cn=<company_name>"

    When you run this command, the author.p12 file is created in the same folder where you installed the bbidtoken.csk in Step 1.

    Check the table below for parameter details:

    Parameters Description
    -genkeypair

    Generates a key pair that consists of a private key and a public key.

    -storepass <bbidtoken_pw>

    Specifies the password you defined for your BlackBerry ID token.

    -dname "cn=<company_name>"

    Specifies the name to associate with the certificate that the tool creates.

Signing and debugging: Frequently Asked Questions

Why must I sign my app?

Signing your app is an important security step. Normally, every app that is installed on a BlackBerry 10 device must be signed.

Signing adds cryptographic hash values to your application .bar file, which help to verify the authorship of your app to other users and to the BlackBerry 10 OS. This process allows users to trace the origin of the app and feel confident that it is a safe app to use.

When must I sign my app?

Signing is the final step when you are ready to build the release version of your app. Each time you sign your app, you must increment the version of the app.

How do I sign my app?

With the BlackBerry WebWorks SDK, your app is automatically signed when you build a release version of the app using either the SDK web tool or the command-line tools. For information on signing your app, see Building and signing your completed app.

How do I test an app without increasing the version number?

During development, you can deploy an unsigned (debug) version of your app to a device for testing. To deploy an unsigned (debug) version of an app to a BlackBerry device, the device must have a valid debug token installed on it. For information on deploying an unsigned app to a device, see Deploying your app to a device.

What is a debug token?

A debug token allows you to install and run unsigned apps on a BlackBerry 10 device so you can debug your apps. Debug tokens are valid for 30 days. When a debug token expires, the BlackBerry 10 OS no longer allows unsigned apps that rely on that token to run.

You are limited to a total of 100 device PINs across the active debug tokens associated with the same keystore password. This restriction means that if you create and install debug tokens on 100 devices, you must wait for some of your debug tokens to expire before you create more.

How do I create a debug token?

With the BlackBerry WebWorks SDK, a debug token is created and installed automatically whenever it is required. If a valid token doesn't exist on the target device when you try to deploy your app, the SDK tools create and install the debug token for you. For more information about deploying your app to a BlackBerry 10 device, see Deploying your app to a device.

Do I have to create a debug token for every app I create?

Debug tokens are not specific to a single app. When you have a valid debug token installed on your BlackBerry 10 device, you can deploy any unsigned app that you have created to the device for testing until that debug token expires.

Last modified: 2014-12-04



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus