org.apache.river.api.security

Class PermissionGrantBuilder

java.lang.Object

org.apache.river.api.security.PermissionGrantBuilder

public abstract class PermissionGrantBuilder
extends Object

The PermissionGrantBuilder creates Dynamic PermissionGrant's based on information provided by the user. The user must have access to the system policy and have permission to grant permissions. A PermissionGrantBuilder implementation should also be used as the serialized form for PermissionGrant's, the implementation of PermissionGrant's should remain package private. This prevents the serialized form becoming part of the public api. Single Thread use only.

Since:

3.0.0

Author:

Peter Firmstone.

See Also:

PermissionGrant

Field Summary

Fields

Modifier and Type	Field and Description
static int	CLASSLOADER The PermissionGrant generated will apply to all classes loaded by the ClassLoader
static int	CODESOURCE_CERTS The PermissionGrant generated will apply to all classes loaded from CodeSource's that have at a minimum the defined array Certificate[] provided the logged in Subject also has all Principals when defined.
static int	PRINCIPAL The PermissionGrant generated will apply to the Subject that has all the principals provided.
static int	PROTECTIONDOMAIN The PermissionGrant generated will apply to all classes belonging to the ProtectionDomain.
static int	URI The PermissionGrant generated will imply the ProtectionDomain run as a Subject with all Principals (when applicable) and CodeSource that has the Certificates and URI RFC3986 location as specified.

Constructor Summary

Constructors

Constructor and Description
PermissionGrantBuilder()

Method Summary

Modifier and Type	Method and Description
abstract PermissionGrant	build() Build the PermissionGrant using information supplied.
abstract PermissionGrantBuilder	certificates(Certificate[] certs) Sets the Certificate[] a CodeSource must have to receive the PermissionGrant.
abstract PermissionGrantBuilder	certificates(Certificate[] certs, String[] aliases) Sets the Certificate[] a CodeSource must have to receive the PermissionGrant.
abstract PermissionGrantBuilder	clazz(Class cl) Extracts ProtectionDomain from the Class for use in the PermissionGrantBuilder.
abstract PermissionGrantBuilder	context(int context) Sets the context of the PermissionGrant to on of the static final fields in this class.
static PermissionGrantBuilder	newBuilder()
abstract PermissionGrantBuilder	permissions(Permission[] perm) Specifies Permission's to be granted.
abstract PermissionGrantBuilder	principals(Principal[] pals) Sets the Principal[] that a Subject must have to be entitled to receive the PermissionGrant.
abstract PermissionGrantBuilder	reset() resets the state for reuse, identical to a newly created PermissionGrantBuilder, this step must be performed to avoid unintentional grants to previously added URI.
abstract PermissionGrantBuilder	setDomain(WeakReference<ProtectionDomain> domain)
abstract PermissionGrantBuilder	uri(String path) The URI will be added to the PermissionGrant, multiple may be specified by calling multiple times.

Methods inherited from class java.lang.Object

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

Field Detail

CLASSLOADER

public static final int CLASSLOADER

The PermissionGrant generated will apply to all classes loaded by the ClassLoader

See Also:

Constant Field Values

PROTECTIONDOMAIN

public static final int PROTECTIONDOMAIN

The PermissionGrant generated will apply to all classes belonging to the ProtectionDomain. This is actually a simplification for the programmer the PermissionGrant will apply to the CodeSource and the ClassLoader combination, the reason for this is the DomainCombiner may create new instances of ProtectionDomain's from those that exist on the stack.

DNS is not consulted, the RFC3986 normalized URI and all Certificates contained by the CodeSources must be equal.

See Also:

AccessControlContext, DomainCombiner, SubjectDomainCombiner, Constant Field Values

PRINCIPAL

public static final int PRINCIPAL

The PermissionGrant generated will apply to the Subject that has all the principals provided.

See Also:

Subject, Constant Field Values

CODESOURCE_CERTS

public static final int CODESOURCE_CERTS

The PermissionGrant generated will apply to all classes loaded from CodeSource's that have at a minimum the defined array Certificate[] provided the logged in Subject also has all Principals when defined.

See Also:

Constant Field Values

URI

public static final int URI

The PermissionGrant generated will imply the ProtectionDomain run as a Subject with all Principals (when applicable) and CodeSource that has the Certificates and URI RFC3986 location as specified.

The outcome of URI comparison is similar to CodeSource.implies(CodeSource).

DNS lookup is avoided for security and performance reasons, DNS is not authenticated and therefore cannot be trusted. Doing so, could allow an attacker to use DNS Cache poisoning to escalate Permission, by imitating a URL with privilege, such as AllPermission.

CodeSource URL are converted to URI and normalized according to RFC3986 before being compared as Strings.

A URI based PermissionGrant "implies" a specified ProtectionDomain if:

