java.rmi
Interface RemoteSecurity

All Known Implementing Classes:
SecureActivationID

public interface RemoteSecurity

Defines the interface to secure RMI stubs and proxies. Secure RMI stubs implement this non-remote interface. Servers that define proxy interfaces to remote services are encouraged to implement this interface as well, to give applications a uniform way to control security constraints.

Overall, security constraints come from three sources:

The server can specify different constraints for each remote method, if desired. The server's constraints for a given method apply to all calls to that method by the client. Constraints placed directly on a proxy by a client apply to all remote calls made through that particular proxy by any thread. Contextual constraints apply to all secure remote calls (made through any proxy, to anywhere), by the thread.

The constraint mechanisms are designed such that constraints set by the client do not weaken constraints set by the server, and constraints set by invoked code do not weaken contextual constraints set by the code that invoked it. However, it is certainly possible for entities to specify conflicting requirements, in which case the remote call will not be made.

A secure remote call will be performed only if: the server is capable of satisfying the combined requirements (from all three sources); the combined requirements are supported by the client's underlying RMI runtime implementation; and the calling thread has the requisite permissions (such as AuthenticationPermission) to satisfy the requirements. In addition, both client and server preferences will be satisfied, to the extent possible.

For classes that implement this interface, the equals method includes both client and server constraints in its comparison.

Since:
1.4

Method Summary
 boolean equalsIgnoreConstraints(java.lang.Object obj)
          Returns true if the two proxies are equal, ignoring both client and server security constraints; returns false otherwise.
 SecurityConstraints getClientConstraints()
          Returns the current client constraints, as a non-null instance.
 SecurityConstraints getServerConstraints(java.lang.String methodName, java.lang.Class[] parameterTypes)
          Returns the server's constraints for the specified remote method as a non-null instance.
 javax.security.auth.Subject getServerSubject()
          Connects to the server as if a remote call were to be performed (with security constraints being applied in the normal way), and returns the authenticated identity of the server as a read-only instance, or null if the server has not been authenticated.
 RemoteSecurity setClientConstraints(SecurityConstraints constraints)
          Returns a new copy of this proxy with the specified client constraints.
 

Method Detail

setClientConstraints

public RemoteSecurity setClientConstraints(SecurityConstraints constraints)
Returns a new copy of this proxy with the specified client constraints. These constraints completely replace (in the copy) any client constraints previously placed on the proxy. The original proxy is not modified. If null is specified, a constraints instance containing no constraints is used instead.

Client constraints placed on a proxy are included in the serialized state of the proxy, to allow a service to be transparent to the client's needs. For example, if remote object s1 obtains a proxy for remote object s2, and passes that proxy to remote object s3, expecting s3 to invoke a method on s2, then s1 can control the security of that call by placing its constraints directly on the proxy before passing it to s3. If a service does not wish to be transparent in this way, then it should explicitly replace the constraints on received proxies with whatever constraints are appropriate to implement its own security policy.

Parameters:
constraints - client constraints, or null
Returns:
a new copy of this proxy with the specified client constraints

getClientConstraints

public SecurityConstraints getClientConstraints()
Returns the current client constraints, as a non-null instance.
Returns:
the current client constraints, as a non-null instance

getServerConstraints

public SecurityConstraints getServerConstraints(java.lang.String methodName,
                                                java.lang.Class[] parameterTypes)
                                         throws java.lang.NoSuchMethodException,
                                                java.rmi.RemoteException
Returns the server's constraints for the specified remote method as a non-null instance. The values can vary with the remote method, so the particular method must be specified by giving the method name and parameter types. The value of parameterTypes can be null, which is treated the same as an empty array.

For stubs created using SecureUnicastRemoteObject, this method will never actually throw RemoteException; the server constraints are constant, and are maintained inside the stub's reference. For stubs created using SecureActivatable, this method can throw RemoteException, and the return values can change over time; the server constraints are maintained inside the transient live reference. Proxies that implement this interface can choose whether the server constraints are constant or variable.

Parameters:
methodName - the name of the remote method
parameterTypes - the formal parameter types of the remote method, in declared order
Returns:
the server's constraints for the specified method as a non-null instance
Throws:
java.lang.NoSuchMethodException - if the specified method does not exist
NullPointerException - if methodName is null or any element of parameterTypes is null
java.lang.IllegalArgumentException - if the specified method exists but is not a remote method and is not the getServerSubject method of this interface
java.rmi.RemoteException - if a communication-related exception occurs

getServerSubject

public javax.security.auth.Subject getServerSubject()
                                             throws java.rmi.RemoteException
Connects to the server as if a remote call were to be performed (with security constraints being applied in the normal way), and returns the authenticated identity of the server as a read-only instance, or null if the server has not been authenticated. Note that checking the authenticated identity of the server obtained from calling this method is no guarantee that the server will correctly authenticate itself in any future calls. Although a client might not specify a ServerMinPrincipal requirement when calling this method, a client generally needs to specify a ServerMinPrincipal requirement for other methods when server authentication is needed, or else verify that the server has specified a satisfactory ServerMinPrincipal requirement for each of the methods that the client cares about. This method can be used to obtain principals with which to create such a ServerMinPrincipal requirement.
Returns:
the authenticated identity of the server as a read-only instance, or null if the server has not been authenticated
Throws:
java.rmi.RemoteException - if a communication-related exception occurs

equalsIgnoreConstraints

public boolean equalsIgnoreConstraints(java.lang.Object obj)
Returns true if the two proxies are equal, ignoring both client and server security constraints; returns false otherwise. For stubs, this method simply checks that the two stubs are for the same remote object.
Parameters:
obj - the proxy object with which to compare
Returns:
true if the two proxies are equal, ignoring both client and server security constraints; false otherwise


Copyright © 2000 Sun Microsystems, Inc. All rights reserved