java.lang.isolate
Class IsolatePermission

java.lang.Object
  |
  +--java.security.Permission
        |
        +--java.security.BasicPermission
              |
              +--java.lang.isolate.IsolatePermission

All Implemented Interfaces:

Guard, Serializable

public class IsolatePermission

extends BasicPermission

This class represents access to or creation of an isolate or link. An IsolatePermission contains a target name but no actions list; you either have the named permission or you don't.

The target name is the name of the isolate-related permission (see below). The naming convention follows the hierarchical property naming convention (though only the "send" and "receive" permissions have a hierarchy). The "*" target represents all IsolatePermission permissions.

The following table lists all the possible IsolatePermission target names, and for each provides a description of what the permission allows and a discussion of the risks of granting the permission.

Permission Target Name	What the Permission Allows	Risks of Allowing this Permission	Notes
create	Creating new isolates	This is an extremely dangerous permission to grant. Being able to create an Isolate instance is tantamount to granting AllPermission because the security environment of the new isolate is entirely under the control of the creator.
receive.{mtype}	Receipt of an IsolateMessage containing the specified type on a Link.	Allows malicious code to receive objects which it should not have access to.	See "Send and Receive Types", below.
send.{mtype}	Dispersal of an IsolateMessage containing the specified type on a Link or via Isolate.start.	Allows malicious or broken code to disperse objects which it should not propagate.	See "Send and Receive Types", below.
control	Invoking exit or halt on an Isolate	Allows malicious code to kill other isolates for which it has an Isolate instance.	Additional permissions may be required when terminating the current isolate.
context	Retrieval of the current isolate's context via Isolate.currentIsolateContext, currentIsolateIOBindings, or Isolate.currentIsolateStartMessages.	Depending on the use of the context, it may allow malicious code to change entries in the context that are used by libraries or other other middleware code, or access low-level IO bindings or private startup messages.

Isolate Security Architecture

Creating a new isolate is a very security sensitive operation because a new isolate has its own security environment that is initialized by standard system properties that, in turn, can be set in the new isolate's context. Code that creates a new isolate must be as trusted as code that creates a new ClassLoader or has permission to invoke Policy.setPolicy. By default, a new isolate will run with the aggregate default security manager settings (which defaults to leaving the relevant values unset, implying there is no default security manager).

See ' Default System and User Policy Files' in Chapter 3 of the Java 2 Platform Security Architecture for details on which standard system properties are used to configure the initial security policy.

The default security policy denies all isolate-related permissions except IsolatePermission("context").

Send and Receive Types

The "send.{mtype}" and "receive.{mtype}" targets should use one of the explicit types defined by the IsolateMessage factory methods to finely control the objects that an isolate can send or receive. Specifically, {mtype} can take one of the following values: "ByteArray", "ByteBuffer", "DatagramChannel", "DatagramSocket", "FileChannel", "FileInputStream", "FileOutputStream" "Isolate", "IsolateEvent", "Link", "PipeSink", "PipeSource", "Serializable", "ServerSocket", "ServerSocketChannel", "Socket", "SocketChannel", "String" plus "*". The {mtype} is case insensitive. The "*" implies any type of message can be transferred.

Note that there are no "send.Composite" or "receive.Composite" permission targets. When sending or receiving a composite message access checks will instead be performed on each of the constituent elements of the composite.

Usage Examples

The following two usage example demonstrate different ways of setting up the security environment of a new isolate.

Default Security Manager:

To start a new isolate with the default security manager set the java.security.manager property in the new isolate's context. All code that runs in the new isolate will be subject to the default policy:

 public Isolate isolateWithDefaultSecurity(String mainclass, String[] args) {
   TransientPreferences context = new TransientPreferences();
   // See Isolate.currentIsolateContext for details:
   context.put("java.preferences/java.security.manager", "");
   Isolate i = new Isolate(mainclass, args, context, null, null, null);
   return i;
 }
 

Privileged Proxy:

To run trusted initialization code in a new isolate before setting up a restricted environment, use a proxy class to initialize the isolate in the new isolate before loading the untrusted code:

 import java.security.*;
 import java.lang.isolate.*;

 public class AppProxy {
   private static AccessControlContext allAccessContext;

   // Spawn a new child.  Only code with IsolatePermission("create")
   // can complete this.  New isolate will run Proxy.main first.
   // New isolate is created with no security manager (default behavior)
   public static void spawn(String appmainclassname) {
     Isolate c = new Isolate(this.getClass().getName(), 
                             new String[] { appmainclassname });
     c.start(null);
   }

   // main invoked when a new proxy is created.  Initialize, install
   // security manager, and then execute the "real" app
   public static void main(String[] args) {
     Permission isoCreate = new IsolatePermission("create");

     // don't let user code re-run this method
     AccessController.checkPermission(isoCreate);

     // Do some trusted initialization of the child isolate
     ...  // e.g., open some sockets or files, connect to a database, etc.

     // Save off current security context (all access granted)
     // (would be better if it saved a context with only the required permissions)
     AppProxy.allAccessContext = AccessController.currentIsolateContext();

     // Install default SecurityManager
     System.setSecurityManager(new SecurityManager())

     runRealApp(args[0]); 
   }

   // let the "real" app do some well-controlled privileged operations
   public static void doPrivilegedOperation() {
     AccessController.doPrivileged(new PrivilegedAction() {
       public Object run() {
          // Do some trusted operations when asked by untrusted code
          ... // e.g., flush to db, get new files/sockets, etc.
       }
     }, AppProxy.allAccessContext);
     return p;
   }

   // Use reflection to look up the "real" app main
   public void runRealApp(String app) { ... }
   
 }
 

See also the Security Section of the specification.

See Also:

Serialized Form

This API element may not be present in some J2ME profiles.

This API element must be present with the following J2ME configurations, profiles, or optional packages:

CDCv1.0

Constructor Summary

IsolatePermission(String name)
Creates a new IsolatePermission with the specified name.

IsolatePermission(String name, String actions)
Creates a new IsolatePermission object with the specified name.

Methods inherited from class java.security.BasicPermission

equals, getActions, hashCode, implies, newPermissionCollection

Methods inherited from class java.security.Permission

checkGuard, getName, toString

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

IsolatePermission

public IsolatePermission(String name)

Creates a new IsolatePermission with the specified name. The name is the symbolic name of the IsolatePermission, such as: "create", "send.Link", "receive.*", or "control." The value "*" may be used to indicate all isolate permissions.

Parameters:

name - the name of the IsolatePermission

Throws:

NullPointerException - if name is null

IsolatePermission

public IsolatePermission(String name,
                         String actions)

Creates a new IsolatePermission object with the specified name. The name is the symbolic name of the IsolatePermission, and the actions string is currently unused and ignored. This constructor exists for use by the Policy object to instantiate new permission objects.

Parameters:

name - the name of the IsolatePermission

actions - ignored but null suggested