net.jini.jeri.kerberos
Class KerberosEndpoint

java.lang.Object
  extended by net.jini.jeri.kerberos.KerberosEndpoint
All Implemented Interfaces:
Serializable, Endpoint, TrustEquivalence

public final class KerberosEndpoint
extends Object
implements Endpoint, TrustEquivalence, Serializable

An Endpoint implementation that uses Kerberos as the underlying network security protocol to support security related invocation constraints its caller specified for the corresponding remote request. Instances of this class are referred to as the endpoints of the Kerberos provider, while instances of KerberosServerEndpoint are referred to as the server endpoints of the provider.

Instances of this class are intended to be created by the BasicJeriExporter class when it calls enumerateListenEndpoints on instances of KerberosServerEndpoint.

The KerberosTrustVerifier may be used for establishing trust in remote proxies that use instances of this class.

This class supports at least the following standard constraints:

An endpoint of this provider uses Kerberos Ticket Granting Tickets (TGTs), which are stored as private credentials in the Subject associated with the access control context of the current thread, to authenticate the caller of the remote request to the server.

A TGT is an instance of KerberosTicket whose server principal is of the form "krbtgt/REALM1@REALM2". The client principal of the TGT indicates what principal the endpoint can use the TGT to authenticate the caller as to the server.

Instances of this class contain a server host name, a server TCP port number, a server principal, as well as an optional SocketFactory for customizing the type of Socket to use.

A SocketFactory used with instances of this class should be serializable, and should implement Object.equals to return true when passed an instance that represents the same (functionally equivalent) socket factory.

To make a remote request through an endpoint of this provider, the caller or initiator of the request supplies the endpoint with a set of InvocationConstraints. The client principal used for the request is a KerberosPrincipal that appears in the principal set of the current subject, allowable by the given set of constraints, whose corresponding TGT is in the private credential set of the subject, and the connect AuthenticationPermission has been granted to the current access control context with the client principal as the local principal and the serverPrincipal contained in this endpoint as the peer principal.

If the set of constraints for the request specifies that encryption and/or delegation is required or preferred, they will be enforced by the provider. If encryption is unspecified in the constraints, the provider may or may not encrypt messages exchanged with the server. If delegation is unspecified in the constraints, the provider will not do delegation for the request. For delegation to happen, the TGT for the request has to be forwardable.

This class uses the Jini extensible remote invocation (Jini ERI) multiplexing protocol to map outgoing requests to the underlying secure connection streams.

The secure connection streams in this provider are implemented using the Kerberos Version 5 GSS-API Mechanism, defined in RFC 1964, over socket connections between client and server endpoints.

Note that, because Kerberos inherently requires client authentication, this transport provider does not support distributed garbage collection (DGC); if DGC is enabled using BasicJeriExporter, all DGC remote calls through this provider will silently fail.

Since:
2.0
Author:
Sun Microsystems, Inc.
See Also:
KerberosServerEndpoint, KerberosTrustVerifier, Serialized Form
Implementation Specifics:
This Kerberos provider implementation uses the Java(TM) GSS-API to provide the underlying Kerberos network authentication protocol support.

The implementation does not automatically renew any renewable TGTs in the Subject corresponding to any outbound request. The assumption is that an endpoint of this provider should merely be a consumer of the principals and credentials of the Subject, and never change its content. But if new TGTs are added into the Subject or old TGTs in the Subject are renewed by means outside this provider, the endpoint will pick up and use these new TGTs for new requests after the old ones have expired.

This class uses the following Logger to log information at the following logging levels:

net.jini.jeri.kerberos.client
Level Description
WARNING failure to register with discovery provider
FAILED problem to support constraint requirements, connect to server through socket, establish GSSContext to server over established connections, or wrap/unwrap GSS tokens
HANDLED exceptions caught attempting to set TCP no delay or keep alive properties on sockets, connect a socket, or reuse a connection
FINE endpoint creation, newRequest invocation, request handle creation, connection configuration decesions, socket creation, connection open/close, connection reuse decesions, GSSContext establishment
FINEST data message encoding/decoding using GSSContext

