net.jini.security

Class BasicProxyPreparer

java.lang.Object

net.jini.security.BasicProxyPreparer

All Implemented Interfaces:

Serializable, ProxyPreparer

public class BasicProxyPreparer
extends Object
implements ProxyPreparer, Serializable

A ProxyPreparer for verifying that proxies are trusted, granting them dynamic permissions, and setting their constraints, as well as for creating other proxy preparer subclasses that include those operations.

Applications and configurations can use this class to create proxy preparers for several common cases. Some examples include creating proxy preparers that:

• Verify trust, grant permissions, and set new constraints, to prepare a proxy received from an untrusted source.
• Use the proxy's existing constraints when verifying trust in the proxy, to prepare a trusted proxy received with integrity protection from a trusted source that supplies constraints, confirming that the proxy's implementation is trusted locally, but allowing the constraints to be downloaded from a third party.
• Set new constraints, to prepare a trusted proxy received with integrity protection from a trusted source that is not known to supply the appropriate constraints.
• Grant permissions, to prepare a trusted proxy received with integrity protection from a trusted source that supplies appropriate constraints, if the proxy needs permission grants.
• Do nothing, to use as a default when retrieving an optional configuration entry, or to prepare a non-secure proxy.

Since:

2.0

Author:

Sun Microsystems, Inc.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected MethodConstraints	methodConstraints Method constraints to use when verifying if proxies are trusted and for setting their constraints, if methodConstraintsSpecified is true.
protected boolean	methodConstraintsSpecified Whether to use methodConstraints when verifying if proxies are trusted and for setting their constraints.
protected Permission[]	permissions Permissions to grant to proxies, or an empty array if no permissions should be granted.
protected boolean	verify Whether to verify if proxies are trusted.

Constructor Summary

Constructors

Constructor and Description
BasicProxyPreparer() Creates a proxy preparer that specifies not to verify proxies, grant them permissions, or set their constraints.
BasicProxyPreparer(boolean verify, MethodConstraints methodConstraints, Permission[] permissions) Creates a proxy preparer that specifies whether proxies should be verified, specifies permissions to grant them, and specifies what method constraints to use when verifying and setting constraints.
BasicProxyPreparer(boolean verify, Permission[] permissions) Creates a proxy preparer that specifies whether proxies should be verified, using the constraints on the proxy by default, and specifies what permissions to grant to proxies.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object object) Returns true if the given object is an instance of the same class as this object, with the same value for verify, with method constraints that are equals or similarly not specified, and with permissions containing the same elements, independent of order.
protected MethodConstraints	getMethodConstraints(Object proxy) Returns the method constraints to use when verifying and setting constraints on the specified proxy.
protected Permission[]	getPermissions(Object proxy) Returns the permissions to grant to proxies, or an empty array if no permissions should be granted.
protected void	grant(Object proxy) Grants permissions to the proxy.
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.
protected Object	setConstraints(Object proxy) Sets constraints on the proxy.
String	toString() Returns a string representation of this object.
protected void	verify(Object proxy) Verifies that the proxy is trusted.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

verify

protected final boolean verify

Whether to verify if proxies are trusted.

methodConstraintsSpecified

protected final boolean methodConstraintsSpecified

Whether to use methodConstraints when verifying if proxies are trusted and for setting their constraints.

methodConstraints

protected final MethodConstraints methodConstraints

Method constraints to use when verifying if proxies are trusted and for setting their constraints, if methodConstraintsSpecified is true. Set to null if methodConstraintsSpecified is false.

permissions

protected final Permission[] permissions

Permissions to grant to proxies, or an empty array if no permissions should be granted. The value is always non-null.

Constructor Detail

BasicProxyPreparer

public BasicProxyPreparer()

Creates a proxy preparer that specifies not to verify proxies, grant them permissions, or set their constraints.

BasicProxyPreparer

public BasicProxyPreparer(boolean verify,
                          Permission[] permissions)

Creates a proxy preparer that specifies whether proxies should be verified, using the constraints on the proxy by default, and specifies what permissions to grant to proxies.

Parameters:

verify - whether to verify if proxies are trusted

permissions - permissions to grant, or null if no permissions should be granted

Throws:

NullPointerException - if permissions is not null and any of its elements are null

BasicProxyPreparer

public BasicProxyPreparer(boolean verify,
                          MethodConstraints methodConstraints,
                          Permission[] permissions)

