org.apache.river.api.security

Class ConcurrentPolicyFile

java.lang.Object

java.security.Policy

org.apache.river.api.security.ConcurrentPolicyFile

All Implemented Interfaces:

ScalableNestedPolicy

public class ConcurrentPolicyFile
extends Policy
implements ScalableNestedPolicy

Concurrent Policy implementation based on policy configuration URL's, it is intended to provide concurrent implies() for greatly improved throughput. Caching limits scalability and consumes shared memory, so no cache exists.

By default all River Policy implementations now utilise ConcurrentPolicyFile.

The default PolicyParser implementation recognises text files, consisting of clauses with the following syntax:

 keystore "some_keystore_url" [, "keystore_type"];
 

 grant [SignedBy "signer_names"] [, CodeBase "URL"]
  [, Principal [principal_class_name] "principal_name"]
  [, Principal [principal_class_name] "principal_name"] ... {
  permission permission_class_name [ "target_name" ] [, "action"] 
  [, SignedBy "signer_names"];
  permission ...
  };
  
 

The keystore clause specifies reference to a keystore, which is a database of private keys and their associated digital certificates. The keystore is used to look up the certificates of signers specified in the grant entries of the file. The policy file can contain any number of keystore entries which can appear at any ordinal position. However, only the first successfully loaded keystore is used, others are ignored. The keystore must be specified if some grant clause refers to a certificate's alias.
The grant clause associates a CodeSource (consisting of a URI and a set of certificates) of some executable code with a set of Permissions which should be granted to the code. So, the CodeSource is defined by values of CodeBase and SignedBy fields. The CodeBase value must be in URI format, while SignedBy value is a (comma-separated list of) alias(es) to keystore certificates. These fields can be omitted to denote any codebase and any signers (including case of unsigned code), respectively.
URI is case sensitive and does not perform DNS lookup or reverse lookup to resolve a URI IP address to determine if a grant clause implies CodeSource URL, instead CodeSource URL objects are converted to URI instances during implies determination. If grants are made to an IP address, these will not imply a DNS name address URI and vice versa.
"FILE:" URI's are case sensitive, although some file systems allow access to the same file using upper or lower case, one URI will not imply another with different case, even if both URI refer to the same file, for this reason case sensitive and case preserving file systems are recommended. The PolicyParser must escape any excluded characters according to RFC2396 and in addition it must convert all MS Windows platform drive letters to upper case.
Also, the code may be required to be executed on behalf of some Principals (in other words, code's ProtectionDomain must have the array of Principals associated) in order to possess the Permissions. This fact is indicated by specifying one or more Principal fields in the grant clause. Each Principal is specified as class/name pair; name and class can be either concrete value or wildcard * . As a special case, the class value may be omitted and then the name is treated as an alias to X.509 Certificate, and the Principal is assumed to be javax.security.auth.x500.X500Principal with a name of subject's distinguished name from the certificate.
The order between the CodeBase , SignedBy , and Principal fields does not matter. The policy file can contain any number of grant clauses.
Each grant clause must contain one or more permission entry. The permission entry consist of a fully qualified class name along with optional name , actions and signedby values. Name and actions are arguments to the corresponding constructor of the permission class. SignedBy value represents the keystore alias(es) to certificate(s) used to sign the permission class. That is, this permission entry is effective (i.e., access control permission will be granted based on this entry) only if the bytecode implementation of permission class is verified to be correctly signed by the said alias(es).

The policy content may be parameterized via property expansion. Namely, expressions like ${key} are replaced by values of corresponding system properties. Also, the special slash key (i.e. ${/}) is supported, it is a shortcut to "file.separator" key. Property expansion is performed anywhere a double quoted string is allowed in the policy file. However, this feature is controlled by security properties and should be turned on by setting "policy.expandProperties" property to true .
If property expansion fails (due to a missing key), a corresponding entry is ignored. For fields of keystore and grant clauses, the whole clause is ignored, and for permission entry, only that entry is ignored.

The policy also supports generalized expansion in permissions names, of expressions like ${{protocol:data}} . Currently the following protocols supported:

self

Denotes substitution to a principal information of the parental Grant entry. Replaced by a space-separated list of resolved Principals (including wildcarded), each formatted as class "name" . If parental Grant entry has no Principals, the permission is ignored.

alias: name

Denotes substitution of a KeyStore alias. Namely, if a KeyStore has an X.509 certificate associated with the specified name, then replaced by javax.security.auth.x500.X500Principal " DN " string, where DN is a certificate's subject distinguished name.

If there is sufficient interest, we can implement a DENY clause, in this case DENY cannot apply to GRANT clauses that contain AllPermission, the domains to which a DENY clause would apply will be a less privileged domain. For example a user could be granted SocketPermission("*", "connect"), while a DENY clause might list specific SocketPermission domains that are disallowed, where a DENY clause has precedence over all GRANT clause Permissions except for AllPermission.
This implementation is thread-safe and scalable.

Since:

2.2.1

Author:

Peter Firmstone.

Nested Class Summary

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

Policy.Parameters

Field Summary

Fields inherited from class java.security.Policy

UNSUPPORTED_EMPTY_COLLECTION

Constructor Summary

Constructors

Modifier	Constructor and Description
	ConcurrentPolicyFile() Default constructor, equivalent to ConcurrentPolicyFile(new DefaultPolicyParser()).
protected	ConcurrentPolicyFile(PolicyParser dpr, Comparator<Permission> comp)

Method Summary

Modifier and Type	Method and Description
List<PermissionGrant>	getPermissionGrants(ProtectionDomain pd) 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 cs) This returns a java.security.Permissions collection, which allows ProtectionDomain to optimise for the AllPermission case, which avoids unnecessarily consulting the policy.
PermissionCollection	getPermissions(ProtectionDomain pd) Returns collection of permissions allowed for the domain according to the policy.
boolean	implies(ProtectionDomain domain, Permission permission)
void	refresh() Gets fresh list of locations and tries to load all of them in sequence; failed loads are ignored.

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

