org.apache.river.api.security

Class PermissionGrant

java.lang.Object

org.apache.river.api.security.PermissionGrant

public abstract class PermissionGrant
extends Object

PermissionGrant implementations are expected to be immutable, non blocking, thread safe and have a good hashCode implementation to perform well in Collections.

Developers may use decorators to alter the behaviour of existing implementations. Decorators should use a single transient volatile field to store the result of an event notification, which must be immutable, state may not be updated in the policy until Policy.refresh() is called. It is the implementors responsibility to call refresh.

PermissionGrant does not implement Serializable for security reasons, however classes extending PermissionGrant may implement Serializable, but are forced to use the Serializable Builder Pattern.

PermissionGrant's are security sensitive objects and can provide an attacker with information about granted Permission. For this reason, it is wise to guard references to PermissionGrant or to avoid storing them in object fields altogether.

Caveat Implementor: PermissionGrant's can only make calls to other objects that themselves perform security checks during an implies call if all ProtectionDomains involved are privileged and the call is performed within PrivilegedAction. PrivilegedAction's should generally be performed prior to creating a PermissionGrant if possible.

Only PermissionGrant's who's ProtectionDomain has AllPermission can perform PrivilegedAction's during Policy.implies(java.security.ProtectionDomain, java.security.Permission) calls, since the Policy checks privileged PermissionGrant's and returns without checking less privileged PermissionGrant's that would cause an infinite recursion. Infinite recursion could be used as a denial of service by an attacker that can access an acting Policy

Since:

3.0.0

Author:

Peter Firmstone

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PermissionGrant(PermissionGrant decorated) PermissionGrant allows for extension to enable condition or event based policy decisions.

Method Summary

Modifier and Type	Method and Description
protected PermissionGrant	decorated()
boolean	equals(Object o)
abstract PermissionGrantBuilder	getBuilderTemplate() Provide a PermissionGrantBuilder, suitable for producing a new PermissionGrant.
Collection<Permission>	getPermissions() Returns an unmodifiable Collection of permissions defined by this PermissionGrant, which may be empty, but not null.
int	hashCode()
abstract boolean	implies(ClassLoader cl, Principal[] pal) Checks if this PermissionGrant applies to the passed in ClassLoader and Principal's.
abstract boolean	implies(CodeSource codeSource, Principal[] pal) Checks if this PermissionGrant applies to the passed in CodeSource and Principal's.
abstract boolean	implies(ProtectionDomain pd) A DynamicPolicy implementation can use a PermissionGrant as a container for Dynamic Grant's.
abstract boolean	impliesEquivalent(PermissionGrant grant) Checks whether grant logic is identical for the passed in PermissionGrant.
abstract boolean	isDyanamic() Returns true if the grant can only be dynamically granted at runtime.
boolean	isPrivileged() Optimisation for AllPermission.
abstract boolean	isVoid() Returns true if this PermissionGrant defines no Permissions, or if a PermissionGrant was made to a ProtectionDomain that no longer exists.

Methods inherited from class java.lang.Object

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

Constructor Detail

PermissionGrant

protected PermissionGrant(PermissionGrant decorated)

PermissionGrant allows for extension to enable condition or event based policy decisions. Extending classes can add functionality using the decorator pattern.

A privileged ProtectionDomain that contains AllPermission cannot be decorated and will throw an IllegalArgumentException. This is to prevent accidental infinite recursion; policy's that utilize PermissionGrant will check privileged PermissionGrant's first to avoid infinite recursion.

A decorated PermissionGrant that calls methods that perform security checks during implies, must do so from within a PrivilegedAction and all subsequent domains on the stack required to perform the PrivilegedAction must have AllPermission and to avoid infinite recursion. If possible avoid security checks while making implies determinations, by having an external event thread perform the privileged action and update a volatile variable that can be checked during an implies call without invoking another security check.

Parameters:

decorated - PermissionGrant to be decorated.

Throws:

IllegalArgumentException - if decorated is privileged

SecurityException - if caller doesn't have RuntimePermission "getProtectionDomain" or "getClassLoader".

Method Detail

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object

decorated

protected final PermissionGrant decorated()

isPrivileged

public final boolean isPrivileged()

Optimisation for AllPermission.

Returns:

true - if PermissionGrant contains AllPermission.

implies

public abstract boolean implies(ProtectionDomain pd)

A DynamicPolicy implementation can use a PermissionGrant as a container for Dynamic Grant's. A PermissionGrant is first asked by the Policy if it applies to a Particular ProtectionDomain, if it does, the Policy calls getPermissions.

Parameters:

pd - ProtectionDomain

Returns:

true if implies.

See Also:

RevocablePolicy

implies

public abstract boolean implies(ClassLoader cl,
                                Principal[] pal)

Checks if this PermissionGrant applies to the passed in ClassLoader and Principal's. Note that if this method returns false, it doesn't necessarily mean that the grant will not apply to the ClassLoader, since it will depend on the contents of the ClassLoader and that is indeterminate. It just indicates that the grant definitely does apply if it returns true. If this method returns false, follow up using the ProtectionDomain for a more specific test, which may return true.

Parameters:

cl - - ClassLoader possibly implied

pal - - Principal's possibly implied

Returns:

true if the ClassLoader and Principal's are implied.

implies

public abstract boolean implies(CodeSource codeSource,
                                Principal[] pal)

Checks if this PermissionGrant applies to the passed in CodeSource and Principal's.

Parameters:

codeSource -

pal -

Returns:

true if implies.

impliesEquivalent

public abstract boolean impliesEquivalent(PermissionGrant grant)

Checks whether grant logic is identical for the passed in PermissionGrant. The permissions granted are not considered, only the imply logic. The main purpose of this method is to allow external consolidation of permissions from a number of grants into one equivalent PermissionGrant.

Parameters:

grant -

Returns:

true if the grant implies logic is identical to this grant.

isDyanamic

public abstract boolean isDyanamic()

Returns true if the grant can only be dynamically granted at runtime. That is, it isn't possible to specify in a policy file grant.

Returns:

getPermissions

public final Collection<Permission> getPermissions()

Returns an unmodifiable Collection of permissions defined by this PermissionGrant, which may be empty, but not null.

Returns:

Collection containing Permission objects.

isVoid

public abstract boolean isVoid()

Returns true if this PermissionGrant defines no Permissions, or if a PermissionGrant was made to a ProtectionDomain that no longer exists.

Returns:

true if void.

getBuilderTemplate

public abstract PermissionGrantBuilder getBuilderTemplate()

Provide a PermissionGrantBuilder, suitable for producing a new PermissionGrant.

Returns:

PermissionGrantBuilder