How do you sign a Java Midlet?

Question

A simple question with a fairly complicated answer:

How do you sign a Java Midlet so you can load it onto a mobile phone with less security prompts?

Answer 1

Get required software

1. Java SDK (JDK) from Sun (you should already have this)
2. Java Wireless Toolkit (WTK) also from Sun
3. Optionally get and install Ant and Antenna to allow you to automate your build (I'd strongly recommend these)

Import an existing certificate (if you have one)

1. If you've purchased a certificate from Verisign (or another provider) you need to import the certificate into your J2SE keystore.
2. Try using the following command keytool -import -alias {myalias} -file {mycertificate} (I haven't been able to test this since I don't have a proper certificate)
3. Run keytool -list to see your new certificate
4. Next you must export the certificate so you can import it to your phone
5. Run keytool -export -alias {myalias} -file mycertificate.crt
6. Import the certificate into your phone (see below for details)

Create and import a new (test) certificate

1. You need to use keytool (from the JDK)
2. I used the following command keytool -genkey -alias {myalias} -keyalg RSA -validity 365
3. This will prompt you for a keystore password, enter your keystore password (if you have an existing keystore) or the one you want to use if you don't have one yet
4. Fill in all the prompts about location/company name etc.
5. Run keytool -list to see your new certificate
6. Next you must export the certificate so you can import it to your phone
7. Run keytool -export -alias {myalias} -file mycertificate.crt
8. Import the certificate into your phone (see below for details)

C:\j2sdk1.4.2_08\bin>keytool -genkey -alias company -keyalg RSA -validity 365
Enter keystore password: password
What is your first and last name? [Unknown]: My Name
What is the name of your organizational unit? [Unknown]: company
What is the name of your organization? [Unknown]: company
What is the name of your City or Locality? [Unknown]: location
What is the name of your State or Province? [Unknown]: location2
What is the two-letter country code for this unit? [Unknown]: GB
Is CN=My Name, OU=company, O=company, L=location, ST=location2, C=GB correct? [no]: yes
Enter key password for (RETURN if same as keystore password):

Build and package the application

1. Use javac to build your MIDlet paying special attention to your classpath and bootclasspath options (otherwise preverification will fail). I also set target to 1.1 and source to 1.3
2. Generate your JAD file the critical attributes in the JAD are MIDlet-Jar-URL, MIDlet-Jar-Size, MIDlet-Permissions we also included MIDlet-Icon, MicroEdition-Configuration, MicroEdition-Profile, MIDlet-Name, MIDlet-Push-1, MIDlet-Icon, MIDlet-Description and MIDlet-Version
3. Generate the MANIFEST.MF file based on your JAD, you must remove MIDlet-Jar-Size and MIDlet-Jar-URL
4. Both these tasks can be completed using the wtkJad Antenna task
5. Package and preverify the app using the wtkPackage Antenna Task you must set the classpath and bootclasspath properties correctly otherwise Preverification will fail

Sign the application

1. Sign the Application using jarsigner
2. Run jarsigner -keystore {mykeystore} -storepass (mypassword} {myjar} {myalias}
3. Now you have a signed jar you need to update the MIDlet-Jar-Size in your JAD
4. Now add the certificate to the JAD using JadTool.jar from the WTK
5. Run java -jar JadTool.jar -addcert -alias {myalias} -storepass {mypassword} -keystore {mykeystore} -inputjad {myinputjad} -outputjad {myoutputjad}
6. Now add the signature to the JAD again using JadTool.jar
7. Run java -jar JadTool.jar -addjarsig -alias {myalias} -jarfile {myjar} -storepass {mypassword} -keypass {mypassword} -keystore {mykeystore} -inputjad {myinputjad} -outputjad {myoutputjad}

Deployment

1. Deploy this to a web server with the MIME types set correctly and download it to your phone and it will be a trusted 3rd party application
2. You can also deploy applications to phones by sending the JAR & JAD to the phone over Bluetooth or Infrared or a cable depending on your phones features. On Nokia phones the files appear in your SMS Inbox

Installing the Certificate on the phone

1. Import the certificate into your phone, in Windows XP SP2 I could do this by right clicking the file and selecting "Send to Bluetooth Device", you should be able to send files by cable or Infra Red (IR) too. NB: I haven't found anyway of importing a certificate on a Series 40 phone
2. Once the certificate is installed it needs to be authorised for "Application Installation". On my phone (Nokia 6680) this is under Tools->Settings->Certificate Management->Trust Settings, I turned on everything but I think "Application Installation" is all you need

Common Problems

1. Application not installed using the JAD: The application is only trusted if it is installed using the JAD, the application will still install from the jar but it won't be trusted.
2. Application trust settings not set: Once your application is installed you need to specify how much trust to give it (it doesn't get all permissions by default). On a Nokia Series 60 phone these are found under the App. Manager.
3. Root certificate missing from phone: The Java Verified certificate and/or Verisign certificates are missing from some phones check under Tools->Settings->Certificate Management for the relevant certificate
4. Authorization Failed: - There are a whole host of possible reasons behind this here are the ones I've come across
   1. Certificate missing from phone, double check your certificate is installed and has been marked as trusted for application installs in Certificate Management
   2. Reboot: Uninstall the application completely then reboot your phone try taking the battery and SIM out too, often things get themselves in a twist, especially if you've been re-installing a lot without uninstalling first
   3. JAD/JAR mismatch: Double check the application size in the JAD, remember it's the number of bytes that is important NOT the size on disk
   4. Browser cache: If you're installing over the air make sure you clear your browser cache before installing
   5. I've heard but not verified that line breaks in the MIDlet-Permissions can cause problems but it seems ok to me on Nokia 6680/6630/6230i (could be firmware dependent?)
   6. The MIDlet-Permissions attribute is the cause of a lot of problems (especially since the documentation is often wrong/missing or different depending on the phone), try leaving it out first and add permissions in one at a time. Some phones will complain about permissions they don't support, some will ignore them
5. There is a bug in some early Nokia 6600 firmwares that stop the install of trusted MIDlets
6. Certificate not valid yet: If you generated the certificate yourself it may have a start validity date of tomorrow, also if your PC and phone dates are different you may be outside the period of validity of the certificate
7. No certificate management on Series 40 phones, you can install a signed application but behavior is strange with self signed certificates
8. JadTool problems: I haven't experienced any of these issues but lots of other people have
   1. "I have issues if I try to use the jadtool manually. I have a certificate chain and can't seem to get the second certificate added to the JAD file using any WTK jadtool. The interesting part however is that I can successfully sign the midlet using any of the same WTK GUI interfaces - they add the second certificate correctly. My steps:
      1. Use 1.4.2_06 jarsigner.exe to sign jar
      2. Use WTK (2.2 or 2.3 beta) jadtool to addcert with certnum 1
      3. If I call jadtool to addcert with certnum 2 the same certificate is inserted as cert 1-2 I'm assuming I am doing something incorrectly since the WTK gui seems to be working just fine"
   2. "I received a post on the KVM news group on the topic that states there is a bug in the jadtool and the author claims to have filed a bug report and posted a patch: http://archives.java.sun.com/cgi-bin/wa?A2=ind0508&L=kvm-interest&F=&S=&P=9858 One interesting note that was also posted was that the cert JAD params are static so once you get them from the WTK correctly you can put them statically in the ant script."
   3. "I am trying to sign a MIdlet for Nokia 6620 device. I am using a Verisign Code Signing certificate that actually contains two certificates (User and Intermediate CA). I am using the WTK 2.2 signing tool. Do you know if this tool support two certificates when signing ? The signature is added to the JAD file with two certificates but I have been getting security error when installing. I have checked on the device and there are different root certificates installed for Verisign but it still fails !
   4. "If you want, you can download the sprintpcs developer kit as it supports dual certs (http://developer.sprintpcs.com). However, I never got that cert to work on the Nokia (6620/cingular) phone, although it does work on sprint phones (with developer root enabled). Ultimately, I only got things to work by creating the cert as described in this blog and installing that on the phone. Bizarrely, even though the root cert for my versign-signed cert *was* on the 6620 phone, it still would never install my MIDlet as you would think it should."
9. Old phones (6230/i, 6682) don't support x509 certificates, WPKI has been suggested as a possible solution but I haven't investigated this
10. Socket connections can be problematic (http://discussion.forum.nokia.com/forum/showthread.php?t=68306 ) possibly due to the WAP infrastructure and the services provided by an operator. HTTP is a much safer protocol to use
11. "Go online and check application validity": Yes/No. If I click on yes button the phone I get the following error: "Certificate revoked for this application" and the installation fails. To rectify this go to Tools -> Manager -> Menu -> Settings -> Online Certif Check [ On / Off / Required] There is also a Default address setting. If the online control setting is required, the check will fail, if there is no default address. see http://discussion.forum.nokia.com/forum/showthread.php?t=71071

Trust Domains

1. There are 4 different trust domains in MIDP2 (manufacturer, operator, trusted third party, and untrusted). Trusted Third Party is the only one of any use to us really.It gives the following options on my Nokia 6680 (Vodafone UK):
Network Access: Not Allowed, Ask every time, Ask first time Messaging: Not Allowed, Ask every time App Auto-Start: Not Allowed, Ask every time, Ask first time Connectivity: Not Allowed, Ask every time, Ask first time, Always allowed Multimedia: Not Allowed, Ask every time, Ask first time Read User Data: Not Allowed, Ask every time, Ask first time, Always allowed Edit User Data: Not Allowed, Ask every time, Ask first time, Always allowed
2. These settings are defined by the operator and the phone manufacturer and therefore vary between phone, manufacturer and operator.

Unresolved Problems

1. I managed to sign the JAD with this format using J2ME WTK utilities, but when trying to install it on the device I get a message "Application authentication failed 909".

Sample JAD

MIDlet-Jar-URL: MyApp.jar
MIDlet-Jar-Size: 201365
MIDlet-Name: MyApp
MIDlet-Vendor: EC1M
MicroEdition-Profile: MIDP-2.0
MicroEdition-Configuration: CLDC-1.1
MIDlet-Icon: logo.png
MIDlet-Push-1: sms://:6553,net.ec1m.MyApp.midp.MyAppMIDlet,*
MIDlet-Description: MyApp MIDlet
MIDlet-Permissions: javax.microedition.io.PushRegistry,javax.microedition.io.Connector.sms...
MIDlet-Version: 1.0.67 MIDlet-1: MyApp, logo.png,net.ec1m.MyApp.midp.MyAppMIDlet
MIDlet-Certificate-1-1: MIICODCCAaECBEKqpfswDQYJKoZIhvcNAQEEBQAwYz...=
MIDlet-Jar-RSA-SHA1: EUsAch/.../hEZOsJsiCjBOhNs/3FSw4=

Sample Manifest

Manifest-Version: 1.0
MIDlet-Name: MyApp  
Created-By: 1.4.2_05-b04 (Sun Microsystems Inc.)
MIDlet-Push-1: sms://:6553,net.ec1m.MyApp.midp.MyAppMIDlet,*
MIDlet-1: MyApp, logo.png, net.ec1m.MyApp.midp.MyAppMIDlet
MicroEdition-Configuration: CLDC-1.1
Ant-Version: Apache Ant 1.6.2
MIDlet-Icon: logo.png
MIDlet-Vendor: EC1M
MIDlet-Permissions: javax.microedition...
MIDlet-Version: 1.0.67
MicroEdition-Profile: MIDP-2.0
MIDlet-Description: MyApp MIDlet

Sample Ant Build File I've put our EC1M ant build file up on our website to (hopefully) make all this a little easier for you. Other Resources This FAQ on the Nokia Forum is worth a read.