Interface Summary
Interface	Description
MIDletProperties	Interface supplied to the Authentication provider by AMS.
PolicyReader	Interface to read the security policy from stream.
PolicyReaderCallback	This interface defines callback that called from the policy reader.

Class Summary
Class	Description
AuthenticationProvider	This class implements core functionality of the authentication provider.
Client	This class implements client as defined in MEEP specification.
DefaultPolicyReader	Policy reader that implements policy file format defined in MEEP specification.
Permissions	This class represents a heterogeneous collection of Permissions.
Policy	This class implements core functionality of the security policy provider.

Enum Summary
Enum Description

AuthenticationProviderException.ErrorCode
Authentication provider error codes.

Enum Summary
Enum	Description
AuthenticationProviderException.ErrorCode	Authentication provider error codes.

Exception Summary
Exception	Description
AuthenticationProviderException	Exception to report authentication error as defined in MEEP specification.
PolicyReaderException	This class defines policy reader exception that used to report policy format error.

Package com.oracle.meep.security Description

Provides classes necessary to create custom authentication and security policy providers as defined by MEEP specification.

Class Overview

There are two main classes that should be used to create custom providers:

Building Providers

Authentication Provider

The purpose of the authentication provider is to verify an application or LIBlet and return the list of appropriate clients.

Custom authentication provider must extend AuthenticationProvider and implement the following abstract methods:

Authenticating Application

To authenticate applications and LIBlets custom authentication provider must implement AuthenticationProvider.authenticateApplication(com.oracle.meep.security.MIDletProperties, java.io.InputStream). This method should either return the list of clients to which an application/LIBlet is bound or report authentication error by throwing AuthenticationProviderException.

Application properties from JAD and/or manifest and application JAR file can be used for authentication purposes.

To access the list of clients defined by the security policy the following methods should be used:

Policy.getPolicy() - to access security policy provider instance
Policy.getClients() - to get the list of all clients except virtual clients
Policy.getClient(java.lang.String) - to get client by the name
Policy.getRootClient() - to get virtual root client
Policy.getUntrustedClient() - to get virtual untrusted client

Example

The following custom authentication provider selects clients depending on 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() {
     }    
 }

Security Policy Provider

The purpose of the security policy provider is to define the list of clients and their protection domains. Protection domain of a client is a set of permissions that can be granted to the application bound to this client.

Custom security policy provider must extend Policy and implement abstract method Policy.initialize(). This method is called by security framework and is responsible for security policy initialization. During initialization custom security policy provider must use helper methods to create the list of clients:

Policy.addClient(com.oracle.meep.security.Client)

Example

The following custom security policy provider defines 2 clients with different protection domains and also specifies protection domain for 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");
         clientA.addPermissions(new javax.microedition.io.HttpProtocolPermission("http://locahost:80/"),
             new javax.microedition.io.SSLProtocolPermission("ssl://:*"));
         addClient(clientA);
         
         Client clientB = new Client("clientB");
         clientB.addPermissions(new javax.microedition.io.PushRegistryPermission("*", "static,dynamic,alarm"));
         addClient(clientB);
         
         getUntrustedClient().addPermissions(new javax.microedition.location.LocationPermission("location", "location"));
     }    
 }

Installing Providers

To install custom authentication and/or security policy providers the following steps should be made:

Build custom providers into a single jar. API stubs should be found in <sdk>\lib\ext\security_api.jar.
Set runtime internal property security.providers.jar to the location of the jar. The path should be either absolute or relative to the working directory of the runtime.

Overload default authentication and/or security policy provider classes by setting runtime internal properties:

Property	Description	Default Value
authentication.provider	Authentication provider class	com.oracle.meep.security.DefaultAuthenticationProvider
microedition.security.policy	Security policy provider class	com.oracle.meep.security.DefaultSecurityPolicy

Example

security.providers.jar = appdb/providers.jar
On SDK this location will be expanded to C:\Users\<USER>\javame-sdk\8.0\work\EmbeddedDevice1\appdb\providers.jar

authentication.provider = com.company.security.AuthProvider

microedition.security.policy = com.company.security.PolicyProvider