12 Security and MIDlet Signing

MIDP 2.1 (JSR 118) includes a comprehensive security model based on protection domains. MIDlet suites are installed into a protection domain that determines access to protected functions. The MIDP 2.1 specification also includes a recommended practice for using public key cryptography to verify and authenticate MIDlet suites.

The general process to create a cryptographically signed MIDlet suite is as follows:

The MIDlet author, probably a software company, buys a signing key pair from a certificate authority (the CA).
The author signs the MIDlet suite with the signing key pair and distributes their certificate with the MIDlet suite.
When the MIDlet suite is installed on the emulator or on a device, the implementation verifies the author's certificate using its own copy of the CA's root certificate. Then it uses the author's certificate to verify the signature on the MIDlet suite.
After verification, the device or emulator installs the MIDlet suite into the security domain that is associated with the CA's root certificate.

For definitive information, consult the MIDP 2.1 specification at:

http://download.oracle.com/otndocs/jcp/midp-2.1-mrel-oth-JSpec

See the following topics:

"Security Domains"
"Setting Security Domains"
"Signing a Project"
"Managing Keystores and Key Pairs"
"Managing Root Certificates"

12.1 Security Domains

The SDK supports the following security domains:

minimum. All permissions are denied to MIDlets in this domain.

maximum. All permissions are granted to MIDlets in this domain. Maximum is the default setting.

unidentified_third_party. Provides a high level of security for applications whose origins and authenticity cannot be determined. The user is prompted frequently when the application attempts a sensitive operation.

identified_third_party. Intended for MIDlets whose origins were determined using cryptographic certificates. Permissions are not granted automatically, but the user is prompted less often than for the unidentified_third_party domain.

operator. All permissions are denied to MIDlets in this domain.

manufacturer. Intended for MIDlet suites whose credentials originate from the manufacturer's root certificate.

12.2 Setting Security Domains

In the SDK, when you use Run Project via OTA, your packaged MIDlet suite is installed directly into the emulator where it is placed in a security domain. The emulator uses public key cryptography to determine the appropriate security domain.

If the MIDlet or MIDlet suite is not signed, it is placed in the default security domain.
If the MIDlet or MIDlet suite is signed, it is placed in the protection domain that is associated with the root certificate of the signing key's certificate chain. See "Signing a Project."

If your project is a MIDlet suite, the entire suite is signed (the individual MIDlets contained within are not).

12.2.1 Specify the Security Domain for an Emulator

In the Device Selection window, right-click on the device and select Properties.
Find the Security Domain setting and make a selection from the context menu.

The SDK knows the runtimes the device can support and supplies only possible domains. The default setting for the sample projects is Maximum.

12.2.2 Specify the Security Domain for a Project

Right-click a project and select Properties.
In the Category area, select Running (the green triangle).
Select Regular Execution and check the Security Domain box.

In this context regular execution means you are running in the emulator, as opposed to running OTA.
Select the domain from the drop-down menu.

12.3 Signing a Project

Devices use signing information to check an application's source and validity before allowing it to access protected APIs. For test purposes, you can create a signing key pair to sign an application. The keys are as follows:

A private key that is used to create a digital signature, or certificate.
A public key that anyone can use to verify the authenticity of the digital signature.

You can create a key pair with the Keystores Manager as described in "Managing Keystores and Key Pairs."

12.3.1 Sign a CLDC Project With a Key Pair

Follow these steps to sign a CLDC project with a key pair:

Right-click a project and select Properties.
From the Build category, select Signing.
Check the Sign Distribution checkbox.
Select a keystore from the Keystores drop-down menu, or click Open Keystores Manager to create a keystore.

The Certificate Details area displays the Subject, Issuer, and Valid (validity dates for the selected keystore) information.
Select a key pair alias from the drop-down menu.

A keystore might be accessed by several key pairs, each with a different alias. If you prefer to use a unique key pair, select Open Keystores Manager and create a new key pair. See "Create a Keystore."
Click OK.

See "Obfuscating."

12.3.2 Sign a CDC Project

To sign a CDC project use the JDK jarsigner command from the command line. For example:

