How to Digitally Sign a J2ME Midlet

Introduction

We were recently asked to digitally sign a Java Mobile Midlet, only to find a significant lack of thorough official documentation on the process. This tutorial explains, from start to finish, in simple language, how to achieve this.

Introductory Notes

You may have already tried the official tutorial from Sun Microsystems, and found that it simply doesn't work. In case you are wondering, signing Java applications and signing J2ME applications is not the same process. You need to do some additional work with the JAD before you can use the app on the phone.

Prerequisites

• Sun Java Wireless Toolkit 2.5.2 or higher
• The latest Java Development Kit (JDK)

Step-by-step Instructions

1. Open a command prompt as administrator

To do this in Windows Vista, go to the Start menu, type cmd, the first result should be "cmd.exe". Right click on this and click "Run As Administrator".

2. Navigate to keytool

You need to switch your working folder to that of the JDK bin folder, where the keytool is located. To do this, first identify where the keytool is. It's probably here: "C:\Program Files\Java\jdk1.6.0_18\bin", but may vary depending on where you installed it and your processor architecture.

To switch folder:

cd "C:\Program Files (x86)\Java\jdk1.6.0_18\bin"

3. Create a keystore

You must create a keystore that contains your company's trading information. This information is used by your certificate authority (such as VeriSign or Thawte) to verify your company. Enter the following command:

keytool -genkey -keyalg rsa -keystore <keystore_filename> -alias <alias_name>

Substitute <keystore_filename> with "truststore2.jks" (no quotes) and <alias_name> with the name of your application. Be sure to exclude spaces and uppercase characters. For example, "Hello World" should become "helloworld". Enter your password for the keystore. If this is the first time you have used this keystore, you will be asked to re-enter the password. Make a note somewhere of this as you need to use it regularly.

You will be asked to enter some information about your company. Fill out the information as accurately as possible, pressing Enter after each field. When all the fields are complete, you must confirm the information. Once done, type "yes" and then press Enter. Enter a password for the alias, then re-enter it. Make sure you keep a note of this password somewhere as you will be using it regularly. This password can be the same as your keystore password.

4. Create a Certificate Signing Request (CSR)

A CSR is basically an encrypted version of all the data you have just entered, in the form of a digital signature. You must send the signature to your Certificate Authority (CA) for processing. To create the CSR:

keytool -certreq -file "C:\Users\Jon\Desktop\certreq.csr" 
    -keystore <keystore_filename> -alias <alias_name>

Substitute the file path ("C:\Users\Jon\Desktop\") with the path to your desktop, recommended for convenience. Substitute <keystore_filename> with the filename you specified earlier (truststore2.jks), and substitute <alias_name> for the name you specified earlier (testapp).

Enter the password for the keystore. You will notice that the CSR has been outputted to your desktop with the file name you stipulated earlier.

5. Submit CSR to the Certificate Authority (CA)

Now that you have created your CSR, you need to send it to your CA. If you have not already started the enrolment process with a CA (such as VeriSign or Thawte), you should do this now. You will eventually come to a field on the registration form that says "Enter CSR:".

To enter the CSR, open the "cert.csr" file in a simple text editor, such as Notepad, by right clicking and selecting "Open With...".

Copy the CSR into the web form, and continue with the registration process.

6. Import certificate to Trust Store

Once your CA has verified your identity, they will reply with a Sun Java Code Signing Digital ID, which basically looks like a really long version of the CSR that you sent them originally in the previous step of this tutorial. Before you can use your Digital ID, you need to do a little work. Create a new file called "cert.p7b" on your desktop and copy and paste the response from your CA into it.

Be sure to include in the "BEGIN CERTIFICATE" and "END CERTIFICATE" starting and ending declarations. These are part of the certificate. Note also that there should be 5 dashes (-) on either side of the text.

To import the certificate to your trust store, issue the following command:

keytool -import -trustcacerts -keystore <keystore_filename> -alias <alias_name> 
    -file "C:\Users\Jon\Desktop\cert.p7b"

Once again, substitute the <> fields with the same values that you indicated earlier in this tutorial.

7. Add certificate to JAD

Your Java Midlet consists of two files: a JAR file and a JAD file. The JAD file is a descriptor file that specifies information about your JAR file. The JAD file is the file that has to be signed with the certificate, not the JAR file (this is why so many people go wrong!).

Before we do this, you need to change your working directory to where the file "JADTool.jar" is located. This file is part of the Java Wireless Toolkit (WTK), and its location may very depending on where you installed it. The file is probably here: "C:\WTK2.5.2_01\bin". To change the working directory, issue the following command:

cd "C:\WTK2.5.2_01\bin"

To add the certificate to the JAD, issue this command:

Java -jar JadTool.jar -addcert -keystore <keystorename> -alias <aliasname> 
    -storepass <password> -inputjad <input_jadfile> 
    -outputjad <output_jadfile>

There is a lot going on here. We need to review each field value carefully:

• <keystorename> - Remember that the keystore is actually located in a different working directory, so you need to specify its full path: "C:\Program Files (x86)\Java\jdk1.6.0_18\bin\truststore2.jks" (Windows Search is your friend here).
• <aliasname> - The alias you stipulated earlier (testapp).
• <password> - The password to your trust store.
• <input_jadfile> - The location of your JAD ("C:\Users\Jon\Desktop\MyApp.jad").
• <output_jadfile> - Tells the tool where to output the new JAD file, gives it a name slightly different to the name you are using now ("C:\Users\Jon\Desktop\MyApp 0.jad").

You should eventually end up with something that looks like this:

Java -jar JadTool.jar -addcert -keystore "C:\Program Files 
    (x86)\Java\jdk1.6.0_18\bin\truststore2.jks" -alias testapp 
    -storepass password -inputjad "C:\Users\Jon\Desktop\MyApp.jad" 
    -outputjad "C:\Users\Jon\Desktop\MyApp 0.jad"

8. Add Signature to JAD

Now that you have added the certificate to the JAD, you must add the signature to the JAD. The command is similar to the one we just issued:

java -jar jadtool.jar -addjarsig -jarfile <jar_file> -keystore <keystorename> 
    -alias <aliasname> -storepass <password> -keypass <password> 
    -inputjad <input_jadfile> -outputjad <output_jadfile>

The main difference is the change of the "-addcert" command to he "-addjarsign" command. Be sure when specifying the <input_jadfile> parameter that you point to the JAD file you just created ("C:\Users\Jon\Desktop\MyApp 0.jad") rather than the original. Give the <output_jadfile> parameter a new name, such as "C:\Users\Jon\Desktop\MyApp 1.jad".

9. Verify that JAD is signed

You can verify that the JAD file was correctly signed by issuing the following command:

java -jar jadtool.jar -showcert -all -inputjad <input_jadfile>

10. Testing and Distribution

Now that your application is signed, delete "MyApp.jad" and "MyApp 0.jad". Now rename "MyApp 1.jad" to "My App.jad".

Transfer both the JAD and JAR file to your mobile phone or other testing device. View the application's details to show that the application has been signed with your company's information. This varies from device to device, but should say something along the lines of "Certificate: Yes".

Thanks for reading!

This article was originally posted at http://www.jpreece.com/csharp-tutorials/how-to-digitally-sign-a-j2me-midlet/.