net.jini.security
Class VerifyingProxyPreparer

java.lang.Object
  extended by net.jini.security.VerifyingProxyPreparer
All Implemented Interfaces:
ProxyPreparer

public final class VerifyingProxyPreparer
extends Object
implements ProxyPreparer

A ProxyPreparer for verifying that proxies are trusted, dynamically granting permissions to trusted proxies, and optionally setting the client constraints on trusted proxies.

Since:
2.1
Author:
Sun Microsystems, Inc.

Field Summary
private static int ADD_CONSTRAINTS
          Add proxy's constraints to context.
private static int AS_IS
          No change to proxy or context.
private  Object[] contextElements
          Trust verifier context elements.
private  ClassLoader loader
          Class loader to pass to verifyObjectTrust.
private  Permission[] permissions
          Permissions to dynamically grant.
private  Principal[] principals
          Principals to scope the permission grant, if any.
private static int SET_CONSTRAINTS
          Set constraints on proxy from context.
private  int type
          SET_CONSTRAINTS, AS_IS, or ADD_CONSTRAINTS.
 
Constructor Summary
VerifyingProxyPreparer(boolean addProxyConstraints, ClassLoader loader, Object[] contextElements, Principal[] principals, Permission[] permissions)
          Creates a proxy preparer that verifies proxies using the specified class loader and trust verifier context elements (optionally with the proxy's client constraints as an additional context element), dynamically grants the specified permissions to trusted proxies for the specified principals, and returns trusted proxies with their original client constraints intact.
VerifyingProxyPreparer(ClassLoader loader, Object[] contextElements, Principal[] principals, Permission[] permissions)
          Creates a proxy preparer that verifies proxies using the specified class loader and trust verifier context elements, dynamically grants the specified permissions to trusted proxies for the specified principals, and returns trusted proxies with their client constraints set to the constraints specified as a trust verifier context element.
VerifyingProxyPreparer(Object[] contextElements, Permission[] permissions)
          Creates a proxy preparer that verifies proxies using the context class loader and specified trust verifier context elements, dynamically grants the specified permissions to trusted proxies for the principals of the preparing thread's subject, and returns trusted proxies with their client constraints set to the constraints specified as a trust verifier context element.
 
Method Summary
private static Permission[] checkPermissions(Permission[] permissions)
          Clones the argument, checks for null elements, returns non-null.
private static Principal[] checkPrincipals(Principal[] principals)
          Clones the argument, checks for null elements.
 boolean equals(Object obj)
          Returns true if the specified object and this object are both instances of this class that were constructed with equivalent arguments.
 int hashCode()
          Returns a hash code value for this object.
 Object prepareProxy(Object proxy)
          Performs operations on a proxy to prepare it for use, returning the prepared proxy, which may or may not be the argument itself.
 String toString()
          Returns a string representation of this object.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

SET_CONSTRAINTS

private static final int SET_CONSTRAINTS
Set constraints on proxy from context.

See Also:
Constant Field Values

AS_IS

private static final int AS_IS
No change to proxy or context.

See Also:
Constant Field Values

ADD_CONSTRAINTS

private static final int ADD_CONSTRAINTS
Add proxy's constraints to context.

See Also:
Constant Field Values

type

private final int type
SET_CONSTRAINTS, AS_IS, or ADD_CONSTRAINTS.


loader

private final ClassLoader loader
Class loader to pass to verifyObjectTrust.


contextElements

private final Object[] contextElements
Trust verifier context elements.


principals

private final Principal[] principals
Principals to scope the permission grant, if any.


permissions

private final Permission[] permissions
Permissions to dynamically grant.

Constructor Detail

VerifyingProxyPreparer

public VerifyingProxyPreparer(Object[] contextElements,
                              Permission[] permissions)
Creates a proxy preparer that verifies proxies using the context class loader and specified trust verifier context elements, dynamically grants the specified permissions to trusted proxies for the principals of the preparing thread's subject, and returns trusted proxies with their client constraints set to the constraints specified as a trust verifier context element. The arrays passed to this constructor are neither modified nor retained; subsequent changes to the arrays have no effect on the instance created.

Parameters:
contextElements - the trust verifier context elements
permissions - the permissions to dynamically grant, or null if no permissions should be granted
Throws:
NullPointerException - if contextElements is null or any element of permissions is null
IllegalArgumentException - if no element of contextElements is an instance of MethodConstraints

VerifyingProxyPreparer

public VerifyingProxyPreparer(ClassLoader loader,
                              Object[] contextElements,
                              Principal[] principals,
                              Permission[] permissions)
Creates a proxy preparer that verifies proxies using the specified class loader and trust verifier context elements, dynamically grants the specified permissions to trusted proxies for the specified principals, and returns trusted proxies with their client constraints set to the constraints specified as a trust verifier context element. The arrays passed to this constructor are neither modified nor retained; subsequent changes to the arrays have no effect on the instance created.

Parameters:
loader - the class loader for finding trust verifiers, or null to use the context class loader
contextElements - the trust verifier context elements
principals - minimum set of principals to which grants apply, or null to use the principals of the preparing thread's subject
permissions - the permissions to dynamically grant, or null if no permissions should be granted
Throws:
NullPointerException - if contextElements is null or any element of principals or permissions is null
IllegalArgumentException - if no element of contextElements is an instance of MethodConstraints

VerifyingProxyPreparer

public VerifyingProxyPreparer(boolean addProxyConstraints,
                              ClassLoader loader,
                              Object[] contextElements,
                              Principal[] principals,
                              Permission[] permissions)
Creates a proxy preparer that verifies proxies using the specified class loader and trust verifier context elements (optionally with the proxy's client constraints as an additional context element), dynamically grants the specified permissions to trusted proxies for the specified principals, and returns trusted proxies with their original client constraints intact. The arrays passed to this constructor are neither modified nor retained; subsequent changes to the arrays have no effect on the instance created.

Parameters:
addProxyConstraints - true if the proxy's client constraints should be included as a trust verifier context element, false otherwise
loader - the class loader for finding trust verifiers, or null to use the context class loader
contextElements - the trust verifier context elements, or null if no elements need to be supplied
principals - minimum set of principals to which grants apply, or null to use the principals of the preparing thread's subject
permissions - the permissions to dynamically grant, or null if no permissions should be granted
Throws:
NullPointerException - if any element of principals or permissions is null
Method Detail

checkPermissions

private static Permission[] checkPermissions(Permission[] permissions)
Clones the argument, checks for null elements, returns non-null.


checkPrincipals

private static Principal[] checkPrincipals(Principal[] principals)
Clones the argument, checks for null elements.


prepareProxy

public Object prepareProxy(Object proxy)
                    throws RemoteException
Performs operations on a proxy to prepare it for use, returning the prepared proxy, which may or may not be the argument itself.

If this preparer was created using the two-argument or four-argument constructor, or using the five-argument constructor with addProxyConstraints set to true, and if the specified proxy is not an instance of RemoteMethodControl, then a SecurityException is thrown. Otherwise, Security.verifyObjectTrust is invoked with the specified proxy, the class loader that was passed to the constructor of this preparer (or null if the two-argument constructor was used), and a trust verifier context collection containing all of the context elements that were passed to the constructor of this preparer. If this preparer was created using the five-arguent constructor with addProxyConstraints set to true, then the proxy's client constraints (obtained by calling getConstraints on the proxy) are included as an additional context element. Any exception thrown by verifyObjectTrust is thrown by this method. If this preparer was created with a non-null array of principals and one or more permissions, then Security.grant is invoked with the proxy's class and those principals and permissions. If this preparer was created with no array of principals (either null was specified or the two-argument constructor was used) but one or more permissions, then Security.grant is invoked with the proxy's class and those permissions. In either case, if grant throws an UnsupportedOperationException, this method throws a SecurityException. Finally, if this preparer was created using the five-argument constructor, then the original proxy is returned, otherwise what is returned is the result of calling RemoteMethodControl.setConstraints on the proxy, passing the first trust verifier context element that is an instance of MethodConstraints.

Specified by:
prepareProxy in interface ProxyPreparer
Parameters:
proxy - the proxy to prepare
Returns:
the prepared proxy
Throws:
NullPointerException - if proxy is null
RemoteException - if a communication-related exception occurs
SecurityException - if a security exception occurs

toString

public String toString()
Returns a string representation of this object.

Overrides:
toString in class Object

equals

public boolean equals(Object obj)
Returns true if the specified object and this object are both instances of this class that were constructed with equivalent arguments. The order of trust verifier context elements, principals, and permissions in the arrays that were passed to the constructor is not significant.

Overrides:
equals in class Object

hashCode

public int hashCode()
Returns a hash code value for this object.

Overrides:
hashCode in class Object


Copyright 2007-2010, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.