Creates a proxy preparer that specifies whether proxies should be verified, specifies permissions to grant them, and specifies what method constraints to use when verifying and setting constraints.

Parameters:

verify - whether to verify if proxies are trusted

methodConstraints - method constraints to use when verifying and setting constraints

permissions - permissions to grant, or null if no permissions should be granted

Throws:

NullPointerException - if permissions is not null and any of its elements are null

Method Detail

getMethodConstraints

protected MethodConstraints getMethodConstraints(Object proxy)

Returns the method constraints to use when verifying and setting constraints on the specified proxy.

The default implementation returns the value of methodConstraints if methodConstraintsSpecified is true, else returns the constraints on the specified proxy if it implements RemoteMethodControl, else returns null.

Subclasses may wish to override this method, for example, to augment the existing constraints on the proxy rather than replacing them.

Parameters:

proxy - the proxy being prepared

Returns:

the method constraints to use when verifying and setting constraints on the proxy

getPermissions

protected Permission[] getPermissions(Object proxy)

Returns the permissions to grant to proxies, or an empty array if no permissions should be granted. The return value need not be newly created, but cannot be null.

The default implementation returns the value of permissions.

Subclasses may wish to override this method, for example, to grant permissions that depend on principal constraints found on the proxy.

Parameters:

proxy - the proxy being prepared

Returns:

the permissions to grant to the proxy

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.

The default implementation provides the following behavior. If proxy is null, throws a NullPointerException. Otherwise, calls verify with proxy. If the verify call succeeds, calls grant with proxy. If the grant call succeeds, returns the result of calling setConstraints with proxy.

Subclasses may wish to override this method, for example, to perform additional operations, typically calling the default implementation via super.

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

See Also:

verify, grant, setConstraints

verify

protected void verify(Object proxy)
               throws RemoteException

Verifies that the proxy is trusted. Called by the default implementation of prepareProxy.

The default implementation provides the following behavior. If proxy is null, throws a NullPointerException. Otherwise, if verify is true, calls Security.verifyObjectTrust, with proxy, null for the class loader, and, for the context, a collection containing the result of calling getMethodConstraints with proxy, or an empty collection if the constraints are null.

Subclasses may wish to override this method, for example, to specify a different class loader or context when verifying the proxy.

Parameters:

proxy - the proxy to verify

Throws:

NullPointerException - if proxy is null

RemoteException - if a communication-related exception occurs

SecurityException - if verifying that the proxy is trusted fails

See Also:

prepareProxy, getMethodConstraints, Security.verifyObjectTrust

grant

protected void grant(Object proxy)

Grants permissions to the proxy. Called by the default implementation of prepareProxy unless verify throws an exception.

The default implementation provides the following behavior. If proxy is null, throws a NullPointerException. Otherwise, calls getPermissions with proxy to determine what permissions should be granted. If the permissions are not empty, calls Security.grant, with the proxy's class as the class argument and those permissions. If grant discovers that dynamic permission grants are not supported and throws a UnsupportedOperationException, catches that exception and throws a SecurityException.

Subclasses may wish to override this method, for example, to alter the principals for which permission grants are made.

Parameters:

proxy - the proxy to grant permissions

Throws:

SecurityException - if a security exception occurs

NullPointerException - if proxy is null

See Also:

prepareProxy, getPermissions, Security.grant

setConstraints

protected Object setConstraints(Object proxy)

Sets constraints on the proxy. Called by the default implementation of prepareProxy unless verify or grant throw an exception.

The default implementation provides the following behavior. If proxy is null, throws a NullPointerException. Otherwise, if methodConstraintsSpecified is false, returns the proxy, else if object does not implement RemoteMethodControl, throws a SecurityException, else returns the result of calling RemoteMethodControl.setConstraints on the proxy, using the value returned from calling getMethodConstraints with proxy.

Subclasses may wish to override this method, for example, to support verifying objects that do not implement RemoteMethodControl.

Parameters:

proxy - the proxy

Returns:

the proxy with updated constraints

Throws:

NullPointerException - if proxy is null

SecurityException - if a security exception occurs

See Also:

prepareProxy, getMethodConstraints, RemoteMethodControl.setConstraints

toString

public String toString()

Returns a string representation of this object.

Overrides:

toString in class Object

equals

public boolean equals(Object object)

Returns true if the given object is an instance of the same class as this object, with the same value for verify, with method constraints that are equals or similarly not specified, and with permissions containing the same elements, independent of order.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code value for this object.

Overrides:

hashCode in class Object