net.jini.security.policy

Class DynamicPolicyProvider

java.lang.Object

java.security.Policy

org.apache.river.api.security.AbstractPolicy

net.jini.security.policy.DynamicPolicyProvider

All Implemented Interfaces:

DynamicPolicy, RevocablePolicy, ScalableNestedPolicy

Direct Known Subclasses:

DebugDynamicPolicyProvider

public class DynamicPolicyProvider
extends AbstractPolicy
implements RevocablePolicy, ScalableNestedPolicy

Security policy provider that supports dynamic granting of permissions at run-time. This provider is designed as a wrapper to layer dynamic grant functionality on top of an underlying policy provider. If the underlying provider does not implement the DynamicPolicy interface, then its permission mappings are assumed to change only when its refresh method is called. Permissions are granted on the granularity of class loader; granting a permission requires (of the calling context) GrantPermission for that permission.

This is a Dynamic Policy Provider that supports concurrent access, for instances where a Policy provider is used for a distributed network of computers, or where there is a large number of ProtectionDomains and hence the opportunity for concurrency exists, concurrency comes with a cost however, that of increased memory usage.

Due to the Java 2 Security system's static design, a Policy Provider can only augment policy files; a Policy can only relax security by granting additional permissions, this implementation adds an experimental feature for revoking permissions, however there are some caveats:

A ProtectionDomain must be created with the dynamic constructor otherwise it will never consult the policy. The AccessController.checkPermission(Permission) method consults the current AccessControlContext, which contains all ProtectionDomain's on the current thread's stack, before consulting the AccessControllContext.checkPermission(Permission), it calls AccessControllContext.optimize() which removes all duplicate ProtectionDomains in the ProtectionDomain array[]'s from the enclosing AccessContolContext for the execution domain and the nested AccessControlContext for the privileged domain (the privileged domain is an array of ProtectionDomain's on the stack since the last AccessController.doPriveleged() call). The optimize() method also calls the DomainCombiner, which, for example, gives the SubjectDomainCombiner the opportunity to manipulate the ProtectionDomain's in the privileged array, in the SubjectDomainCombiner's case, it creates new copies of the ProtectionDomain's with new Principal[]'s injected. The optimize() method returns a new optimized AccessControlContext.

Now the AccessController calls the new AccessControlContext.checkPermission(Permission), at this stage, each ProtectionDomain, if created with the dynamic constructor consults the Policy, calling Policy.implies(ProtectionDomain, Permission).

If any calls to the policy return false, the ProtectionDomain then checks its internal Permissions and if they return false, it returns false. The first ProtectionDomain in the AccessControlContext to return false causes the AccessController.checkPermission(Permission) to throw an AccessControlException

To optimise the time taken to check Permission's the ProtectionDomain's should either be static, which excludes the Policy, or dynamic with a null PermissionCollection in it's constructor,

So in order to prevent dynamic grants from finding their way into a ProtectionDomain's private PermissionCollection, this policy ensures that no dynamically grantable permissions are returned via the method:

getPermissions(Codesource source) as a precaution.

This is different to the behaviour of the previous Jini 2.0 DynamicPolicyProvider implementation where dynamically granted Permissions could escape into the ProtectionDomain's private PermissionCollection.

It is thus recommended that Static policy files only be used for setting up your privileged code and use UmbrellaGrantPermission's and grant all other Permission's using dynamic grants.

The underlying policy provider may be set using the System property:

,

net.jini.security.policy.PolicyFileProvider.basePolicyClass = org.apache.river.security.concurrent.ConcurrentPolicyFile

Since:

2.0

See Also:

ProtectionDomain, Policy, ConcurrentPolicyFile, PolicyFileProvider, CachingSecurityManager, RemotePolicy

Nested Class Summary

Nested classes/interfaces inherited from class java.security.Policy

Policy.Parameters

Field Summary

Fields inherited from class org.apache.river.api.security.AbstractPolicy

ALL_PERMISSION, comparator, umbrella

Fields inherited from class java.security.Policy

UNSUPPORTED_EMPTY_COLLECTION

Constructor Summary

Constructors

Constructor and Description
DynamicPolicyProvider() Creates a new DynamicPolicyProvider instance that wraps a default underlying policy.
DynamicPolicyProvider(Policy basePolicy) Creates a new DynamicPolicyProvider instance that wraps around the given non-null base policy object.

Method Summary

