Getting code signing keys from RIM, then using them – Tutorial

Posted November 20th, 2008 by

Introduction

If you use certain BlackBerry APIs, you have to get code signing keys and sign your .COD file with them, before you will be able to install and run these applications on a BlackBerry device. You can learn more about which APIs need to be signed here. Here’s a short list of the APIs that require signing:

  1. Runtime APIs,
  2. BlackBerry Application APIs,
  3. BlackBerry Cryptography APIs,
  4. Certain other functionality, such as the ability to execute on startup also requires applications to be signed.

Books, devices, and accessories

If you’d like to buy BlackBerry devices, accessories, or user guides, from Amazon.com click here.

Buying the keys from RIM

It will cost you $20 USD in order to purchase a set of keys from RIM. Here’s the order form that you can use to get the keys. You will need to provide a private PIN number that you will need to remember for the steps that follow. Once you fill out the form, it will take about 5 business days. You should place an order for the keys on a Monday morning, to get the process expedited.

What happens if you don’t get your keys on time?

I didn’t get my keys on time, and I got really worried. There’s really no information out there on what to do when something goes wrong. When you fill out the form, you just get a generic ‘thank you’ message… there’s no transaction ID or anything to reference later on if you have issues. Also, you don’t get any confirmation emails with status updates. The ‘thank you’ message that you get has an 877 number for you to call, which isn’t really helpful! So here’s what you do if you run into problems:

  1. Call 519-888-7465, the main number to RIM HQ office and ask to be transferred to customer service.
  2. Tell them that you’re calling about the code signing keys you requested.
  3. They should be able to lookup the request using the name and email address that you provided in the form; the request should be linked to your last name. Ask them about the status, and if it’s possible to put a rush service for this request, and you should get your keys by the end of the day or early next day.
  4. They should create a case number for you; save this number. In case you have to call them again, you can reference this case number. You should also get emails from them with the case number, confirming all the stuff you said over the phone. These emails may be delayed 3 days after your phone call :) . The App Dev team actually handles code signing keys, and not Customer Service, which is why there’s some inefficiencies in going through Customer Service.

What to do when I get the keys via email?

When the keys are issued, you should get 3 emails from RIM. Each email will have an attachment, a .CSI file that you will need to proceed further. You still have a few more hoops to jump through before you can sign your BlackBerry apps with you keys.

Here’s a link to guide that will help you understand what to do with the keys. It’s good as a reference; I will now show you how to use the .CSI files and get everything set up. Before we begin, you must have the JDE installed and running (developerlife has you covered ;) ).

Step by step guide to registering the keys

Save the three .csi files (that are attached to the emails) to your JDE bin folder.

Run the SignatureTool.jar program on each one of the .csi files individually.

Let’s start with the RBB file

clip_image002

You get this prompt –

clip_image004

Select Yes, and create a new private key (if you want, you can make it the same as your PIN) –

clip_image006

clip_image008

Then type in both private key password and PIN –

clip_image010

When you click on Register, it will send information to RIM –

clip_image012

When the process is complete, you will get an email from RIM (websigner@mail.rim.net) telling you that this is complete.

On to the RCR file

Time to run SignatureTool.jar on the RCR file. You won’t have to setup the password for the private key this time, you just have to provide the PIN and private key password:

clip_image014

RRT file next

Time to run SignatureTool.jar on the RRT file. You won’t have to setup the password for the private key, you just have to provide the PIN anad private key password:

clip_image016

Using JDE to actually sign the .COD files –

Once you’re in the JDE and have built your project, you can then launch the signing tool by invoking Request Signatures from the Build menu.

clip_image018

Then you have to select the COD file and the type of SignerID and click on Request.

clip_image020

Then type in your private key password –

clip_image022

Then all the .COD files requiring signatures will be signed, and you will see this:

clip_image024

That’s it! At this point, your .COD file should be signed. Next step is loading it up on your device. I’m going to show you how to do this OTA (over the air), and not by simply generating an .ALX file and using Desktop Manager to load the app.

Depending on how many .COD files have to be signed, you will get that many emails from RIM telling you that the .COD files got signed. I get 40 emails every time I sign this test app I have :) . So keep a lookout for these emails from websigner@mail.rim.net when you sign your code.

What if you reinstall the JDE?

You have to preserve three files from your current JDE instance. These files are in the bin folder of you JDE install. In my case, they are all in C:\blackberry\ide\jde\bin, and they are:

  1. sigtool.csk
  2. sigtool.db
  3. sigtool.set

Even if you don’t reinstall the JDE, you might have multiple versions of the JDE on your machine, in which case, these instructions will come in handy.

Deploying a signed app OTA

You don’t have to setup mime associations for .JAD and .COD on the web server that will be hosting your .COD and .JAD files. You will need to copy the .COD and .JAD file to your web server. Before you copy the .COD file, there are some very strange things that you might have to do to it, to get it working. If you have a .COD file larger than 50K or so, then you will get an error when you try and install this .COD file on your BlackBerry device. The following instructions show you how to solve that problem.

.COD madness

You do have to extract the .COD file if it’s greater that 50KB. For some odd reason, large .COD files (which are ZIP files) are chunked into smaller files (<64K) in size. The strange part is that the .COD file chunks are named the same as the main .COD file. Here’s an example of a .COD file, which actually contains a bunch of other .COD files, of the same name as the main .COD file, which leads to confusion:

Note, how the HelloWorldProject.cod (640KB in size) contains a bunch of other .COD files, including “HelloWordProject.cod” (47K in size)! What? This is very confusing. So you have to extract the contents of this file, and then copy that to your web server. If you’re planning on extracting these files to the same folder as the original .COD file, you frist have to rename the main .COD file something else, and then extract it and put it on the web server. At that point, you should be able to install your app by using a URI to the .JAD file.

Comments and feedback

To share your thoughts on this tutorial click here.


Comments are closed.