10 Custom Security Policy and Authentication Providers

Sample Custom Security Policy Provider

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.

Example 10-1 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"));
    }
}

Sample Custom Authentication Provider

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.

Example 10-2 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() {
    }    
}

Installing Custom Providers

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

1. Build the provider into a single JAR file. You can find API stub files in the security_api.jar archive under lib\ext in the Java ME SDK installation directory. The default location is C:\Java_ME_platform_SDK_8.1\lib\ext\security_api.jar

2. Right-click an emulated device in the Device Selector tab and select Security Configuration.

3. Specify the path to the custom security provider implementation JAR file, and the class names of the authentication and security policy providers. For more information about using the Security Configuration window, see "Configuring the Security Policy for a Device".

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