Modifier and Type	Method and Description
Permission[]	getGrants(Class cl, Principal[] principals) If this security policy provider supports dynamic permission grants, returns a new array containing the cumulative set of permissions dynamically granted to protection domains (including ones not yet created) that are associated with the class loader of the given class and possess at least the given set of principals.
List<PermissionGrant>	getPermissionGrants(ProtectionDomain domain) Returns a new List containing immutable PermissionGrant's, the List returned is not synchronised and must not be shared with policy internal state.
PermissionCollection	getPermissions(CodeSource codesource)
PermissionCollection	getPermissions(ProtectionDomain domain)
void	grant(Class cl, Principal[] principals, Permission[] permissions) If this security policy provider supports dynamic permission grants, grants the specified permissions to all protection domains (including ones not yet created) that are associated with the class loader of the given class and possess at least the given set of principals.
boolean	grant(PermissionGrant p) A dynamic grant.
boolean	grantSupported() Returns true if this policy provider supports dynamic permission grants; returns false otherwise.
boolean	implies(ProtectionDomain domain, Permission permission)
void	refresh() Calling refresh doesn't remove any dynamic grant's, it only clears the cache and refreshes the underlying Policy, it also removes any grants for ProtectionDomains that no longer exist.
boolean	revokeSupported() Checks if policy supports revocation.

Methods inherited from class org.apache.river.api.security.AbstractPolicy

checkCallerHasGrants, checkNullElements, convert, expandUmbrella, extractGrantFromPolicy, processGrants

Methods inherited from class java.security.Policy

getInstance, getInstance, getInstance, getParameters, getPolicy, getProvider, getType, setPolicy

Methods inherited from class java.lang.Object

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

Constructor Detail

DynamicPolicyProvider

public DynamicPolicyProvider()
                      throws PolicyInitializationException

Creates a new DynamicPolicyProvider instance that wraps a default underlying policy. The underlying policy is created as follows: if the net.jini.security.policy.DynamicPolicyProvider.basePolicyClass security property is set, then its value is interpreted as the class name of the base (underlying) policy provider; otherwise, a default class name of "net.jini.security.policy.PolicyFileProvider" is used. The base policy is then instantiated using the no-arg public constructor of the named class. If the base policy class is not found, is not instantiable via a public no-arg constructor, or if invocation of its constructor fails, then a PolicyInitializationException is thrown.

Note that this constructor requires the appropriate "getProperty" SecurityPermission to read the net.jini.security.policy.DynamicPolicyProvider.basePolicyClass security property, and may require "accessClassInPackage.*" RuntimePermissions, depending on the package of the base policy class.

Throws:

PolicyInitializationException - if unable to construct the base policy

SecurityException - if there is a security manager and the calling context does not have adequate permissions to read the net.jini.security.policy.DynamicPolicyProvider.basePolicyClass security property, or if the calling context does not have adequate permissions to access the base policy class

DynamicPolicyProvider

public DynamicPolicyProvider(Policy basePolicy)

Creates a new DynamicPolicyProvider instance that wraps around the given non-null base policy object.

Parameters:

basePolicy - base policy object containing information about non-dynamic grants

Throws:

NullPointerException - if basePolicy is null

Method Detail

revokeSupported

public boolean revokeSupported()

Description copied from interface: RevocablePolicy

Checks if policy supports revocation.

Specified by:

revokeSupported in interface RevocablePolicy

Returns:

true - If Revoke supported by underlying policy.

getPermissions

public PermissionCollection getPermissions(CodeSource codesource)

Overrides:

getPermissions in class Policy

getPermissions

public PermissionCollection getPermissions(ProtectionDomain domain)

Overrides:

getPermissions in class Policy

implies

public boolean implies(ProtectionDomain domain,
                       Permission permission)

Overrides:

implies in class Policy

refresh

public void refresh()

Calling refresh doesn't remove any dynamic grant's, it only clears the cache and refreshes the underlying Policy, it also removes any grants for ProtectionDomains that no longer exist. If a CachingSecurityManager has been set, this method will clear its cache.

Overrides:

refresh in class Policy

grantSupported

public boolean grantSupported()

Description copied from interface: DynamicPolicy

Returns true if this policy provider supports dynamic permission grants; returns false otherwise. Note that this method may return different values for a given DynamicPolicy instance, depending on context. For example, a policy provider that delegates to different underlying policy implementations depending on thread state would return true from this method when the current delegate supports dynamic permission grants, but return false when another delegate lacking such support is in effect.