jarsigner.exe -keystore keystore.ks -storepass keystorepwd MyCdcApp.jar dummyCA

12.4 Managing Keystores and Key Pairs

For test purposes, you can create a signing key pair to sign a MIDlet. The Keystores Manager administers this task, as described in the remainder of this topic, the key pair consists of two keys:

A private key that is used to create a digital signature, or certificate.
A public key anyone can use to verify the authenticity of the signature.

To deploy on a device, you must obtain a signing key pair from a certificate authority recognized by the device. You can also import keys from an existing Java SE platform keystore.

The following topics describe the user interface:

"Security Domains"
"Create a New Key Pair"
"Remove a Key Pair"
"Import an Existing Key Pair"

You can also use the command line tools described in "Command Line Security Features."

12.4.1 Working With Keystores and Key Pairs

The Keystores Manager handles creating and using keystores. The keystores known to the Keystores Manager are listed when you sign a project, as described in "Signing.".

Keystores contain key pairs, which you can also manage from this dialog. You must select a keystore to access the key pair tools.

Section 12.1, "Security Domains"
Section 12.4.1.3, "Create a New Key Pair"
Section 12.4.1.4, "Remove a Key Pair"
Section 12.4.1.5, "Import an Existing Key Pair"

12.4.1.1 Create a Keystore

Select the Tools menu and select Keystores.

The Keystores Manager opens.
Click Add Keystore....

The Add Keystores window opens.
Select Create a New Keystore.
Supply a name, location, and password.
Click OK.

The new keystore appears in the Keystores list.

12.4.1.2 Add an Existing Keystore

Select the Tools menu and select Keystores.

The Keystores Manager opens.
Click Add Keystore....

The Add Keystores window opens.
Select Add Existing Keystore.
Browse to the location of the keystore and select the keystore file. The default location for user-defined keystores is:

username
Select a keystore and Click Open, then click OK.

The existing keystore appears in the Keystores list. You might have to unlock this keystore, and each key pair within it.

12.4.1.3 Create a New Key Pair

Select the Tools menu and select Keystores.

The Keystores Manager opens.
Select a Keystore in the Keystores area on the left. If you prefer a different keystore, you can create one as described in "Create a Keystore."

Note, you cannot add a key to the Built-in Keystore, but you can export a key from it.
Click the New... button.
Fill in the Create Key Pair dialog:

You must provide an alias to refer to this key pair.

The six Certificate Details fields are provisionally optional. You must complete at least one field.

Key Pair Alias. The name used to refer to this key pair.

Common Name. Common name of a person, such as "Jane Smith"

Organization Unit. Department or division name, such as "Development"

Organization Name. Large organization name, such as "Oracle Corporation"

Locality Name. Locality (city) name, such as "Santa Clara"

State Name. State or province name, such as "California"

Country. Two-letter country code, such as "US"

Although not required, you should provide a password. The password should be at least six characters long.
Click OK.

The new key is displayed in the Keys area under its alias. You can now select this keypair when you sign a project. See "Signing a Project."

12.4.1.4 Remove a Key Pair

Select the Tools menu and select Keystores.
In the Keys area, click a Key Pair.
Select Delete. You are asked if you are sure. Click Yes if you are and the delete proceeds.

12.4.1.5 Import an Existing Key Pair

If you have keys in a Java SE platform keystore that you would like to use for MIDlet signing, you can import the signing keys to the Oracle Java ME SDK.

Select the Tools menu and select Keystores.
Click Add Keystore....

The Add Keystore window opens.
Click Add Existing Keystore.
Browse to the keystore location.
Click OK.

12.5 Managing Root Certificates

The Oracle Java ME SDK command line tools described in "Manage Certificates (MEKeyTool)" manage the emulator's list of root certificates.

External devices have similar lists of root certificates, although you typically cannot modify them. When you deploy your application on an external device, you must use signing keys issued by a certificate authority whose root certificate is present on the device. This makes it possible for the device to verify your application.

Each emulator instance has its own _main.ks file located in its appdb directory. For example: username\javame-sdk\3.4\work\devicename\appdb.

You can use the -import option to import certificates from these keystores as described in "Manage Certificates (MEKeyTool)."