java.rmi.transport
Interface SecureClientEndpoint


public interface SecureClientEndpoint

Defines a transport-neutral interface to objects that contain all of the information necessary for a client to open outgoing connections for secure remote calls. In the case of TCP, a client endpoint normally contains a remote IP address and port to connect to, and the socket factory to use. Classes that implement this interface should be serializable.

The equals method returns true if the parameter is functionally equivalent to this SecureClientEndpoint instance, and returns false otherwise.

When a secure remote object is exported, and when a stub for a secure remote object is deserialized, each SecureClientEndpoint instance is checked to ensure it is an instance of a trusted class, by consulting the list of TrustVerifier instances. The trustedClientEndpointClass method of each TrustVerifier instance is called with the endpoint class as a parameter. If any method returns true, the class is trusted. If none of the methods return true, a SecurityException is thrown.

Since:
1.4

Method Summary
 void checkConnect()
          Checks that the calling thread has permission to call openConnection.
 SecureClientConnection chooseConnection(java.util.Collection connections, SecureCallContext context)
          Returns the best connection from the specified collection of connections, such that the constraints actually in use on the connection, in conjunction with the authenticated identity of the client (if any) and server (if any), satisfy at least the same constraints that would be satisfied if openConnection was invoked with the specified context.
 SecureCallContext getCallContext(SecurityConstraints constraints, javax.security.auth.Subject clientSubject)
          Returns a context for making a secure remote call with the specified constraints and the specified client subject, which can be null.
 SecureClientConnection openConnection(SecureCallContext context)
          Returns a new connection, based on the specified context, such that the connection satisfies the best constraints possible from the constraints specified when the context was created.
 

Method Detail

getCallContext

public SecureCallContext getCallContext(SecurityConstraints constraints,
                                        javax.security.auth.Subject clientSubject)
                                 throws java.io.IOException
Returns a context for making a secure remote call with the specified constraints and the specified client subject, which can be null. This method returns null if not all of the constraint requirements can be supported in conjunction with the specified client subject, or if the calling thread does not have the requisite permissions (such as AuthenticationPermission) to satisfy the requirements. Communication with the remote server is permitted, but is not required, if the calling thread has permission. This method does not need to support any constraints based on relative time.
Parameters:
constraints - the security constraints for making the remote call
clientSubject - the client subject, or null
Returns:
a context for making a secure remote call with the specified constraints and the specified client subject, which can be null
Throws:
java.io.IOException - if an I/O exception occurs
NullPointerException - if the constraints parameter is null

openConnection

public SecureClientConnection openConnection(SecureCallContext context)
                                      throws java.io.IOException
Returns a new connection, based on the specified context, such that the connection satisfies the best constraints possible from the constraints specified when the context was created. The client is authenticated as necessary as the appropriate subset of the client subject specified when the context was created. The meaning of "best" is implementation dependent, but the connection must satisfy all of the requirements specified when the context was created. This method can attempt to negotiate more than one combination of constraints. If it does, the order is implementation dependent. However, absent of any overriding criteria, this method should attempt the negotiations in decreasing order of the number of preference types satisfied (see SecureCallContext).

If the connection returned by this method supports reuse with different constraints it should implement the SecureReusableClientConnection interface.

Parameters:
context - the secure call context
clientSubject - the client subject, or null
Returns:
a new connection, based on the specified context, such that the connection satisfies the best constraints possible from the constraints specified when the context was created
Throws:
java.io.IOException - if an I/O exception occurs
java.lang.SecurityException - if the calling thread does not have permission to call this method. In the usual TCP/IP case, the permission check for calling this method is performed by calling the checkConnect method of the installed security manager, passing the destination host and port for the connection.
NullPointerException - if context is null
java.lang.IllegalArgumentException - if the specified context was not created by an endpoint equal to this endpoint

checkConnect

public void checkConnect()
Checks that the calling thread has permission to call openConnection.
Throws:
java.lang.SecurityException - if the calling thread does not have permission to call openConnection. In the usual TCP/IP case, the permission check is performed by calling the checkConnect method of the installed security manager, passing the destination host and port for the connection.

chooseConnection

public SecureClientConnection chooseConnection(java.util.Collection connections,
                                               SecureCallContext context)
Returns the best connection from the specified collection of connections, such that the constraints actually in use on the connection, in conjunction with the authenticated identity of the client (if any) and server (if any), satisfy at least the same constraints that would be satisfied if openConnection was invoked with the specified context. Returns null if no connection in the collection satisfies these criteria, or the connections that satisfy these criteria do so in ways that are deemed too expensive compared with opening a new connection. The meaning of "best" and "too expensive" are implementation dependent. The specified collection must not be modified. To avoid opening a security hole, the implementation of this method must only compare objects (such as principals and credentials) that are known to be instances of classes trusted by this provider.
Parameters:
connections - a collection of connections
context - the secure call context
Returns:
the best connection from the specified collection of connections, such that the constraints actually in use on the connection, in conjunction with the authenticated identity of the client (if any) and server (if any), satisfy at least the same constraints that would be satisfied if openConnection was invoked with the specified context
Throws:
NullPointerException - if any parameter is null
java.lang.IllegalArgumentException - if the specified context or a connection in the specified collection was not created by an endpoint equal to this endpoint


Copyright © 2000 Sun Microsystems, Inc. All rights reserved