Signing a Jar

In order to access underlying hardware resources on a phone (File System, Text Messaging, GPRS) without receiving a prompt each time the resource is requested, many phones require that jar files be signed by a signing certificate. This is a guide to signing a JavaRosa powered application with a signing certificate.

Kinds of Certificates

There are four primary sources of Signing Certificates that are available 1. Verisign - Probably most common, but almost twice as expensive as thawte. 1. Thawte - Common on many devices. 1. Java Verified - Extremely expensive and a huge pain. 1. Self-Signed - Free, but rarely useful.

Thawte and Verisign

Thawte and Verisign are both trust identity service vendors. They provide a certificate signing authority that is present on phones that allows the phone to identify that the code provided has been signed with a valid certificate. Most phones have at least a thawte or verisign certificate, and many have both. It is extremely difficult to find a master list of which phones provide with Certificate Authorities, but individual phones often are able to provide a list of Certificate Authorities present on that phone.

Java Verified

Java Verified is a program by which Jars can be signed with a certificate that is present on nearly all modern mobile phones. However, the process of applying for a certificate is involved and expensive and isn't recommended for anyone.

Self-Signed

Some phones will allow for Certificate Authorities to be installed directly on the phone, allowing for the use of self-signed Jar files. This is not a commonly available technique, however, which is mostly available on older Nokia phones.

Creating a Keystore and Certificate Signing Request

Will need to create a keystore file to maintain your private key that will be used to generate your certificate request, and to load the certificate into once it is received.

To create and manage keystores this guide will use the Java keytool application. Information about this app can be found [http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/keytool.html here].

Using the keytool application, you will generate a local key and a certificate signing request that will be provided to verisign or thawte to create your key. Detailed instructions about how to do so can be found at [https://search.thawte.com/support/ssl-digital-certificates/index?page=content&id=SO3186 thawte's technical support documents].

'''''Once your keystore and csr are made it is vital that you back up the keystore file. If this file is lost your certificate will be unrecoverable and a new one will be necessary.'''''

Importing the Certificate

Once your certificate signing request has been created and sent off to the signing authority (Verisign or Thawte), a certificate file will be sent back. This certificate should be used to sign the key that you created in your keystore. The key can then be used to sign code which can be validated using the CA on the phone. Detailed instructions about using the certificate can be found at [https://search.thawte.com/support/ssl-digital-certificates/index?page=content&id=SO1079 thawte's technical support documents].

'''''This is another good time to back up your keystore.'''''

Signing the Jar

Once a keystore exists on the local machine which contains a certificate signed key, it can be used to sign your jar files. J2ME Polish makes this process very easy using the sign element inside the build target. Inside of the <build> block, the following element should be provided

				<sign
					keystore="${key.keystore}"
					key="${key.keyname}"
					password="${key.password}"
				/>

Each property value used for this process should be provided in a key.properties file that is present along side the build.properties file that is present in the project's root directory, and added to the build.xml file with the line

                    <property file="${basedir}/key.properties" />

that is already present in the demo project's build.xml file.

The key.properties file should stay separate, and should be added to the list of svn ignored files, so that your keystore's key name and password are not compromised by being added to svn. Additionally, this will allow different groups to use their own signing certificates.

Adding Permissions

Once code is being signed properly, phone permissions can be added to the JAD file to allow the application access to various pieces of the phone's hardware. These should go inside of the jad element in the build block. An example looks like

				<jad>
					<attribute name="MIDlet-Permissions" 
			 			   value="javax.microedition.io.Connector.file.read, javax.microedition.io.Connector.file.write, javax.microedition.io.Connector.http, javax.microedition.media.control.VideoControl.getSnapshot, javax.microedition.io.Connector.comm"
					           if="app.usefileconnections" />
				</jad>

A good list of relevant permissions can be found on sony ericsson's site [http://developer.sonyericsson.com/community/docs/DOC-1049 here].

In Practice

On some phones (Like Nokia's) getting permissions to work is essentially a three part process.

1. Sign the jar using these instructions (or other methods) 1. Ensure that the relevant MIDlet permissions are appended to access what is needed. 1. On the phone at runtime enable permissions to be set to allowed. On Nokias this is done by highlighting the application and going to Application Access and then finding the appropriate access and choosing the highest level of availability (Always Allow is Best).