net.jini.security

Class Security

java.lang.Object

net.jini.security.Security

public final class Security
extends Object

Provides methods for executing actions with privileges enabled, for snapshotting security contexts, for verifying trust in proxies, for verifying codebase integrity, and for dynamically granting permissions. This class cannot be instantiated.

Since:

2.0

Author:

Sun Microsystems, Inc.

Implementation Specifics:

This implementation uses the Logger named net.jini.security.integrity to log information at the following levels:

Level	Description
FAILED	verifyCodebaseIntegrity throws a SecurityException because no integrity verifier verifies a URL
FINE	integrity verifier returns true
FINE	creation of cached integrity verifiers

This implementation uses the Logger named net.jini.security.policy to log information at the following level:

Level	Description
FINER	dynamic permission grants

This implementation uses the Logger named net.jini.security.trust to log information at the following levels:

Level	Description
FAILED	verifyObjectTrust throws a SecurityException because no trust verifier trusts the specified object
FAILED	TrustVerifier.Context.isTrustedObject throws an exception
HANDLED	trust verifier throws a RemoteException or a SecurityException
FINE	trust verifier returns true
FINE	creation of cached trust verifiers
FINE	TrustVerifier.Context.isTrustedObject returns false because no trust verifier trusts the specified object

Method Summary

Modifier and Type	Method and Description
static <T> T	doAs(Subject subject, PrivilegedAction<T> action) Performs work as a particular Subject in the presence of untrusted code, for distributed systems.
static <T> T	doAs(Subject subject, PrivilegedExceptionAction<T> action) Performs work as a particular Subject in the presence of untrusted code, for distributed systems.
static <T> T	doAsPrivileged(Subject subject, PrivilegedAction<T> action, SecurityContext context) Perform work as a particular Subject in the presence of untrusted code for distributed systems.
static <T> T	doAsPrivileged(Subject subject, PrivilegedExceptionAction<T> action, SecurityContext context) Perform work as a particular Subject in the presence of untrusted code for distributed systems.
static <T> T	doPrivileged(PrivilegedAction<T> action) Executes the specified action's run method with privileges enabled, preserving the domain combiner (if any) of the calling context.
static <T> T	doPrivileged(PrivilegedExceptionAction<T> action) Executes the specified action's run method with privileges enabled, preserving the domain combiner (if any) of the calling context.
static SecurityContext	getContext() Returns a snapshot of the current security context, which can be used to restore the context at a later time.
static void	grant(Class fromClass, Class toClass) If the installed security policy provider implements the DynamicPolicy interface, takes the set of permissions dynamically granted to the class loader of fromClass with the current subject's principals, determines which of those permissions the calling context is authorized to grant, and dynamically grants that subset of the permissions to the class loader of toClass, qualified with the current subject's principals.
static void	grant(Class cl, Permission[] permissions) If the installed security policy provider implements the DynamicPolicy interface, delegates to the security policy provider to grant 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 principals of the current subject (if any).
static void	grant(Class cl, Principal[] principals, Permission[] permissions) If the installed security policy provider implements the DynamicPolicy interface, delegates to the security policy provider to grant 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.
static void	grant(PermissionGrant grant)
static boolean	grantSupported() Returns true if the installed security policy provider supports dynamic permission grants--i.e., if it implements the DynamicPolicy interface and calling its grantSupported method returns true.
static boolean	revocationSupported() Returns true if the installed security policy provider supports dynamic revocable permission grants--i.e., if it implements the RevocablePolicy interface and calling its grantSupported method returns true.
static void	verifyCodebaseIntegrity(String codebase, ClassLoader loader) Verifies that the URLs in the specified codebase all provide content integrity, using verifiers from the specified class loader.
static void	verifyObjectTrust(Object obj, ClassLoader loader, Collection context) Verifies that the specified object can be trusted to correctly implement its contract, using verifiers from the specified class loader and using the specified collection of context objects as necessary.

Methods inherited from class java.lang.Object

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

Method Detail

verifyObjectTrust

public static void verifyObjectTrust(Object obj,
                                     ClassLoader loader,
                                     Collection context)
                              throws RemoteException

Verifies that the specified object can be trusted to correctly implement its contract, using verifiers from the specified class loader and using the specified collection of context objects as necessary. If a null class loader is specified, the context class loader of the current thread is used instead. Code that is itself downloaded and that carries its own trust verifiers (to trust other downloaded code) should specify an explicit class loader unless the calling code is known to be reachable from the context class loader.

A TrustVerifier.Context is created, containing an ordered list of trust verifiers (obtained as specified below) and the specified class loader and collection of context objects. The isTrustedObject method of that context is then called with the specified object. If that call returns true, then this method returns normally. If that call throws a RemoteException or SecurityException exception, that exception is thrown by this method. If that call returns false, a SecurityException is thrown.