1. The ProtectionDomain's CodeSource is not null.
2. All Principal's, if defined in the PermissionGrant are present in the ProtectionDomain, when run as a Subject, in any order.
3. A URI based PermissionGrant "implies" a specified ProtectionDomain or non null CodeSource if:
   1. All Certificate's included in a URI based PermissionGrant are present in that ProtectionDomain's CodeSource's certificates, in any order, or no Certificates are defined by the PermissionGrant.
   2. For any URI in a PermissionGrant, checks are made in the following order:
      1. Any null URI implies any ProtectionDomain that contains a non null CodeSource, including a null URL returned by CodeSource.getLocation().
      2. If any RFC3986 normalized URI equals the ProtectionDomain's CodeSource.getLocation()'s URL after it is converted to a RFC3986 normalized URI, the PermissionGrant.implies(java.security.ProtectionDomain) method will return true.
      3. The CodeSource.getLocation()'s URL is checked against each URI contained in a PermissionGrant and returns true if all the following conditions are met for at least one URI:
         1. The URI.getScheme() scheme must be equal to a CodeSource's URL.getProtocol() protocol, after normalization to RFC3986 rules.
         2. If URI.getHost() is non null, and URL.getHost() is equal after RFC3986 compliant normalization performed.
         3. If the URI.getPort() port is not equal to -1 (that is, if a port is specified), it must equal the CodeSource URL's port.
         4. URI and URL path's are normalized to RFC3986, in addition file: scheme paths are normalized to upper case, on platforms with a backslash path separator.
         5. After normalization, if this URI.getPath() path doesn't equal codesource's URL.getPath() path, then the following checks are made: If this URI's path ends with "/-", then codesource's URL path must start with this URI's path (exclusive the trailing "-"). If this URI's path ends with a "/*", then codesource's URL path must start with this URI's path and must not have any further "/" separators. If this URI's path doesn't end with a "/", then codesource's URL path must match this URI's path with a '/' appended.
         6. If this URI.getFragment() fragment is not null, it must equal codesource's URL.getRef() reference.
         7. Unlike CodeSource.implies(java.security.CodeSource) URI.getQuery() query is not appended to the path because normalization to specific platforms is undefined. It appears that URL was developed prior to RFC2396 and as such the URL.getFile() included the query component, later in Java 1.3 the URL.getPath() method was added, however earlier developed classes like URLClassLoader continued to use URL.getFile() and append this with path separators and wild cards after the query, if it existed. In any case, Certificate and Principal are more prudent identifiers for privileges.

See Also:

Constant Field Values

Constructor Detail

PermissionGrantBuilder

public PermissionGrantBuilder()

Method Detail

newBuilder

public static PermissionGrantBuilder newBuilder()

reset

public abstract PermissionGrantBuilder reset()

resets the state for reuse, identical to a newly created PermissionGrantBuilder, this step must be performed to avoid unintentional grants to previously added URI.

Returns:

PermissionGrantBuilder

context

public abstract PermissionGrantBuilder context(int context)
                                        throws IllegalStateException

Sets the context of the PermissionGrant to on of the static final fields in this class.

Parameters:

context - value of a static field defined in this builder.

Returns:

PermissionGrantBuilder

Throws:

IllegalStateException - if context out of range of static fields defined in this builder.

uri

public abstract PermissionGrantBuilder uri(String path)

The URI will be added to the PermissionGrant, multiple may be specified by calling multiple times.

Parameters:

path - - RFC3986 compliant URI or null.

Returns:

PermissinoGrantBuilder

clazz

public abstract PermissionGrantBuilder clazz(Class cl)

Extracts ProtectionDomain from the Class for use in the PermissionGrantBuilder. The ClassLoader and ProtectionDomain are weakly referenced, when collected any created PermissionGrant affected will be voided.

Parameters:

cl - Class used to determine the ProtectionDomain to be used for PermissionGrant.

Returns:

PermissionGrantBuilder.

certificates

public abstract PermissionGrantBuilder certificates(Certificate[] certs)

Sets the Certificate[] a CodeSource must have to receive the PermissionGrant.

Parameters:

certs - Certificates

Returns:

a PermissionGrantBuilder

certificates

public abstract PermissionGrantBuilder certificates(Certificate[] certs,
                                                    String[] aliases)

Sets the Certificate[] a CodeSource must have to receive the PermissionGrant.

Parameters:

certs - Certificates

aliases - of certificates.

Returns:

a PermissionGrantBuilder

principals

public abstract PermissionGrantBuilder principals(Principal[] pals)

Sets the Principal[] that a Subject must have to be entitled to receive the PermissionGrant.

Parameters:

pals - Principals.

Returns:

a PermissionGrantBuilder

permissions

public abstract PermissionGrantBuilder permissions(Permission[] perm)

Specifies Permission's to be granted.

Parameters:

perm - Permissions.

Returns:

a PermissionGrantBuilder

build

public abstract PermissionGrant build()

Build the PermissionGrant using information supplied.

Returns:

an appropriate PermissionGrant.

setDomain

public abstract PermissionGrantBuilder setDomain(WeakReference<ProtectionDomain> domain)

Parameters:

domain - WeakReference containing ProtectionDomain

Returns:

a PermissionGrantBuilder