# Signing MIDlet suites

MTJ supports cryptographic signing of MIDlet suites. This page provides background material on the signing process and provides an overview of how you go about signing a MIDlet Suite using MTJ.

1. Background
2. Basic steps
3. Signing using MTJ

## Background

Under the MIDP 1.0 specification, all MIDlets operated using a "sandbox" security model. Essentially, a MIDlet could only access API's that were specifically included as part of the MIDP 1.0 specification, or to libraries that were bundled as part of the same MIDlet suite.

MIDP 2.0 (JSR-118) introduced the concept of "trusted" and "untrusted" MIDlet suites. An "untrusted" suite operates under the same restrictions as in MIDP 1.0 - the only API's that can be accessed are those that are part of the MIDP specification. "Trusted" suites can be granted access to a wider selection of API's on the device. In addition, as part of the MIDP 2.0 specification, certain "standard" API's were provided that required authorization to use. For example, an untrusted MIDlet suite must be able to access the javax.microedition.io.HttpConnection API, but the system is required to make the user confirm that it is OK for the MIDlet suite to use this API.

Trusted MIDlet suites can, on the other hand, be granted access to API's without explicit user authorization, and may have access to API's that an untrusted MIDlet is not allowed to access. Details of all of this are spelled out in JSR-118, and so will not be repeated here.

## Basic Steps in Signing a MIDlet Suite

The basic steps in signing a MIDlet suite are:

1. Include the list of permissions your MIDlet suite is requesting in the JAD file and manifest
2. Obtain an appropriate cryptographic key/certificate pair to do the signing
3. Sign the MIDlet suite as the final step in deploying it

### Including the list of permissions your MIDlet suite is requesting in the JAD file and manifest

A MIDlet requests permissions by declaring them in the application descriptor and JAR manifest, using either MIDlet-Permissions or MIDlet-Permissions-Opt tag. Multiple permissions can be specified with either tag, and are separated by commas. During the installation process, the device is required to look at the requested permissions. If a permission is declared in MIDlet-Permissions, then the device must either be prepared to install the MIDlet in a protection domain that grants access to these features, or the device must abort the installation. However, if the permission is declared in MIDlet-Permissions-Opt, and the MIDlet suite fails to gain access to an appropriate protection domain, the installation can continue but the suite will not have access to the requested permission. So, if your MIDlet suite depends on having a permission, and cannot operate without it, this permission should be requested in MIDlet-Permissions.

If your application can live without a specific permission, but would make use of the feature if access is granted, request the permission using MIDlet-Permissions-Opt. If your MIDlet is not granted permission to the feature, you should get a SecurityException when you try to access it. Note that for HTTP in particular, certain device providers violate the specification just slightly and throw an IOException, instead of a SecurityException, in an odd attempt to be compatible with MIDP 1.0. Check your toolkit provider's documentation on this.

The following is an example of requested permissions in a JAD file. The MIDlet suite is indicating it must have access to HTTP and HTTPS and would like to have access to the PushRegistry, VideoControl.getSnapshot, and SMS. If the latter three are denied, the suite can adjust and still provide value to the user.

    MIDlet-Permissions: javax.microedition.io.Connector.http, javax.microedition.io.Connector.https
    MIDlet-Permissions-Opt: javax.microedition.io.PushRegistry, javax.microedition.media.control.VideoControl.getSnapshot, javax.wireless.messaging.sms.receive, javax.wireless.messaging.sms.send

In this example, HTTP and HTTPS are not requested as optional. Because the application has indicated it cannot function without these resources, if the device is unable to grant these permissions on installation, the installation will abort. Whether or not the device will be able to grant permission is dependent on its own security policies, and whether or not the MIDlet is trusted. In order to be trusted, the MIDlet must be signed.

### MTJ provides a signing page on the JAD Editor in order to manage the suite permissions.

The signing page allows developers to:

- Add/Remove Permissions
- Order the permissions in the JAD
- Scan the project's code for permissions

### Obtaining an appropriate cryptographic key/certificate pair to do the signing

MIDlet security is based around public key cryptography. The basic steps are:

1. You create a public key/private key pair.
2. You use the private key to digitally "sign" the MIDlet suite.
3. You then include the public key as part of the MIDlet suite so that anybody else can validate the signed information.

Since only your private key can generate information that your public key can decrypt, so as long as you keep your private key a secret, the world can be sure that anything that can be verified by your public key was prepared by you.

Of course, this still begs the question of how someone knows that a particular public key really came from you. What is to prevent me from claiming to be Bill Gates, and digitally signing documents accordingly? Instead of just including your public key in the MIDlet suite, you include a certificate that, in turn, includes the public key. The certificate is issued by a trusted third party such as Verisign, and essentially promises that this public key really did come from you.

How does the device know to trust the Verisign certificate? Devices are programmed with a set of "root certificate authorities" that they will always trust. Certificates are themselves signed, using information that is pre-programmed into the phones. Thus, the device can verify that your certificate was actually issued by Verisign by using its pre-programmed information. Alternately, your certificate may be signed by an "intermediate" key, which is itself, in turn, signed by a trusted key. This is called a "certificate chain." Chains can actually be any number of keys in length, although it's rare that they contain more than two or three links.

As a result, the process for getting your keys set up typically works like this:

- You generate a public/private key pair using a convenient tool.
- You generate a "certificate request" that contains your public key, and send it to a certificate authority.
- The certificate authority does a little checking to make sure that you are who you say you are. What kind of checking is done varies from authority to authority.
- Once the certificate authority is satisfied that you are who you say you are (and you pay them their fee) the certificate authority wraps your public key in a certificate, and sends it back to you.
- You import the certificate back into your keystore so that you will have it when you need to sign something.

### Sign Using MTJ

In order to sign the suite using MTJ the developer will need to setup the signing settings in one of two ways:

1. Workspace Preferences signing page for default project signing settings
2. Project Properties signing page for specific project signing settings

### 1. Signing Preferences Page

On this page the user can select a keystore file to be used as the default keystore. By pressing the External... button the user will select the default keystore.

After selecting the file the user will be prompted for the keystore password in order to list all private key aliases:

NOTE: The default settings for keystore's Provider and Type are:

Option | Value
--- | ---
Provider | SUN
Type | JKS

In case your keystore has either a different Provider or Type they must be set in the Advanced Settings section before opening the external file:

The keystore password prompt allows the user to save the keystore password in the workspace keyring in order to avoid having to enter the password when needed.
Once the correct password is entered the list of available aliases will be listed as bellow:

### 2. Project Properties Page

In case a project needs signing specific settings other than the default set in the workspace preferences, the developer can setup project specific signing settings by opening the signing page on the project properties:

The only difference between the project and the preferences signing pages are the password management as show bellow:

Both keystore and key passwords can be managed in one of the following forms:

- Prompt for password when required
- Save password in workspace keyring
- Save password as part of project

Once all signing configuration is set, open the signing page under the JAD Editor. Make sure the sign generated packages button is selected in order to sign your application.

On the alias section there should be listed all available aliases from the configured keystore, select one of the available aliases and MTJ will sign your application with it.

### NOTE: MTJ only signs the package generated under the deployed folder, it does not sign any intermediate package since it is a time consuming task for incremental builds.