The collection of context objects is provided as a means for the caller to communicate additional information to the trust verifiers. The meaning of an element in this collection is determined by its type. As a specific example, if any trust verifiers might communicate with a remote server (in particular, when verifying a proxy for a remote server), the caller might be responsible for specifying any necessary client constraints as a context object of type MethodConstraints.

When security is a concern, this method should be called with a downloaded proxy before making any other use of the proxy, in order to verify basic trust in the proxy to correctly implement its contract. This method can also be used to verify trust in other types of objects, depending on what verifiers have been configured. In general, verification of an object involves verification of all of its constituent objects. However, for objects that are instances of RemoteMethodControl, the client constraints (that would be returned by RemoteMethodControl.getConstraints) are not verified; it is assumed that the caller will either replace them or independently decide that it trusts them. Verification of other types of objects may similarly exempt certain application-controlled state.

The list of trust verifiers is obtained as follows. For each resource named META-INF/services/net.jini.security.TrustVerifier that is visible to the specified class loader, the contents of the resource are parsed as UTF-8 text to produce a list of class names. The resource must contain a list of fully qualified class names, one per line. Space and tab characters surrounding each name, as well as blank lines, are ignored. The comment character is '#'; all characters on each line starting with the first comment character are ignored. Each class name (that is not a duplicate of any previous class name) is loaded through the specified class loader, and the resulting class must be assignable to TrustVerifier and have a public no-argument constructor. The constructor is invoked to create a trust verifier instance. An implementation of this method is permitted to cache the verifier instances associated with a class loader, rather than recreating them on every call.

Parameters:

obj - the object in which to verify trust

loader - the class loader for finding trust verifiers, or null to use the context class loader

context - a collection of context objects for use by trust verifiers

Throws:

SecurityException - if the object is not trusted, or if a SecurityException is thrown by the trust verifier context

RemoteException - if a communication-related exception occurs

NullPointerException - if the collection is null

verifyCodebaseIntegrity

public static void verifyCodebaseIntegrity(String codebase,
                                           ClassLoader loader)
                                    throws MalformedURLException

Verifies that the URLs in the specified codebase all provide content integrity, using verifiers from the specified class loader. If a null class loader is specified, the context class loader of the current thread is used instead. An ordered list of integrity verifiers is obtained as specified below. For each URL (if any) in the specified codebase, the providesIntegrity method of each verifier is called (in order) with the URL. If any verifier call returns true, the URL is verified (and no further verifiers are called with that URL). If all of the verifier calls return false for a URL, this method throws a SecurityException. If all of the URLs are verified, this method returns normally.

The list of integrity verifiers is obtained as follows. For each resource named META-INF/services/net.jini.security.IntegrityVerifier that is visible to the specified class loader, the contents of the resource are parsed as UTF-8 text to produce a list of class names. The resource must contain a list of fully qualified class names, one per line. Space and tab characters surrounding each name, as well as blank lines, are ignored. The comment character is '#'; all characters on each line starting with the first comment character are ignored. Each class name (that is not a duplicate of any previous class name) is loaded through the specified class loader, and the resulting class must be assignable to IntegrityVerifier and have a public no-argument constructor. The constructor is invoked to create an integrity verifier instance. An implementation of this method is permitted to cache the verifier instances associated with a class loader, rather than recreating them on every call.

Parameters:

codebase - space-separated list of URLs, or null

loader - the class loader for finding integrity verifiers, or null to use the context class loader

Throws:

MalformedURLException - if the specified codebase contains an invalid URL

SecurityException - if any URL in the specified codebase does not provide content integrity

getContext

public static SecurityContext getContext()

Returns a snapshot of the current security context, which can be used to restore the context at a later time. If either the installed security manager or policy provider implements the SecurityContextSource interface, then this method delegates to the getContext method of the implementing object, with precedence given to the security manager. If neither the security manager nor the policy provider implement SecurityContextSource, then a new default SecurityContext instance is returned whose methods have the following semantics:

• The wrap methods each return their respective PrivilegedAction and PrivilegedExceptionAction arguments, unmodified
• The getAccessControlContext method returns the AccessControlContext in effect when the security context was created

Returns:

snapshot of the current security context

doPrivileged

public static <T> T doPrivileged(PrivilegedAction<T> action)

Executes the specified action's run method with privileges enabled, preserving the domain combiner (if any) of the calling context. If the action's run method throws an unchecked exception, that exception is thrown by this method. This method is equivalent to the AccessController.doPrivileged method of the same signature, except that it maintains, instead of clears, the domain combiner (if any) in place at the time of the call. This typically results in preservation of the current Subject (if the combiner is a SubjectDomainCombiner), thus retaining permissions granted to principals of the Subject, as well as the ability to use credentials of the Subject for authentication.

Type Parameters:

T - type of object result from PrivilegedAction

Parameters:

