HOWTO Build, Sign and Install MIDlets

http://browndrf.blogspot.com/2006/06/build-and-install-singed-midlet.html

 

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!

Disclaimer

The process described here is not guaranteed to work on all handset models.

 

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 required

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.

(You might require to configure openSSL such as creating a folder called c:\usr\bin under windows and copy the openssl.conf file into that folder)

 

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 company 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

[code]
$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);

[/code] 

 

 

Sample JSP back-end java code will look like this

 

[code]

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();

[/code]

 

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.

 

 

Step6: 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.

 

 

Step7: 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.

 

 

 

Step8: Create certificate 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.

• Open Internet Explorer
• Open certificate manager (Tools->Internet Options->Content->Certificates)
• Pick “Trusted Root Certification Authorities” tab and Click “Import”
• Click “Next” and choose path to your ca.crt file and click “Next”
• Pick certificate store as “Trusted Root Certification Authorities” and continue until it says imported.
• 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.
• In “Intermediate Certification Authorities” select your code-sign certificate and click “Export”
• 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)
• Continue by clicking next and pick a file name (say code-sign)
• 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 9, 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.

 

Step9: MIDlet signing

• Hope you still have carbide.j tool window open from step6.
• Go to “Sign MIDlet package” view and click “Import Certifiacte”
• On prompt pick the P7b file created in step8.
• On success it won’t say anything, but you’ll see the information getting added.
• Finally – the big click – Click “Sign”

 

It will prompt for the .jad file – pick the jad file you created on step2 (MyMIDlet.jar, jad)

 

Click OK and it should say successfully signed.

 

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

 

 

Step10: Verify your jad file

Step9 must have modified your jad file by adding the certificate information into it. So 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, believe it or not, you have a signed MIDlet ready to install !!

 

 

Step11: 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.

 

 

 

Step12: Relax

 

Good luck :)