Instances of this class recognize the following system properties:


Method Summary
 boolean checkTrustEquivalence(Object obj)
          Returns true if the argument is an instance of KerberosEndpoint with the same values for server principal, server host, and port; and either both this instance and the argument have null socket factories, or the factories have the same actual class and are equal; and returns false otherwise.
 boolean equals(Object obj)
          Two instances of this class are equal if they contain the same server principal, host, and port, and their socket factories are both null or have the same actual class and are equal.
 String getHost()
          Returns the server host that this endpoint connects to.
static KerberosEndpoint getInstance(String serverHost, int serverPort, KerberosPrincipal serverPrincipal)
          Returns a KerberosEndpoint instance for the given server host name, TCP port number, and server principal.
static KerberosEndpoint getInstance(String serverHost, int serverPort, KerberosPrincipal serverPrincipal, SocketFactory csf)
          Returns a KerberosEndpoint instance for the given server host name, TCP port number, server principal, and SocketFactory.
 int getPort()
          Returns the TCP port that this endpoint connects to.
 KerberosPrincipal getPrincipal()
          Returns the principal this endpoint requires the server to authenticate as.
 SocketFactory getSocketFactory()
          Returns the SocketFactory that this endpoint uses to create Socket objects.
 int hashCode()
          Returns a hash code value for this object.
 OutboundRequestIterator newRequest(InvocationConstraints constraints)
          Returns an OutboundRequestIterator to use to send a new request to this remote endpoint using the specified constraints.
 String toString()
          Returns a string representation of this endpoint.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Method Detail

getInstance

public static KerberosEndpoint getInstance(String serverHost,
                                           int serverPort,
                                           KerberosPrincipal serverPrincipal)
Returns a KerberosEndpoint instance for the given server host name, TCP port number, and server principal. Internally this endpoint uses Socket objects to connect to its server endpoint.

Parameters:
serverHost - the host for the endpoint to connect to
serverPort - the TCP port on the given host for the endpoint to connect to
serverPrincipal - principal the server can authenticate as
Returns:
a KerberosEndpoint instance
Throws:
NullPointerException - if serverHost or serverPrincipal is null
IllegalArgumentException - if serverPort is not in the range of 1 to 65535

getInstance

public static KerberosEndpoint getInstance(String serverHost,
                                           int serverPort,
                                           KerberosPrincipal serverPrincipal,
                                           SocketFactory csf)
Returns a KerberosEndpoint instance for the given server host name, TCP port number, server principal, and SocketFactory.

If the socket factory argument is null, then this endpoint will create Socket objects directly.

Parameters:
serverHost - the host for the endpoint to connect to
serverPort - the TCP port on the given host for the endpoint to connect to
serverPrincipal - principal the server can authenticate as
csf - the SocketFactory to use for this KerberosEndpoint, or null
Returns:
a KerberosEndpoint instance
Throws:
NullPointerException - if serverHost or serverPrincipal is null
IllegalArgumentException - if serverPort is not in the range of 1 to 65535
See Also:
SocketFactory

getHost

public String getHost()
Returns the server host that this endpoint connects to.

Returns:
the server host that this endpoint connects to

getPort

public int getPort()
Returns the TCP port that this endpoint connects to.

Returns:
the TCP port that this endpoint connects to

getPrincipal

public KerberosPrincipal getPrincipal()
Returns the principal this endpoint requires the server to authenticate as.

Returns:
the server principal

getSocketFactory

public SocketFactory getSocketFactory()
Returns the SocketFactory that this endpoint uses to create Socket objects.

Returns:
the socket factory that this endpoint uses to create sockets, or null if no factory is used

newRequest