action - the action to be executed

Returns:

the object returned by the action's run method

Throws:

NullPointerException - if the action is null

doPrivileged

public static <T> T doPrivileged(PrivilegedExceptionAction<T> action)
                          throws PrivilegedActionException

Executes the specified action's run method with privileges enabled, preserving the domain combiner (if any) of the calling context. If the action's run method throws an unchecked exception, that exception is thrown by this method. This method is equivalent to the AccessController.doPrivileged method of the same signature, except that it maintains, instead of clears, the domain combiner (if any) in place at the time of the call. This typically results in preservation of the current Subject (if the combiner is a SubjectDomainCombiner), thus retaining permissions granted to principals of the Subject, as well as the ability to use credentials of the Subject for authentication.

Type Parameters:

T - type of object result from PrivilegedExceptionAction

Parameters:

action - the action to be executed

Returns:

the object returned by the action's run method

Throws:

PrivilegedActionException - if the action's run method throws a checked exception

NullPointerException - if the action is null

doAs

public static <T> T doAs(Subject subject,
                         PrivilegedAction<T> action)

Performs work as a particular Subject in the presence of untrusted code, for distributed systems.

This method retrieves the current Threads AccessControlContext and using a SubjectDomainCombiner subclass, prepends a new ProtectionDomain implementing SubjectDomain, containing the Principals of the Subject, a CodeSource with a null URL and null Certificate array, with no Permission and a null ClassLoader.

Unlike Subject.doAs, existing ProtectionDomains are not replaced unless they implement SubjectDomain.

Policy grants to Principals only are implied when run as the Subject, combinations of Principal, CodeSource URL and Certificates never imply this Subjects Principals as it is treated independently of CodeSource policy grants, nor do any such grants imply any of the ProtectionDomains that represent code on the call stack, since these ProtectionDomains are never replaced with ProtectionDomains containing the Subject Principals.

The SubjectDomainCombiner used treats CodeSource and Principal grants as separate concerns.

If a policy provider is installed that recognises SubjectDomain, then Subjects who's principals are mutated are effective immediately.

No AuthPermission is required to call this method, it cannot elevate privileges, only reduce them to those determined by a policy for a particular Subject.

Type Parameters:

T - type of object result from PrivilegedAction

Parameters:

subject - The Subject the work will be performed as, may be null.

action - The code to be run as the Subject.

Returns:

The value returned by the PrivilegedAction's run() method.

Throws:

NullPointerException - if action is null;

Since:

3.0.0

doAs

public static <T> T doAs(Subject subject,
                         PrivilegedExceptionAction<T> action)
                  throws PrivilegedActionException

Performs work as a particular Subject in the presence of untrusted code, for distributed systems.

This method retrieves the current Thread AccessControlContext and using a SubjectDomainCombiner subclass, prepends a new ProtectionDomain implementing SubjectDomain, containing the Principals of the Subject, a CodeSource with a null URL and null Certificate array, with no Permission and a null ClassLoader.

Unlike Subject.doAs, existing ProtectionDomains are not replaced unless they implement SubjectDomain.

Policy grants to Principals only are implied when run as the Subject, combinations of Principal, CodeSource URL and Certificate grants never imply this Subjects Principals as it is treated independently of CodeSource policy grants, nor do any such grants imply any of the ProtectionDomains that represent code on the call stack, since these ProtectionDomains are never replaced with ProtectionDomains containing the Subject Principals.

The SubjectDomainCombiner subclass used treats CodeSource and Principal grants as separate concerns.

The SubjectDomainCombiner subclass implementation is package private and can only be accessed through SubjectDomainCombiner public methods.

If a policy provider is installed that recognizes SubjectDomain, then Subjects who's principals are mutated are effective immediately.

No AuthPermission is required to call this method, it cannot elevate privileges, only reduce them to those determined by a policy for a particular Subject.

Type Parameters:

T - type of object result from PrivilegedExceptionAction

Parameters:

subject - The Subject the work will be performed as, may be null.

action - The code to be run as the Subject.

Returns:

The value returned by the PrivilegedAction's run() method.

Throws:

NullPointerException - if action is null;

PrivilegedActionException - if the specified action's run method throws a check exception.

Since:

3.0.0

doAsPrivileged

public static <T> T doAsPrivileged(Subject subject,
                                   PrivilegedAction<T> action,
                                   SecurityContext context)

Perform work as a particular Subject in the presence of untrusted code for distributed systems. This method behaves exactly as Security.doAs, except that instead of retrieving the current Threads AccessControlContext, it uses the provided SecurityContext. If the provided SecurityContext is null this method instantiates a new AccessControlContext with an empty array of ProtectionDomains. Unlike Security.doAs which doesn't require any privileges, this method requires the same Permission as Subject.doAsPrivileged to execute.

Type Parameters:

T - type of object result from PrivilegedAction