ConcurrentPolicyFile

public ConcurrentPolicyFile()
                     throws PolicyInitializationException

Default constructor, equivalent to ConcurrentPolicyFile(new DefaultPolicyParser()).

Throws:

PolicyInitializationException - in instantiation unsuccessful

ConcurrentPolicyFile

protected ConcurrentPolicyFile(PolicyParser dpr,
                               Comparator<Permission> comp)
                        throws PolicyInitializationException

Throws:

PolicyInitializationException

Method Detail

getPermissions

public PermissionCollection getPermissions(ProtectionDomain pd)

Returns collection of permissions allowed for the domain according to the policy. The evaluated characteristics of the domain are it's codesource and principals; they are assumed to be null if the domain is null. Each PermissionCollection returned is a unique instance.

Overrides:

getPermissions in class Policy

Parameters:

pd - ProtectionDomain

See Also:

ProtectionDomain

getPermissions

public PermissionCollection getPermissions(CodeSource cs)

This returns a java.security.Permissions collection, which allows ProtectionDomain to optimise for the AllPermission case, which avoids unnecessarily consulting the policy. This implementation only returns a Permissions that contains AllPermission for privileged domains, otherwise it calls super.getPermissions(cs).

Overrides:

getPermissions in class Policy

Parameters:

cs - CodeSource

See Also:

CodeSource

implies

public boolean implies(ProtectionDomain domain,
                       Permission permission)

Overrides:

implies in class Policy

refresh

public void refresh()

Gets fresh list of locations and tries to load all of them in sequence; failed loads are ignored. After processing all locations, old policy settings are discarded and new ones come into force.

Overrides:

refresh in class Policy

See Also:

PolicyUtils.getPolicyURLs(Properties, String, String)

getPermissionGrants

public List<PermissionGrant> getPermissionGrants(ProtectionDomain pd)

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:

pd - ProtectionDomain grants apply to

Returns:

List of PermissionGrant's