org.apache.river.api.security

Class DelegatePermission

java.lang.Object

java.security.Permission

org.apache.river.api.security.DelegatePermission

All Implemented Interfaces:

Serializable, Guard

public final class DelegatePermission
extends Permission

Permissions such as SocketPermission or FilePermission guard a resource but allow that resource to escape the control of the SecurityManager and Policy provider, this prevents them from being revoked. DelegatePermission supports Li Gong's method guard pattern, by allowing developers to implement a method guard delegate object, that checks for the DelegatePermission on every invocation, without allowing a reference to the resource to permanently escape the control of the SecurityManager or Policy provider.

A DelegatePermission represents any other Permission, called a candidate Permission. A user granted a DelegatePermission does not have the privilege of the candidate Permission, although a user with a candidate Permission has the privilege of the DelegatePermission that represents the candidate, while the @ref DelegateSecurityManager is in force.

A DelegatePermission requires a method guard delegate to encapsulate a privileged resource. The developer is responsible for developing the method guard wrapper, an example for SocketFactory can be found on Apache River's svn.

A method guard delegates ProtectionDomain is granted the candidate permission, the security delegate allows any user granted a DelegatePermission to utilise the functions that its candidate Permission guards, when the user no longer has the DelegatePermission, the method guard delegate no longer allows the user to access the functions guarded by the candidate permission. A security delegate has the responsibility to prevent security sensitive objects guarded by the candidate permission from escaping. In order to do so, a security delegate utilises Li Gong's proposed method guard pattern.

Security Delegates enable sensitive objects to be used by code that isn't fully trusted you may want to monitor, such as a file write that is limited by the number of bytes written, or a Permission to write a file, that we might decide to retract or revoke if a user does something we don't like, such as exceed a pre set limit or behave in a manner we would like to avoid, such as hogging network bandwidth.

If the SecurityManager installed doesn't implement DelegateSecurityManager, DelegatePermission's will be disabled. This allows delegate's to be included in code, the decision to utilise delegate functionality may delayed until runtime or deployment.

The DelegatePermissionCollection returned by newPermissionCollection() is not synchronized, this decision was made because PermissionCollection's are usually accessed from within a heterogenous PermissionCollection like Permissions that synchronizes anyway. The decision made for the PermissionCollection contract to be synchronized has been broken deliberately in this case, existing PermissionCollection implementations don't cleanly protect their internal state with synchronization, since the Enumeration returned by elements() will throw a ConcurrentModificationException if in a loop when Permission's are being added to a PermissionCollection. In this case external synchronization must be used.

Serialization has been implemented so the implementation is not tied to the serialized form, instead serialization proxy's are used.

A candidate permission is referred to as a target in the following explanation of DelegatePermission policy file syntax.

The syntax of the target name approximates that used for specifying permissions in the default security policy file; it is listed below using the same grammar notation employed by The Java(TM) Language Specification:

 Target:
   DelimiterDeclarationopt Permissions ;opt
   
 DelimiterDeclaration:
   delim = DelimiterCharacter
   
 Permissions:
   Permission
   Permissions ; Permission
   
 Permission:
   PermissionClassName
   PermissionClassName Name
   PermissionClassName Name , Actions
   
 PermissionClassName:
   ClassName
   
 Name:
   DelimitedString
   
 Actions:
   DelimitedString
 

The production for ClassName is the same as that used in The Java Language Specification. DelimiterCharacter can be any unquoted non-whitespace character other than ';' (single and double-quote characters themselves are allowed). If DelimiterCharacter is not specified, then the double-quote character is the default delimiter. DelimitedString is the same as the StringLiteral production in The Java Language Specification, except that it is delimited by the DelimiterDeclaration-specified (or default) delimiter character instead of the double-quote character exclusively.

Note that if the double-quote character is used as the delimiter and the name or actions strings of specified permissions themselves contain nested double-quote characters, then those characters must be escaped (or in some cases doubly-escaped) appropriately. For example, the following policy file entry would yield a GrantPermission containing a FooPermission in which the target name would include the word "quoted" surrounded by double-quote characters:

 permission org.apache.river.api.security.DelegatePermission
     "FooPermission \"a \\\"quoted\\\" string\"";
 

For comparison, the following policy file entry which uses a custom delimiter would yield an equivalent GrantPermission:

 permission org.apache.river.api.security.DelegatePermission
     "delim=| FooPermission |a \"quoted\" string|";
 

Some additional example policy file permissions:

 // allow granting of permission to listen for and accept connections
 permission org.apache.river.api.security.DelegatePermission
     "java.net.SocketPermission \"localhost:1024-\", \"accept,listen\"";

 // allow granting of permissions to read files under /foo, /bar directories
 permission org.apache.river.api.security.DelegatePermission 
     "delim=' java.io.FilePermission '/foo/-', 'read'; java.io.FilePermission '/bar/-', 'read'";
 

Since:

3.0.0

Author:

Peter Firmstone

See Also:

Serialized Form

Method Summary

Modifier and Type	Method and Description
void	checkGuard(Object object)
boolean	equals(Object obj)
static Permission	get(Permission p) Factory method to obtain a DelegatePermission, this is essential to overcome broken equals contract in some jvm Permission implementations like SocketPermission and to allow caching.
String	getActions()
Permission	getPermission()
int	hashCode()
boolean	implies(Permission permission)
PermissionCollection	newPermissionCollection()

Methods inherited from class java.security.Permission

getName, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

get

public static Permission get(Permission p)

Factory method to obtain a DelegatePermission, this is essential to overcome broken equals contract in some jvm Permission implementations like SocketPermission and to allow caching.

Parameters:

p - Permission to be represented.

Returns:

DelegatePermission

checkGuard

public void checkGuard(Object object)
                throws SecurityException

Specified by:

checkGuard in interface Guard

Overrides:

checkGuard in class Permission

Throws:

SecurityException

implies

public boolean implies(Permission permission)

Specified by:

implies in class Permission

getPermission

public Permission getPermission()

equals

public boolean equals(Object obj)

Specified by:

equals in class Permission

hashCode

public int hashCode()

Specified by:

hashCode in class Permission

getActions

public String getActions()

Specified by:

getActions in class Permission

newPermissionCollection

public PermissionCollection newPermissionCollection()

Overrides:

newPermissionCollection in class Permission