BlackBerry Widgets and Code Signing: What you need to know


BlackBerry® Widgets can be written entirely using web technologies like HTML and JavaScript®. However, a compiled BlackBerry Widget is simply a regular Java®-based BlackBerry® application. BlackBerry Widget developers must therefore be aware of an important requirement for deploying an application onto an actual BlackBerry® smartphone – code signing.

Has the following scenario happened to you?

After working tirelessly to create a beautiful looking BlackBerry Widget application, and having used a BlackBerry Smartphone Simulator to perform extensive testing on the many application features you have created, you eagerly load your application for the first time onto a real device. Anticipating a surreal and mind-blowing experience, you quickly search for your application’s icon to open it for the first time…

…and you get this:

Figure 1: Secure API prompt

I never saw that message during testing, what does this mean?

Don’t worry, you didn’t do anything wrong. This message simply means your application has not yet been assigned a RIM authorized code signature. The BlackBerry® Device Software has recognized that your application needs to use core BlackBerry® application program interfaces (APIs), but has not been granted the appropriate permission from RIM to do so, and therefore prevents your application from starting.

The reason you didn’t receive this message when loading your application onto the BlackBerry Smartphone Simulator is that the simulator does not perform this security check (this enables efficient deployment for testing purposes).

Why do BlackBerry Widgets need to be signed?

RIM must track the use of some BlackBerry APIs for security and export control reasons. If you use these controlled classes in your BlackBerry applications, your application must be signed using a signature key (provided by RIM) before you can load the application .cod files onto the BlackBerry smartphone.

APIs requiring signing are used during the compilation of BlackBerry Widget applications. If you have ever looked at the BlackBerry API reference document, you can see that any APIs requiring signing are indicated by a lock icon, or are otherwise noted as “signed”. Here is an example of one of the secured APIs used in packaging a BlackBerry Widget:

Figure 2: BlackBerry API Java Docs definition of secure API

How do I sign my BlackBerry Widget?

Setting up and signing a BlackBerry Widget application involves three steps:

  1. Purchase your code signing keys online (available at no additional charge to Alliance members).
  2. You will receive an email containing attached code signing keys, as well as instructions on where to save and how to configure them to be used on your developer machine.
  3. Sign your application using the BlackBerry Signature Tool.

BlackBerry code signing keys must be purchased from and registered with RIM. These keys are uniquely assigned to a developer and are good for life. During the registration process, you will set a password that you provide each time you make a code signing request.

The identity of the registered user is recognized each time any of the signature keys are used to sign an application. As such, it is very important that they are not shared among developers, as the registered user assumes responsibility for the implementation and use of the application that is signed. Never publish these keys online, as you have no way of knowing how they may be used if downloaded.

Finally, through the use of the BlackBerry Signature Tool, you can sign your BlackBerry Widget using any of the following development tools:

Code signing using the BlackBerry Widget Packager:

If you are using the BlackBerry Widget Packager, this can be performed by providing the /g command line argument along with your signing password while you are packaging your widget:

Figure 3: Packaging and Signing a BlackBerry Widget

Code signing using BlackBerry Web Plug-in for Microsoft Visual Studio 2.0:

Your application can automatically be signed each time you build it using the BlackBerry® Web Plug-in for Microsoft® Visual Studio® 2.0 by changing the active solution configuration from ‘debug’ to ‘release signed’. You can change this configuration through the Configuration Manager menu item, found in Microsoft Visual Studio’s Build menu.

Figure 4: Changing active configuration through Configuration Manager

After making this configuration change, the next time you build your Widget, you will be prompted to enter your signing password:

Figure 5: Prompt to enter signing password

Code signing using BlackBerry Web Plug-in for Eclipse 2.0:

When building your BlackBerry Widget project using the BlackBerry® Web Plug-in for Eclipse® 2.0, you can right click on your project name in the Package Explorer window to open a contextual menu. At the bottom of the menu are two options for building, including one that will apply code signatures to your COD file(s).

Figure 6: Menu item for signing a BlackBerry Widget

After selecting this menu option, you will be prompted to enter your signing password, after which your application will be built, and signed.

Figure 7: Prompt to enter signing password

BlackBerry Signature Tool

When the BlackBerry Signature Tool signs your Widget application, you will see the following screen open. This screen displays the list of APIs requiring signing that are used by your application. Each required signature will be applied, and you will see the value in the “Status” column change from “Not Signed” to “Signed”:

Figure 8: BlackBerry Signing Authority Tool

This is great! Now what?

Take a deep breath and smile. Your BlackBerry Widget is now ready to be used and can now be deployed to your users through venues like BlackBerry App World™. Congratulations! In the comments, tell us about the latest BlackBerry Widget you developed.

Eclipse is a trademark of Eclipse Foundation, Inc. Microsoft and Visual Studio are trademarks of Microsoft Corporation. Java and JavaScript are trademarks of Sun Microsystems, Inc.

About Adam S.

Adam is a Team Lead on the Developer Relations Team at BlackBerry. He manages technical relationships with ISVs as well as incubating the developing community ecosystem. Adam specializes in producing applications based on web and native technologies.

Join the conversation

Show comments Hide comments
+ -
  • Heiko Maass

    Got a question regarding the Blackberry Signature Tool:
    Everytime a .cod-File is signed, blackberry sends 3 confirmation emails.
    Due to the fact that our application is splitted up into 10 .cod-Files, each signing creates 30(!) confirmation emails.

    –> Is there any way to disable the “confirmation” mail sent by blackberry ?

  • astanley

    Hello Heiko,

    There is currently no way for developers to disable the confirmation emails that are sent during the code signing process. A change has been proposed that would allow users to configure this feature so that they are sent less emails (e.g. daily / weekly summary), however at this time there are no plans or efforts under way to implement this change. You can however setup a filter that will drop these emails into an easy to organize folder. I do this myself in Outlook, where all emails are automatically delivered to a folder named “code signing emails”.

    If you'd like to submit a request for a feature enhancement/change, please do so using the Developer Issue Tracker (…). This would help increase its visibility allowing other users to vote for your request and provide a way to capture a sense of the importance of making a change like this from other users.


  • Sam Shipley

    When I try to sign my widget using the widget packager with the /g paramater I get this messsage Cannot sign widget – cannot find signing keys. Where is the pacakager looking for the keys? I have purchased and registered the keys. My system is Windows XP SP3.


  • CjKun

    Hello Sam.
    I would like to know if you have been able to sign your application through Eclipse Widget Plugin 2.0…

    Thanks very much in advance

  • helmy

    hi there,
    1. I do aware of code signing, but is it possible that i can pump my app to blackberry without signing it. I don’t mind seeing pop-up telling about the security, but how i do prove the application really works on bb to my management before purchasing the key ($20).
    2. It is a long read of everything in Blackberry docs and FAQ. I simply want to ask , Do i have to buy each key for my applications ?


  • ate_fel

    the blackberry curve 8520 supports widgets created with Visual studio 2008??

blog comments powered by Disqus