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:
- Purchase your code signing keys online (available at no additional charge to Alliance members).
- 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.
- 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:
- BlackBerry Widget Packager 1.0
- BlackBerry Web Plug-in for Microsoft Visual Studio 2.0
- BlackBerry Web Plug-in for Eclipse 2.0
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.