Specified by:

grantSupported in interface DynamicPolicy

Returns:

true if policy supports dynamic permission grants under current context, false otherwise

grant

public void grant(Class cl,
                  Principal[] principals,
                  Permission[] permissions)

Description copied from interface: DynamicPolicy

If this security policy provider supports dynamic permission grants, grants the specified permissions to all protection domains (including ones not yet created) that are associated with the class loader of the given class and possess at least the given set of principals. If the given class is null, then the grant applies across all protection domains that possess at least the specified principals. If the list of principals is null or empty, then principals are effectively ignored in determining the protection domains to which the grant applies. If this policy provider does not support dynamic permission grants, then no permissions are granted and an UnsupportedOperationException is thrown.

The given class, if non-null, must belong to either the system domain or a protection domain whose associated class loader is non-null. If the class does not belong to such a protection domain, then no permissions are granted and an UnsupportedOperationException is thrown.

If a security manager is installed, its checkPermission method is called with a GrantPermission containing the permissions to grant; if the permission check fails, then no permissions are granted and the resulting SecurityException is thrown. The principals and permissions arrays passed in are neither modified nor retained; subsequent changes to the arrays have no effect on the grant operation.

Specified by:

grant in interface DynamicPolicy

Parameters:

cl - class to grant permissions to the class loader of, or null if granting across all class loaders

principals - if non-null, minimum set of principals to which grants apply

permissions - if non-null, permissions to grant

getGrants

public Permission[] getGrants(Class cl,
                              Principal[] principals)

Description copied from interface: DynamicPolicy

If this security policy provider supports dynamic permission grants, returns a new array containing the cumulative set of permissions dynamically granted to protection domains (including ones not yet created) that are associated with the class loader of the given class and possess at least the given set of principals. If the given class is null, then this method returns the cumulative set of permissions dynamically granted across all protection domains that possess at least the specified principals (i.e., through calls to the grant method where the specified class was null). If the list of principals is null or empty, then the permissions returned reflect only grants not qualified by principals (i.e., those performed through calls to the grant method where the specified principals array was null or empty). If this policy provider does not support dynamic permission grants, then an UnsupportedOperationException is thrown.

The given class, if non-null, must belong to either the system domain or a protection domain whose associated class loader is non-null. If the class does not belong to such a protection domain, then an UnsupportedOperationException is thrown.

Specified by:

getGrants in interface DynamicPolicy

Parameters:

cl - class to query the permissions dynamically granted to the class loader of, or null if querying permissions granted across all class loaders

principals - if non-null, principals to query dynamic grants for

Returns:

new array containing the permissions dynamically granted to the indicated class loader (if any) and principals

getPermissionGrants

public List<PermissionGrant> getPermissionGrants(ProtectionDomain domain)

Description copied from interface: ScalableNestedPolicy

Returns a new List containing immutable PermissionGrant's, the List returned is not synchronised and must not be shared with policy internal state. Only those PermissionGrant's that imply the domain will be returned. If any PermissionGrant's are privileged (contain AllPermission), then only that one PermissionGrant should be added to the collection. If a List has a size of 1, and contains only a privileged PermissionGrant, it enables the calling policy to determine the privileged state quickly. If a policy has a privileged PermissionGrant to add to a Collection, then the Collection must be cleared before the privileged PermissionGrant is added, so the Collection only contains the privileged PermissionGrant. The top level policy gathers all PermissionGrant's, retrieves all relevant permissions, then sorts them using a PermissionComparator, so Permission objects are added to a PermissionCollection in the most efficient order. If a nested base policy doesn't support ScalableNestedPolicy, then the implementer should create a PermissionGrant for the domain, containing the Permission objects returned from the policy. The first nested base policy (usually a file policy provider) is responsible for merging any static Permission objects from the ProtectionDomain.

Specified by:

getPermissionGrants in interface ScalableNestedPolicy

Parameters:

domain - ProtectionDomain grants apply to

Returns:

List of PermissionGrant's

grant

public boolean grant(PermissionGrant p)

Description copied from interface: RevocablePolicy

A dynamic grant. Caveat: Not all Permission's once granted can be revoked. When a Permission is checked, prior to passing a reference to a caller, that reference has escaped any further Permission checks, meaning that the Permission cannot be revoked for the caller holding a reference.

Specified by:

grant in interface RevocablePolicy

Parameters:

p - PermissionGrant to be granted.

Returns:

true if successful