This chapter contains the following topics:
You can find the Java ME Embedded Profile specification in the meep-8.0.zip
file located under docs\api
in the Oracle Java ME SDK installation directory. In particular, the following chapters in the specification are relevant for understanding the security model:
Security for Applications
Security Authentication Providers
Security Policy Providers
The security model works as follows:
The author of the Java ME Embedded application, probably a software company, buys a signing key pair from a certificate authority (CA) and signs the IMlet suite.
When the IMlet suite is installed on a device, the authentication provider verifies the author's certificate using its own copy of the CA's root certificate. Then the authentication provider uses the author's certificate to verify the signature on the IMlet suite.
After verification, the IMlet suite is assigned to one of the clients defined by the security policy. The default authentication scheme (X.509-based certificate) uses the certificate DN to determine to which client an application must be bound.
Oracle Java ME SDK supports the following security provider clients by default:
Manufacturer
: This client is configured by the device vendor. You should not modify the list of permissions.
Operator
: This client has all permissions granted by default, and you can modify the list if necessary.
untrusted
: Defines the security policy for unsigned applications. According to the X.509 authentication scheme, unsigned applications are bound to the untrusted
client.
The security policy of a device defines clients to which an IMlet suite can be assigned after authentication. Each client has an associated security protection domain that defines the permissions that may be granted to an application assigned to this client.
To configure the security policy for a device:
Right-click the device in the Device Selector tab and select Security Configuration.
Figure 10-1shows the Security Configuration window.
Figure 10-1 The Security Configuration Window
The options in the Security Providers group at the top of the Security Configuration window can be used if you want to specify a custom security provider implementation JAR file, and class names of your custom authentication provider and security policy provider. For information about creating custom authentication and security policy providers, see Custom Security Policy and Authentication Providers.
To add a client to the security policy:
Click Add under the Clients list, specify a name and click OK.
When you select a client from the list, you can add, edit, and remove permissions for the selected client.
To add a permission for a client:
Select the client and click Add under the Permissions list.
Select the permission from the list, specify the name of the protected resource (you can use wildcards) and the requested actions separated by commas (for example, read,write
), and click OK.
To edit a permission, select it from the list of permissions, and click Edit under the Permissions list. To remove a permission, select it in the list, and click Remove.
Devices use signing information to verify an application's source and validity before allowing it to access protected APIs.
Oracle Java ME SDK provides a default built-in keystore, but you can also create any number of key pairs using the Keystores Manager as described in Managing Keystores and Key Pairs.
The key pair consists of the following keys:
A private key that is used to create a digital signature.
A public key that anyone can use to verify the authenticity of the digital signature.
To sign a Java ME Embedded Application project with a key pair in NetBeans IDE:
Right-click a project and select Properties.
In the Signing category, select Sign JAR.
Select a keystore and a key pair alias.
Click OK.
To sign a Java ME project with a key pair in Eclipse IDE:
For an emulated device, it is also necessary to export the root certificate to the device. For more information, see Managing Root Certificates.
For test purposes, you can create a signing key pair to sign an IMlet. In both NetBeans IDE and Eclipse IDE, the Keystores Manager administers this task.
The instructions below relate to NetBeans IDE.
To deploy an IMlet 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.
To create a keystore in NetBeans IDE:
Open the Tools menu and select Keystore Management.
Click Add Keystore.
Select Create a New Keystore and specify a name, location, and password.
Click OK.
To add an existing keystore in NetBeans IDE:
Open the Tools menu and select Keystore Management.
Click Add Keystore.
Select Add Existing Keystore and specify the path to the keystore file. The default location for user-defined keystores is the user's folder under C:\Users
.
Click OK.
You might have to unlock this keystore and each key pair within it.
To create a new key pair in NetBeans IDE:
To remove a key pair, select it in the list and click Delete.
The Oracle Java ME SDK 8.3 command-line tools manage the emulator's list of root certificates.
External devices have similar lists of root certificates. When you deploy your application on an external device, you must use signing keys issued by a certificate authority whose root certificate is on the device. This makes it possible for the device to verify your application.
Each emulator instance has a shared keystore and one for each of the security clients. The shared keystore file is named _main.ks
and located under appdb\certs
in the device's configuration directory.
You can use the -import
option to import certificates from these keystores as described in Manage Certificates (mekeytool).
To export a certificate to an emulated device in NetBeans IDE:
The full spectrum of the Oracle Java ME SDK 8.3 security features are available from the command line. You can adjust the emulator's default protection domain, sign IMlet suites, and manage certificates.
This section contains the following topics:
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:
Prints usage instructions for jadtool
.
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>
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]
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:
Prints usage instructions for mekeytool
.
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 |
---|---|---|
|
Path to the DER, PKCS12, PEM, or JKS keystore file or file that contains the certificate |
|
|
Password to unlock the input DER, PKCS12, PEM, or JKS keystore |
N/A |
|
Private key password for the PKCS12, PEM, or JKS keystore |
N/A |
|
The key pair alias in the input JKS keystore |
N/A |
|
The name of the target security client |
N/A |
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.
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 |
---|---|---|
|
The key number in the keystore. Keys are numbered starting from 1. To view the key number, use the |
N/A |
|
The key owner. |
N/A |
|
The name of the target security client |
N/A |
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 |
---|---|---|
|
The key number in the keystore. Keys are numbered starting from 1. To view the key number, use the |
N/A |
|
Name of the output file. |
N/A |
|
The name of the target security client |
N/A |
Prints the list of security clients that can accept public keys.
Device emulators in Oracle Java ME SDK are bundled with default security policy and authentication providers that can be used without any modification or configured to your needs, as described in Configuring the Security Policy for a Device. You can also create custom security policy and authentication providers, as defined in the MEEP specification.
The classes necessary to create custom security policy and authentication providers are defined in the com.oracle.meep.security
package. You can find a detailed Javadoc of this package in the security_api_javadoc.zip
file located under docs\api
in the Java ME SDK installation directory.
The purpose of a security policy provider is to define the list of clients and their protection domains. A protection domain of a client is a set of permissions that can be granted to the Java ME Embedded application bound to this client.
A custom security policy provider must extend the Policy
class and implement the Policy.initialize()
abstract method. This method is called by the security framework and is responsible for security policy initialization. During initialization, the custom security policy provider must use the Policy.addClient(com.oracle.meep.security.Client)
helper method to create the list of clients.
The following example shows how to create a custom security policy provider that defines two clients with different protection domains and specifies a separate protection domain for the virtual untrusted
client.
package com.company.security; import com.oracle.meep.security.Client; import com.oracle.meep.security.Policy; public class PolicyProvider extends Policy { public void initialize() { Client clientA = new Client("clientA", null); clientA.addPermissions(new javax.microedition.io.HttpProtocolPermission("http://locahost:80/"), new javax.microedition.io.SSLProtocolPermission("ssl://:*")); addClient(clientA); Client clientB = new Client("clientB", null); clientB.addPermissions(new javax.microedition.io.PushRegistryPermission("*", "static,dynamic,alarm")); addClient(clientB); getUntrustedClient().addPermissions(new javax.microedition.location.LocationPermission("location", "location")); } }
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:
security_api.jar
archive under lib\ext
in the Java ME SDK installation directory. The default location is C:\Java_ME_platform_SDK_8.3\lib\ext\security_api.jar
To install custom security providers on a physical external device, see the documentation for the device.