Hack 98. Sign Your COD Files

To distribute your application, you first must request a certificate from RIM.

When you develop applications using the BlackBerry Simulator, everything runs smoothly. But once you deploy them to an actual handheld device, it may fail with an error message. To give RIM more central control, each application developer whose code accesses protected areas of the API must obtain security keys and sign his code before it will run on an actual BlackBerry handheld. This prevents viruses and nefarious actions on the BlackBerry platform.

The registration process is quite easy and self-explanatory. To get the exact information required to obtain a certificate, go to http://www.blackberry.com/developers/na/java/tools/controlledAPIs.shtml. Upon approval, you should soon receive some .csi executable files. Save and double-click these files on your Windows computer, and an application will appear that walks you through the process of generating a security key pair. You will be prompted to make up a new password that is used when you sign your application.

9.6.1. Sign Your Application

During the certificate process, you will have generated two files: SigTool.db and SigTool.csk. These files need to reside in the bin directory of the JDE.

Now build your application as usual. After a successful compile and build, go to the Build menu option and select Request Signatures. You will be presented with the Signature Tool, shown in Figure 9-8. The options are fairly self-explanatory, There are two you will be interested in using right away. This first is Add, which allows you to specify the COD files that need to be signed (this is where you will need to enter the password you created earlier during the certificate process). The second option, Request, sends a request to RIM to sign your COD files. The signature process occurs as the status column is updated. Upon a successful signature, the status will change to Signed. Note that all CODs that require a signature must have the status Signed.

Figure 9-8. Signature Tool

9.6.2. Failed Signatures

There are few reasons why the signature process may fail:

• Your certificate has expired. You will need to contact RIM to extend or reapply for new certificate.

• You have exceeded the number of signatures. For security reasons, you are given a limit of how many times you can sign the COD file. But don't worry; the limit is usually some large number so it won't hinder your development. If you actually do hit the limit, you'll have to get another set of keys from RIM.

• If you reinstall or upgrade the JDE and you wipe out the SigTool files, simply drop the SigTool files back into the bin directory. If you lost these files you will have to contact RIM.

• The RIM Signature server may be down. Contact RIM developer support to check on this.

• Make sure you have a working Internet connection.

Once you sign your application, you can now deploy it like any other application.

9.6.3. Automated Build Script

Of course in the mobile world with hundreds of different devices, using a build tool such as Ant (http://ant.apache.org/) or Antenna (http://antenna.sourceforge.net/), is quite common. So the next question is whether there is a way to sign the COD files via a command-line interface (CLI). Fortunately, there is. Under the bin directory, you should find the executable JAR file called SignatureTool.jar. To use it, run java -jar SignatureTool.jar [-a] [-c] [-C] filename, where -a automatically request signatures, -c closes the program after a successful signing, -C forces the program to close even if the signature fails, and filename is of course the COD file to sign.

9.6.3.1. See Also

• http://www.blackberry.com/developer/

• http://ant.apache.org/

• http://antenna.sourceforge.net

Jason Lam