10 About the Java ME Embedded Security Model

jadtool is a command-line interface to sign IMlet suites using public key cryptography according to the MEEP specification. Signing an IMlet suite is the process of adding the signer certificates and the digital signature of the JAR file to a JAD file. jadtool is also capable of signing payment update (JPP) files.

jadtool only uses certificates and keys from Java SE platform keystores. Java SE software provides keytool, the command-line tool to manage Java SE platform keystores.

jadtool.exe is located under bin in the Java ME SDK installation directory. For more information about the jadtool, see Signing an IMlet Suite's JAR File in the Oracle Java ME Embedded Developer’s Guide.

The following options can be used with the jadtool command:

-help

Prints usage instructions for jadtool.

-addcert

Adds the certificate of the key pair from the given keystore to the JAD file or JPP file. This option has the following syntax:

-addcert -alias <key_alias> [-storepass <password>] [-keystore <keystore>] [-certnum <number>] [-chainnum <number>] [-encoding <encoding>] -inputjad <filename> -outputjad <filename>

-addjarsig

Adds a digital signature of the input JPP file to the specified output JPP file. The -useSha256 argument changes the default signature algorithm to SHA256withRSA. If not present, SHA1withRSA signature algorithm is used. This option has the following syntax:

-addjarsig [-jarfile <filename>] -keypass <password> -alias <key_alias> -storepass <password> [-keystore <keystore>] [-chainnum <number>] [-encoding <encoding>] -inputjad <filename> -outputjad <filename> [-useSha256]

-showcert

Displays information about certificates in JAD files. This option has the following syntax:

-showcert [([-certnum <number>] [-chainnum <number>] ) | [-all]] [-encoding <encoding>] -inputjad <filename>

mekeytool manages the public keys and key pairs provided by certificate authorities (CAs). It is functionally similar to the keytool utility that comes with the Java SE Development Kit (JDK). The purpose of the public keys is to facilitate secure HTTP communication over SSL (HTTPS).

Before using mekeytool, you must have access to a DER, PKCS12, PEM, or JKS keystore. You can create one using the Java SE keytool utility (found in the bin directory under the JDK installation location) or OpenSSL.

The -Xdevice option can be used with any command to run it on the specified device. Note that not every device supports all of the mekeytool commands. Specify the device name after a colon. For example, to list the shared public keys (used only for SSL/HTTPS connections) in the keystore of EmbeddedDevice1, run the following command:

> mekeytool.exe -Xdevice:EmbeddedDevice1 -list

The following commands can be used with the mekeytool utility:

-help

Prints usage instructions for mekeytool.

-import

Imports a public key from the source keystore to the device's keystore (with or without private key).

Note:

Oracle Java ME SDK 8 supports RSA encoded public keys stored in DER, PKCS12, PEM, and JKS formats, and key pairs stored in PKCS12, PEM, and JKS formats.

This command has the following syntax:

-import [-keystore <filename>] [-storepass <password>] [-keypass <password>] [-alias <key_alias>] [-client <name>]

---

Option	Description	Default
-keystore	Path to the DER, PKCS12, PEM, or JKS keystore file or file that contains the certificate	<user.home>\.keystore.ks
-storepass	Password to unlock the input DER, PKCS12, PEM, or JKS keystore	N/A
-keypass	Private key password for the PKCS12, PEM, or JKS keystore	N/A
-alias	The key pair alias in the input JKS keystore	N/A
-client	The name of the target security client	N/A

---

-list

Lists the keys in the Java ME keystore, including the owner and validity period for each. This command has the following syntax:

-list [-client <name>]

You can specify the name of the target security client using the -client option.

-delete

Deletes a key from the given Java ME keystore with the given owner. This command has the following syntax:

-delete (-owner <owner> | -number <number>) [-client <name>]

---

Option	Description	Default
-number	The key number in the keystore. Keys are numbered starting from 1. To view the key number, use the -list option.	N/A
-owner	The key owner.	N/A
-client	The name of the target security client	N/A

---

-export

Exports the key from the keystore. If only public certificate is present, it is exported in PEM format. If there is a public certificate with a private key, it is exported in PKCS12 format. This command has the following syntax:

-export -number <number> -out <filename> [-client <name>]

---

Option	Description	Default
-number	The key number in the keystore. Keys are numbered starting from 1. To view the key number, use the -list option.	N/A
-out	Name of the output file.	N/A
-client	The name of the target security client	N/A

---

-clients

Prints the list of security clients that can accept public keys.

The purpose of an authentication provider is to verify a Java ME Embedded application or LIBlet and return the list of appropriate clients. A custom authentication provider must extend the AuthenticationProvider class and implement the following abstract methods:

• AuthenticationProvider.initialize()

• AuthenticationProvider.authenticateApplication(com.oracle.meep.security.MIDletProperties, java.io.InputStream)

The authenticateApplication() method should either return the list of clients to which an application or LIBlet is bound, or report an authentication error by throwing AuthenticationProviderException.

Application properties from JAD and JAR files can be used for authentication purposes. To access the list of clients defined by the security policy, use the following methods:

• Policy.getPolicy(): Access the security policy provider instance.

• Policy.getClients(): Get the list of all clients except for virtual clients.

• Policy.getClient(java.lang.String): Get the client by name.

• Policy.getRootClient(): Get the virtual root client.

• Policy.getUntrustedClient(): Get the virtual untrusted client.

The following example shows how to create a custom authentication provider that selects clients depending on the application vendor property.

package com.company.security;

import com.oracle.meep.security.AuthenticationProvider;
import com.oracle.meep.security.AuthenticationProviderException;
import com.oracle.meep.security.Client;
import com.oracle.meep.security.MIDletProperties;
import com.oracle.meep.security.Policy;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.List;

public class AuthProvider extends AuthenticationProvider {
    public List<Client> authenticateApplication(MIDletProperties props, InputStream in) throws AuthenticationProviderException {
        List<Client> result = new ArrayList<>();
        String vendor = props.getProperty("MIDlet-Vendor");

        switch (vendor) {
            case "Manufacturer":
                result.add(Policy.getPolicy().getRootClient());
                break;
            case "TrustedCompany":
                result.add(Policy.getPolicy().getClient("clientA"));
                result.add(Policy.getPolicy().getClient("clientB"));
                break;
            case "UntrustedCompany":
                result.add(Policy.getPolicy().getUntrustedClient());
                break;
            default:
                throw new AuthenticationProviderException(AuthenticationProviderException.ErrorCode.AUTHENTICATION_FAILURE);
        }

        return result;
    }

    public void initialize() {
    }    
}

To install a custom security policy or authentication provider on an emulated device:

To install custom security providers on a physical external device, see the documentation for the device.