Signing your app

Before you can distribute your applications on the BlackBerry World storefront, you must first sign them. Signing an app is a matter of requesting a .bar or .cod file signature from the BlackBerry Signing Authority. You can sign your app using the Ripple emulator, or using the command-line tools.

Before you start, make sure you have configured your computer for code signing. See Set up for signing for more information.

  • Why must I sign my app?

    The main reason that apps must be signed is for security.

    Apps must be signed for security and export control reasons whenever certain sensitive BlackBerry APIs are used. Because the BlackBerry WebWorks Packager framework makes use of some of those sensitive APIs, all WebWorks apps must be signed before they can run on a BlackBerry device.

    Signing is used to provide proof of authorship. By signing your app, you are binding your (or your company's) identity to the apps that you develop and distribute to users. This proof of authorship protects both you as the developer, and the user, since the source of the app can be traced and cannot be altered.

    And, perhaps the most important reason, at least for developers: apps must be signed before they can make you money. Until apps are signed, they cannot be distributed through, and generate income from, the BlackBerry World storefront.

  • When must I sign my app?

    You'll need to sign your WebWorks app whenever you want to load it onto a device.

    You can deploy and test an unsigned app on a simulator at any time. For more information on testing your app on a simulator, see Deploy to a simulator.

Sign a BlackBerry 7 or earlier app

You can sign your smartphone application by using the Ripple emulator or the BlackBerry WebWorks SDK. The BlackBerry WebWorks SDK is a command-line tool, whereas the Ripple emulator is a UI-based tool.

Before you begin: Make sure that you have performed the setup to sign applications. This setup needs to be performed only once. For more information, see Set up for signing.

Using the BlackBerry WebWorks SDK to sign your app

You can sign your app at the same time that you package it by adding the -g <password> option to the package command.

Before you begin: Make sure that you have created an archive file (zip file) of your app.

  1. At a command prompt, navigate to the installation folder for the BlackBerry WebWorks SDK, where the bbwp.exe file is located. The file path may vary based on where you installed the BlackBerry WebWorks SDK.
    For Windows XP:
    cd C:\Program Files\Research In Motion\BlackBerry WebWorks SDK <version>
    For Windows 7:
    cd C:\Program Files (x86)\Research In Motion\BlackBerry WebWorks SDK <version>
    For Mac OS:
    cd "/Developer/SDKs/Research In Motion/BlackBerry WebWorks SDK <version>"
  2. Type the following command to package and sign your app:
    bbwp <archive_file> -g <password> -o <output_location>
    where:
    • <archive_file> is the name and location of the app archive file (your zip file)
    • <password> is the password that you specified when you registered your code signing keys with the RIM Signing Authority
    • <output_location> is the location where you want the output files to be created

    Windows example:

    bbwp C:\myapp\HelloWorld.zip -g mypassword -o C:\myapp\signed

    Mac OS example:

    ./bbwp ~/myapp/HelloWorld.zip -g mypassword -o ~/myapp/signed

    When you execute this command, the BlackBerry WebWorks SDK packages your app and then starts the BlackBerry Signature Tool to sign your app.


    This image displays the results when you sign your application at a command line.

    After your app is successfully signed:
    • The RIM Signing Authority sends you email messages indicating that your app was successfully signed.
    • The BlackBerry WebWorks SDK creates two folders: OTAInstall and StandardInstall in the output location you specified. These folders contain the signed COD files.

OTAInstall and StandardInstall folders

When you package and build your app with the BlackBerry WebWorks SDK, two folders are created: OTAInstall and StandardInstall. These folders contain the files you will need to deploy your app. If you choose to deploy your app by using the BlackBerry Desktop Manager or from a BlackBerry Enterprise Server, you use the files in the StandardInstall directory. This includes all the *.cod files and the *.alx file.

If you are deploying your app by having a user click a link in their BlackBerry Browser, you will need the files from the OTAInstall directory (OTA is short for "over the air"). This includes all the *.cod files and *.jad file. You post the *.jad and *.cod files on a web server and provide the user with the URL to the *.jad file.

Viewing the approval status

If you want to view the status of your signed files, perform the following steps:

  1. Start the BlackBerry Signature Tool:
    1. From a command prompt, navigate to the bin folder in the BlackBerry WebWorks SDK installation folder.
    2. Type the following command:
      java -jar SignatureTool.jar
  2. In the BlackBerry Signature Tool, browse to your COD file.
  3. View the Status column.


    Displays the Signature Tool.

    For files that are signed, the Status column contains Signed. For files that are not signed, the Status column contains Failed. A .cod file might be rejected because you typed an incorrect private key password.

Using the Ripple emulator to sign your app

In the Ripple emulator, you can sign your app at the same time that you build it.

First, you need to fill in some settings for signing:

  1. In the Ripple emulator, select the Build panel.
  2. Select Settings.
  3. In the Password field, type the password that you used to register your signing key.
  4. Close the Settings window to save your changes.

    The fields in the Build section need to be filled in as well because you are building the app, then signing it. For more information about the build settings, see Package with the Ripple emulator

Now, to sign the app:

  1. If the build and deploy services are not currently running, click Start Services.
  2. Select Package & Sign.

The Ripple emulator builds and signs your app. Make sure that you pay attention to the console messages to determine whether signing is successful. The Ripple emulator indicates when the package and build is completed successfully, but does not determine the status of app signing.

After the process completes successfully, the .zip and signed .cod files for the app are stored in the output folder that you specified in the settings.

Last modified: 2013-10-02