public OutboundRequestIterator newRequest(InvocationConstraints constraints)
Returns an OutboundRequestIterator to use to send a new request to this remote endpoint using the specified constraints.

The constraints must be the complete, absolute constraints for the request.

The returned OutboundRequestIterator's next method behaves as follows:

Initiates an attempt to communicate the request to this remote endpoint.

When the implementation of this method needs to create a new Socket, it will do so by invoking one of the createSocket methods on the SocketFactory of this KerberosEndpoint (which produced this iterator) if non-null, or it will create a Socket directly otherwise.

When the implementation needs to connect a Socket, if the host name to connect to (this KerberosEndpoint's host name) resolves to multiple addresses (according to InetAddress.getAllByName), it attempts to connect to the first resolved address; if that attempt fails with an IOException or a SecurityException, it then attempts to connect to the next address; and this iteration continues as long as there is another resolved address and the attempt to connect to the previous address fails with an IOException or a SecurityException. If the host name resolves to just one address, the implementation makes one attempt to connect to that address. If the host name does not resolve to any addresses (InetAddress.getAllByName would throw an UnknownHostException), the implementation still makes an attempt to connect the Socket to that host name, which could result in an UnknownHostException. If the final connection attempt fails with an IOException or a SecurityException, then if any connection attempt failed with an IOException, this method throws an IOException, and otherwise (if all connection attempts failed with a SecurityException), this method throws a SecurityException.

If there is a security manager:

  • If a new connection is to be created, the security manager's checkConnect method is invoked with this KerberosEndpoint's host and -1 for the port; if this results in a SecurityException, this method throws that exception. checkConnect is also invoked for each connection attempt, with the remote IP address (or the host name, if it could not be resolved) and port to connect to; this could result in a SecurityException for that attempt. (Note that the implementation may carry out these security checks indirectly, such as through invocations of InetAddress.getAllByName or Socket's constructors or connect method.)
  • In order to reuse an existing connection for the communication, the current security context must have the KerberosPrincipal, and permissions required to use it, that would be necessary if the the connection were being created. In addition, it must be possible to invoke checkConnect in the current security context with this KerberosEndpoint's host and -1 for the port without resulting in a SecurityException, and it also must be possible to invoke checkConnect with the remote IP address and port of the Socket without resulting in a SecurityException (if the remote socket address is unresolved, its host name is used instead). If no existing connection satisfies these requirements, then this method must behave as if there are no existing connections.

Throws NoSuchElementException if this iterator does not support making another attempt to communicate the request (that is, if hasNext would return false).

Throws IOException if an I/O exception occurs while performing this operation, such as if a connection attempt timed out or was refused or there are unsupported or conflicting constraints.

Throws SecurityException if there is a security manager and an invocation of its checkConnect method fails. Also, a SecurityException may be thrown if the caller does not have the appropriate AuthenticationPermission.

Specified by:
newRequest in interface Endpoint
Parameters:
constraints - the complete, absolute constraints
Returns:
an OutboundRequestIterator to use to send a new request to this remote endpoint
Throws:
NullPointerException - if constraints is null

checkTrustEquivalence

public boolean checkTrustEquivalence(Object obj)
Returns true if the argument is an instance of KerberosEndpoint with the same values for server principal, server host, and port; and either both this instance and the argument have null socket factories, or the factories have the same actual class and are equal; and returns false otherwise.

Specified by:
checkTrustEquivalence in interface TrustEquivalence
Parameters:
obj - object to check that is not yet known to be trusted
Returns:
true if the specified object (that is not yet known to be trusted) is equivalent in trust, content, and function to this known trusted object, and returns false otherwise

hashCode

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

Overrides:
hashCode in class Object

equals

public boolean equals(Object obj)
Two instances of this class are equal if they contain the same server principal, host, and port, and their socket factories are both null or have the same actual class and are equal.

Overrides:
equals in class Object

toString

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

Overrides:
toString in class Object


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