Parameters:

subject - The Subject the work will be performed as, may be null.

action - The code to be run as the Subject.

context - The SecurityContext to be tied to the specific action and subject.

Returns:

The value returned by the PrivilegedAction's run() method.

Throws:

NullPointerException - if the specified PrivilegedExceptionAction is null.

SecurityException - if the caller doesn't have permission to call this method.

doAsPrivileged

public static <T> T doAsPrivileged(Subject subject,
                                   PrivilegedExceptionAction<T> action,
                                   SecurityContext context)
                            throws PrivilegedActionException

Perform work as a particular Subject in the presence of untrusted code for distributed systems. This method behaves exactly as Security.doAs, except that instead of retrieving the current Threads AccessControlContext, it uses the provided SecurityContext. If the provided SecurityContext is null this method instantiates a new AccessControlContext with an empty array of ProtectionDomains. Unlike Security.doAs which doesn't require any privileges, this method requires the same Permission as Subject.doAsPrivileged to execute.

Type Parameters:

T - type of object result from PrivilegedExceptionAction

Parameters:

subject - The Subject the work will be performed as, may be null.

action - The code to be run as the Subject.

context - The SecurityContext to be tied to the specific action and subject.

Returns:

The value returned by the PrivilegedAction's run() method.

Throws:

NullPointerException - if the specified PrivilegedExceptionAction is null.

SecurityException - if the caller doesn't have permission to call this method.

PrivilegedActionException - if the PrivilegedActionException.run method throws a checked exception.

grantSupported

public static boolean grantSupported()

Returns true if the installed security policy provider supports dynamic permission grants--i.e., if it implements the DynamicPolicy interface and calling its grantSupported method returns true. Returns false otherwise.

Returns:

true if the installed security policy provider supports dynamic permission grants

See Also:

grant(Class,Permission[]), grant(Class,Principal[],Permission[]), grant(Class,Class)

revocationSupported

public static boolean revocationSupported()

Returns true if the installed security policy provider supports dynamic revocable permission grants--i.e., if it implements the RevocablePolicy interface and calling its grantSupported method returns true. Returns false otherwise.

Returns:

true if the installed security policy provider supports dynamic permission grants

See Also:

grant(Class,Permission[]), grant(Class,Principal[],Permission[]), grant(Class,Class)

grant

public static void grant(PermissionGrant grant)

grant

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

If the installed security policy provider implements the DynamicPolicy interface, delegates to the security policy provider to grant 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 principals of the current subject (if any). If the given class is null, then the grant applies across all protection domains that possess at least the current subject's principals. The current subject is determined by calling Subject.getSubject on the context returned by AccessController.getContext. If the current subject is null or has no principals, then principals are effectively ignored in determining the protection domains to which the grant applies.

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 permissions array passed in is neither modified nor retained; subsequent changes to the array have no effect on the grant operation.

Parameters:

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

permissions - if non-null, permissions to grant

Throws:

UnsupportedOperationException - if the installed security policy provider does not support dynamic permission grants, or if cl is non-null and belongs to a protection domain other than the system domain with an associated class loader of null

SecurityException - if a security manager is installed and the calling context does not have GrantPermission for the given permissions

NullPointerException - if any element of the permissions array is null

See Also:

grantSupported(), DynamicPolicy.grant(Class,Principal[],Permission[])

grant

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

If the installed security policy provider implements the DynamicPolicy interface, delegates to the security policy provider to grant 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.

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.

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

Throws:

UnsupportedOperationException - if the installed security policy provider does not support dynamic permission grants, or if cl is non-null and belongs to a protection domain other than the system domain with an associated class loader of null

SecurityException - if a security manager is installed and the calling context does not have GrantPermission for the given permissions

NullPointerException - if any element of the principals or permissions arrays is null

See Also:

grantSupported(), DynamicPolicy.grant(Class,Principal[],Permission[])

grant

public static void grant(Class fromClass,
                         Class toClass)

If the installed security policy provider implements the DynamicPolicy interface, takes the set of permissions dynamically granted to the class loader of fromClass with the current subject's principals, determines which of those permissions the calling context is authorized to grant, and dynamically grants that subset of the permissions to the class loader of toClass, qualified with the current subject's principals. The current subject is determined by calling Subject.getSubject on the context returned by AccessController.getContext; the permissions dynamically granted to fromClass are determined by calling the getGrants method of the currently installed policy, and the permission grant to toClass is performed by invoking the grant method of the current policy.

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

Parameters:

fromClass - class indicating the source class loader of the dynamic grants to propagate

toClass - class indicating the target class loader of the dynamic grants to propagate

Throws:

NullPointerException - if fromClass or toClass is null

UnsupportedOperationException - if currently installed policy does not support dynamic permission grants, or if either specified class belongs to a protection domain with a null class loader, other than the system domain