Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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
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, or returns `false` because no trust verifier trusts the specified object
  `HANDLED` | trust verifier throws a `RemoteException` or a `SecurityException`
  `FINE` | trust verifier returns `true`
  `FINE` | creation of cached trust verifiers

Method Summary
`static Object` | `doPrivileged(PrivilegedAction action)` Executes the specified action's `run` method with privileges enabled, preserving the domain combiner (if any) of the calling context.
`static Object` | `doPrivileged(PrivilegedExceptionAction 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 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 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 Object doPrivileged(PrivilegedAction 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.

  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 Object doPrivileged(PrivilegedExceptionAction 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.

  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`

### 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)`

### 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 Sun Microsystems, Inc. All rights reserved