Introduction

A Client Package is an installer that is specifically designed to fit in for a given target handset.

For a Java device one will obtain a .jar and a .jad files.

Client package creation is a 3-step process:

• Configuration
• Packaging
• Signing

Prerequisites

Application configuration can be accessed from the Service > Service Settings > Application configuration tab in Workbench Developer.

In order to customize an application one will need to specify:

• Standard settings, i.e. application name, application version, application icon (see requirements below)...
• (optional) Advanced settings, i.e. SMS Listener activation and any other .jad parameters
• (optional) Signature (see procedure below), i.e. all parameters (key, password...) to get the application signed

Icon

The PNG format is the preferred and widely used file format for a MIDlet icon. The number of colors used should be kept at a minimum, preferably at the 8-bit depth of 256 colors max. One should also avoid anti-aliased icons because some devices don't support them and will display the anti-aliased icon with "dirty" edges or with random pixels around the edges that are supposed to be semi-transparent.
There is no minimum size specified, and it is up to the platform to resize the icon. As such, if one wants a perfect looking icon for a MIDlet, the only way to do it is to know the size that the phone supports. Most Java handsets accept 16x16, 32x32 icon sizes.

Signing

Signing an application is a necessary step for commercial distribution, and eventually for testing purpose.

On Java devices, the signing procedure requires a certificate signed by a certificate authority (500 USD) and may be optional depending on the device capabilities used in the developed application.

Applying the signing procedure will especially enable to get rid of popup notifications the end-user shall definitely not meet.

Useful reference: Sony Ericsson Java™ ME Signing Guidelines.

One will need the JadTool program in order to sign the applications. One will need to download the Sun Wireless ToolKit (or the Sun Java ME SDK).

Public/Private key pair generation

The first step consists in generating a pair of public/private cryptographic keys. If not already done, one will have to download the Java 2 Software Development Kit (SDK) from http://java.sun.com/javase/downloads/index.jsp.
With the JDK comes the keytool utility program. This tool allows creating a keystore (a collection of keys and certificate). The keytool program is located in the bin/ directory of the JDK. Ensure that the tool is on the system classpath and execute this command:

Keytool will ask to provide information on one's identity and company. Keep the generated keystore file (e.g. mycompany.ks) safe and private.

Certificate Signing Request (CSR) Creation

To generate a Certificate Signing Request (CSR), execute the following command:

The created .csr file will be uploaded to the Certificate Authority (CA).

Certificate Authority (CA)

A CA's obligation is to verify an applicant's credentials.

For a Versigin certification one will have to do this:

• Go to the Verisign website.
• Go to the Code Signing Sun Java section [link].
• Click on "buy" and follow the instructions. One will be asked to enter various information about himself and his company. One will need to send the Certificate Siging request. The price is 499 USD for 1 year.

The request will then go through designated verification and security processes. If the application is complete, one's Digital ID should be issued in 3 to 5 business days. The certificate will be attached to the mail in the rfc 1421 format:

-----BEGIN CERTIFICATE-----
and at the end by

-----END CERTIFICATE-----

Copy this content (including the --- XXX CERTIFICATE ---) into a .cer file (e.g. certificate.cer). Now one must import the signed certificate into the keystore. The signed certificate will then replace the self signed certificate of the private key.

Packaging

Wizard

Application packaging can be accessed from the Service > Create Client Packages menu option in Workbench Developer.

In order to package an application one will need to specify:

• Targeted device(s), i.e. select all devices the application is supposed to support
• Application configurations, i.e. all defined configurations (as defined in the Prequisites section above) can be set / updated here
• Rich Media Server information, i.e. required parameters to access Streamezzo Rich Media Server instance if any (i.e. if the application contains server-side scenes)
• Output, i.e. output folder and pattern (this last parameter is mandatory in case multiple devices are selected for packaging, as each application installer will need to be dumped in a separated and identified folder, inside the output folder)

Once the "Finish" button is pressed, all requested client packages will be generated for each selected device.

If specified in the configuration, the application will be automatically signed.

The progression of the client packages creation can be followed in the Client packages creation view.

Once a client package has been created, its output folder can also be accessed from here.

Ant task

Some operations as accomplished above with the wizard can be performed relying on an Ant task, which is usually comfortable to reiterate a client package creation in a given configuration (i.e. selected devices, configuration, output...) in a 1-click operation.

In order to do this one can follow those steps:

• Create an Ant build file
• Open it in the Workbench Developer editor
• Right-click in the editor area and select Wizards > Create client package target
• Follow the same wizard steps as detailed above; once the "Finish" button is pressed, the Ant build file will be automatically filled accordingly (instead of really creating the client package(s))

The obtained Ant task looks like this:

<?xml version="1.0" encoding="UTF-8"?> My description

The Ant build file can then be dumped in the Ant view and executed from here.

The progression of the running Ant task can be followed as successive logs in the Console, ending with message "BUILD SUCCESSFUL" in case it succeeded.

In addition to this one may need to add the signing procedure, which can also be operated relying on Ant.

• Step 1: Add the certificate to the jad file. This will add a MIDlet-Certificate-1-1 directive to the application jad file. This refers to the certificate. Note: If one is using a certificate chain (which is not the case here), one must add all the certificates present in the chain (except the root one). 
• Step 2: Add the jar signature to the jad. The JadTool utility signs the JAR file, base64 encodes the signature and stores it as the value of the MIDlet-Jar-RSA-SHA1 attribute of the output JAD file.

Such Ant script looks like this:

Distribution

Once properly packaged and signed, a Java application can be distributed OTA by any applicable mean, i.e. FTP, Provisioning Server...

The application shall be installed via the .jad file in order to have all specified jad parameters taken into account and for the singature to be checked.