How To Build, Sign and Install Java MIDlets

 always have trouble building a signed MIDlet and installing it on a handset. No matter whether you buy a code signing certificate or not, it is hard to get it working at the first shot. I wrote this article after a prolonged trials and errors. I hope this would help some readers. 

Build and install Singed MIDlet

I’m aware that this is a lengthy process and involves several delicate steps. I wish I knew an easier method!! I have only tested this with one handset (nokia 6682). If you have a different handset things can be slightly different. However the basic signed MIDlet security model should be the same. The main problem with several (at least mine) handsets is, they do not allow you to directly install new CA root certificates. The security model is great, but this enforces us to buy a code-signing certificate even just for testing purpose. After reading several articles and email discussions I managed to install a self-signed certificate to my handset. I could also successfully install my test MIDlet signed by that self-signed certificate. My contribution to this process is very little. I just collected bits and pieces from different places and put them together. I hope this might help some developers. If you have any questions or comments you may email me to brown_drf [at] yahoo [dot] com. Good luck!

Pre-requisites

I assume the reader knows how to setup a simple website, simple web page programming to upload a file, basic knowledge on how certificates work etc. The processdescribed here also require reasonable understanding of your handset's configuration. I’m also not focusing on how to download tools and how to set them up.

Tools used 

• Sun Wireless Toolkit 2.3 (WTK)
• carbide j - 1.0 (just to sign the midlet - I haven't tried other tools)
• OpenSSL - to create and sign certificates
  

Goal
To to build, sign and install a MIDlet that can access a restricted j2me classes (like network access). In my experiments I was tring to develop a client MIDlet capable of opening a Bluetooth connection to a PC.

Step 1: Build and (try to) test your MIDlet on Emulator 
I started with a sample code came with Sun's WTK. Build your code using KToolbar. Try to run your MIDlet on an emulator. In my case it wasn't working! “for some reason” the emulator was not was not detecting my a bluetooth hardware - anyway. Since I was developing a BT client, I first tested it with standard sockets, just to check whether my handset UI works at least.

Tool used: KToolbar (Sun WTK)

Step 2: Set permissions and Create MIDlet package
Once you think your MIDlet is good to go, you should build a package for installation. As you might already know, depending on the classes/packages you are using, you might need to setup MIDlet permissions. You can do that with KToolbar itself. Click "Settings" and pick "Permissions" tab. Click on "Add" to pick the packages/class you are interested in. I had to add only one (javax.microedition.io.Connector.bluetooth.client) because my MIDLet was a simple BT client. Most other fields are automatically filled, but it worth eyeballing around and making sure nothing is obviously wrong. Now you may create the MIDlet package by selecting Menu->Project->Packages->CreatePackage. This will create a MyMIDlet.jar file and a MyMIDlet.jad file under your sample app's bin/ folder. Open the .jad file in a text editor and take a quick visual examination

Make sure :

• You don't see anything unusual - obviously :)
• The permission(s) you added are present - very important
• No certificate information present - If present, delete them (we will add them later)

Alrite.. , you just created an "unsigned" MIDlet !!

Step 3: Create a self-signed issuer CA
The idea is to create fake CA certificate that can be used to issue a code-signing certificate.
Note: Do these under a clean folder so that you won’t lose these files
At the command prompt, run following OpenSSL commands to create an issuer CA 

• openssl genrsa -des3 -out ca.key 4096
• openssl req -new -x509 -days 365 -key ca.key -outform DER -out ca.cer
• openssl req -new -x509 -days 365 -key ca.key -out ca.crt
  

This will ask a few questions (like comapy name, OU etc). Enter some valid inputs.
Now you have generated 3 files

• ca.key is your fake self-signed CA private key
• ca.crt your CA’s public key (certificate) in PEM format
• ca.cer your CA’s public key (certificate) in DER format
  

Note: Make sure you save these files.

Now, test the certificate's validity by installing it on your desktop. If you are on windows, just double click it and windows will say if the cert is invalid.

For further reading on certificate creations go to :
http://www.tc.umn.edu/~brams006/selfsign.html

Step 4: Install the newly created CA certificate on your handset
This is tricky. I did it with the help of a small webserver I had. What you need to do is to create a web page from which a browser can download your ca.cer file. The page can be can be developed in any language. In my case I had a tomcat server serving a jsp page. But I recommend apahe/php, because its easy to setup. The important thing is setting the MIME content type to "application/x-x509-ca-cert". 
Sample php back-end script will look like this

$file = path_to_your_CA_CER_FILE
header('Content-Description: File Transfer');
header('Content-Type: application/x-x509-ca-cert');
header('Content-Length: ' . filesize($file));
$bn = basename($file);
header("Content-Disposition: attachement;filename=$bn");
readfile($file); 

Sample JSP back-end java code will look like this 
File exportFile = new File(path_to_your_CA_CER_FILE);
response.setContentType("application/x-x509-ca-cert");
response.addHeader("Content-Disposition", "attachment; filename=" + exportFile.getName());
OutputStream os = response.getOutputStream();
InputStream is = new FileInputStream(fileName);
while (is.available() > 0) {
char c = (char) is.read();
os.write(c);
}
os.flush();
is.close(); 
Important! You can install certificates ONLY in DER format so make sure path_to_your_CA_CER_FILE points to ca.cer. 

Now, load the cer file to the location specified in the script above and start the webserver.
Using your handset's browser, browse (Over The Air) to the new page and try to download the cer file. The handset should ask whether you want to download and install the certificate. Say yes and the handset should download the certificate and install it as a trusted CA. If there is a problem installing the certificate, make sure the certificate is valid as mentioned in step3.

Step5: Configure the installed certificate on the handset
Open-up certificate manager on your handset and adjust the trust status. I set it like this

• Symbian Installation: No
• Internet: Yes
• App. Installation: Yes
• Online Cert. Check: No
  

If you have got this far successfully- 50% of your job is done !! You don't have to do this CA cert installation ever again !!
Note: changing certificate trust status can be different on different handset models.

Step5: Generate a Certificate Signing Request (CSR) 
To create a code-signing certificate all CA's require a Certificate Signing Request (CSR). I used carbide.j tool to create CSR. It is simple - Run carbide.j standalone. Select "Create Application Package" view. In "General" tab choose "recreate based on existing package" option. Pick path to your JAD and JAR files. Now change to "Sign Application Package" view. If you have something in "available alias" area, you may delete at the first time. Click "New keypair" and enter your (your comapny's) information and click "Create".

Important: Do NOT use two letter state code. (example Use California instead of just CA)

Now you should have a new entry in the alias box. Click on "Generate CSR". It will prompt to enter a file name (say code-sign.csr). Enter a valid file name in a known location and click OK. Now you have a Certificate Signing Request (CSR) that you can submit to a CA.!

Keep this tool running. We need it later.

File created : server.csr
Note: Save this file for future, you can use this later when you decide to buy a real CA cert. 

Step6: Create a code signing certificate 
This is the money saving step. You are about to create a code-signing certificate for yourself, that you would buy from a CA otherwise. In Step3 we created a CA and in Step4 we installed that certificate on our handset. In Step5 we created a CSR. Now create a code signing certificate for the CSR you created using the CA we created.

Run this OpenSSL command under (make sure all key/crt/csr files are accessible.

• openssl x509 -req -days 365 -in code-sign.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out code-sign.crt
  

File created: code-sign.crt

info: What you have (code-sign.crt) is a PEM format certificate issued by the CA you created in Step3. ca.crt is the root certificate and code-sign.crt is the leaf certificate. Note that leaf certificate is NOT valid unless you have the root certificate. In next step we will create a file containing both root and leaf certificate. This will be in PKCS#7 format.

Step7: Create certificates package 
The idea is to combine ca.crt and code-sign.crt and create a .P7c file. I used Windows’s certificate manager to do it.

1. Open Internet Explorer
2. Open certificate manager (Tools->Internet Options->Content->Certificates)
3. Pick “Trusted Root Certification Authorities” tab and Click “Import”
4. Click “Next” and choose path to your ca.crt file and click “Next”
5. Pick certificate store as “Trusted Root Certification Authorities” and continue until it says imported.
6. Now pick “Intermediate Certification Authorities” tab import code-sign.crt like you did for ca.crt. Once successfully imported, you’ll see the code-sign certificate among intermediate certificates.
7. In “Intermediate Certification Authorities” select your code-sign certificate and click “Export”
8. Succeeding screen will prompt you to choose the format. Pick PKCS#7 (.P7B). and check “include all certificates in the certification path if possible” checkbox (very important)
9. Continue by clicking next and pick a file name (say code-sign)
10. Continue till it says successfully exported and you should see a file by name code-sign.p7b has been created.
    

Important: Pay special attention to step 8, If you do not check "include all certificates..." you will not be able to sign your MIDlet.

Save this file (code-sign.p7b) as well. 
Note: You may also use other browsers or OpenSSL command line tool to achieve this.

Step8: MIDlet signing
Hope you still have carbide.j tool window open from step5.

1. Go to “Sign MIDlet package” view and click “Import Certifiacte”
2. On prompt pick the P7b file created in step7.
3. On success it won’t say anything, but you’ll see the information getting added.
4. Finally – the big click – Click “Sign”
5. It will prompt for the .jad file – pick the jad file you created on step2 (MyMIDlet.jar, jad)
6. Click OK and it should say successfully signed.
   

If you are gotten this far, you’re 99% done !!

Step9: Verify your jad file
 
Step8 must have modified your jad file by adding the certificate information into it.
Now you should see lines like these in your jad file

MIDlet-Certificate-1-1: MIID8DCC….
MIDlet-Certificate-1-2: MIIGdzC…..
MIDlet-Jar-RSA-SHA1: SFvS0W…

Also make sure MIDlet-Jar-Size: field value matches with the actual size of your jar file.

Well, you have a signed MIDlet ready to install !!
Step10: Install the MIDlet on your handset 
This is what you were waiting for. Cross your fingers :)
I did this – again – with the help of my little website. I tried Nokia’s PC suite, but it did not work. I wish I knew an easier way to do this. This is what you should do if you follow what I did.

Created a simple html file like this 

[html]
[head]
[title]MySignedMIDlet[/title]
[/head]
[body]
[a href=http://mywebsite/my_midlet_folder/mymidlet.jad] mymidlet.jad [/a]
[/body]
[/html]

Note: apparently, replace all square brackets with angle brackets

• Save this HTML to -say- "mymidlet_installer.html" and mait it available to web.
• Copy the MyMIDLet.jar and MyMIDLet.jad files to a web folder as shown in the html script.
• Using your handset’s browser browse to http://mywebsite/my_midlet_folder/mymidlet_installer.html
• Browser will show the link and click on it.
• Handset should prompt whether you want to install the application.
• Click "yes" and - BOOM!! you installed your MIDlet.

Step11: Relax
Good luck :)