KerberosEndpoint (Apache River v3.0.0 API Documentation (internals))

java.lang.Object
- 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:

Integrity.YES
Confidentiality
ClientAuthentication.YES
ConnectionAbsoluteTime
ServerAuthentication.YES
ClientMaxPrincipal, when it contains at least one KerberosPrincipal
ClientMaxPrincipalType, when it contains the KerberosPrincipal class
ClientMinPrincipal, when it contains exactly one KerberosPrincipal
ClientMinPrincipalType, when it contains only the KerberosPrincipal class
ServerMinPrincipal, when it contains exactly one KerberosPrincipal
Delegation
ConstraintAlternatives, if the elements all have the same actual class and at least one element is supported

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

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:

org.apache.river.jeri.kerberos.KerberosEndpoint.minGssContextLifetime - Minimum number of seconds of remaining lifetime a GSSContext of an existing connection has to have before it can be considered as a candidate connection to be chosen for a new request. The default is 30.
org.apache.river.jeri.kerberos.KerberosEndpoint.maxGssContextRetries - RFC 1510 specifies that if a KDC or server receives two authenticators with the same client and server pair and timestamps of the same microsecond, the second will be considered a replay and will be rejected. This means if multiple session ticket requests of the same client and server principal pair and microsecond timestamps are received at a KDC, only the first one will succeed, and the rest will be considered replays and will be rejected by the KDC. For this reason, the Kerberos provider catches the "replay" exception and retries the corresponding GSSContext initialization handshake. This system property controls the maximum number of retries a KerberosEndpoint will conduct. The default is 3.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`private static class`	`KerberosEndpoint.CacheKey` The key used for the softcache of this endpoint.
`private class`	`KerberosEndpoint.ConnectionEndpointImpl` ConnectionEndpoint implementation class for this end point
`private class`	`KerberosEndpoint.ConnectionImpl` Implementation class of the client side connection abstraction
`private static class`	`KerberosEndpoint.KerberosEndpointInternals` Support EndpointInternals, for use by discovery providers
`private class`	`KerberosEndpoint.RequestHandleImpl` `OutboundRequestHandle` implementation

Field Summary

Fields
Modifier and Type	Field and Description
`private static Object`	`classLock` Internal lock for class-wide synchronizaton
`private KerberosEndpoint.ConnectionEndpointImpl`	`connectionEndpoint` The `ConnectionEndpoint` this endpoint passes to its `connManager` to create connections.
`private ConnManager`	`connManager` The `ConnManager` this endpoint uses to create connections.
`private SocketFactory`	`csf` The socket factory that this `KerberosEndpoint` uses to create `java.net.Socket` objects.
`private boolean`	`disableSocketConnect` If set to true, causes the endpoint not to connect sockets it obtains from its socket factory.
`private static String[]`	`ERROR_STRINGS`
`private static GSSManager`	`gssManager` GSSManager instance used by all endpoints in a JVM
`private static Map`	`internTable` Weak set of canonical instances; in order to use WeakHashMap, maps canonical instances to weak references to themselves.
`private static Logger`	`logger` JERI Kerberos client transport logger
`private static int`	`maxCacheSize` Maximum number of entries allowed in the soft cache of a Kerberos endpoint.
`private static int`	`maxGssContextRetries` Maximum retries for initial `GSSContext` handshake.
`private static int`	`minGssContextLifetime` Minimum number of seconds of life time a `GSSContext` of an existing connection has to have before it can be considered as a candidate connection to be chosen for a new request.
`private static int`	`NO_CLIENT_PRINCIPAL`
`private static int`	`NO_ERROR`
`private static int`	`NULL_SUBJECT`
`private static long`	`serialVersionUID`
`private String`	`serverHost` Name or ip address of the server host.
`private int`	`serverPort` Port that the server is listening on for incoming connection requests.
`private KerberosPrincipal`	`serverPrincipal` Principal of which the server is capable of authenticating as.
`private KerberosUtil.SoftCache`	`softCache` A cache maintains soft reference to its values.
`private static int`	`UNSATISFIABLE_CONSTRAINT_REQUIRED`
`private static int`	`UNSUPPORTABLE_CONSTRAINT_REQUIRED`

Constructor Summary

Constructors
Modifier	Constructor and Description
`private`	`KerberosEndpoint(String serverHost, int serverPort, KerberosPrincipal serverPrincipal, SocketFactory csf)` Creates an endpoint of this Kerberos provider.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`private KerberosEndpoint.ConnectionImpl`	`checkConnection(Object c)` Make sure that the passed in context has the right type, and was previously instantiated in this endpoint.
`private void`	`checkEndpoint(KerberosEndpoint ep)` Make sure that the passed in endpoint instance equals the enclosing endpoint instance.
`private KerberosEndpoint.RequestHandleImpl`	`checkRequestHandleImpl(Object h)` Make sure that the passed in request handle has the right type, and was previously instantiated in this endpoint.
`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.
`private static KerberosEndpoint`	`intern(KerberosEndpoint endpoint)` Returns canonical instance equivalent to given instance.
`OutboundRequestIterator`	`newRequest(InvocationConstraints constraints)` Returns an `OutboundRequestIterator` to use to send a new request to this remote endpoint using the specified constraints.
`private void`	`readObject(ObjectInputStream ois)` Read in a serialized instance and check that the deserialized instance has the right fields.
`private Object`	`readResolve()` Resolves deserialized instance to equivalent canonical instance.
`String`	`toString()` Returns a string representation of this endpoint.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - serialVersionUID
```
private static final long serialVersionUID
```
    See Also:
    
    Constant Field Values
  - logger
```
private static final Logger logger
```
    JERI Kerberos client transport logger
  - serverHost
```
private final String serverHost
```
    Name or ip address of the server host.
  - serverPort
```
private final int serverPort
```
    Port that the server is listening on for incoming connection requests.
  - serverPrincipal
```
private final KerberosPrincipal serverPrincipal
```
    Principal of which the server is capable of authenticating as.
  - csf
```
private final SocketFactory csf
```
    The socket factory that this KerberosEndpoint uses to create java.net.Socket objects.
  - classLock
```
private static final Object classLock
```
    Internal lock for class-wide synchronizaton
  - gssManager
```
private static GSSManager gssManager
```
    GSSManager instance used by all endpoints in a JVM
  - maxCacheSize
```
private static final int maxCacheSize
```
    Maximum number of entries allowed in the soft cache of a Kerberos endpoint. The default is 64.
  - minGssContextLifetime
```
private static final int minGssContextLifetime
```
    Minimum number of seconds of life time a GSSContext of an existing connection has to have before it can be considered as a candidate connection to be chosen for a new request. The default is 30.
  - maxGssContextRetries
```
private static final int maxGssContextRetries
```
    Maximum retries for initial GSSContext handshake.
  - softCache
```
private transient KerberosUtil.SoftCache softCache
```
    A cache maintains soft reference to its values. This cache is keyed by security constraints and subject used for the corresponding request, its value entries encapsulate the result of the analysis of the constraints and principals in the subject, without checking permissions and private credentials.
  - connectionEndpoint
```
private transient KerberosEndpoint.ConnectionEndpointImpl connectionEndpoint
```
    The ConnectionEndpoint this endpoint passes to its connManager to create connections.
  - connManager
```
private transient ConnManager connManager
```
    The ConnManager this endpoint uses to create connections.
  - disableSocketConnect
```
private transient boolean disableSocketConnect
```
    If set to true, causes the endpoint not to connect sockets it obtains from its socket factory.
  - internTable
```
private static final Map internTable
```
    Weak set of canonical instances; in order to use WeakHashMap, maps canonical instances to weak references to themselves.
  - NO_ERROR
```
private static final int NO_ERROR
```
    See Also:
    
    Constant Field Values
  - UNSUPPORTABLE_CONSTRAINT_REQUIRED
```
private static final int UNSUPPORTABLE_CONSTRAINT_REQUIRED
```
    See Also:
    
    Constant Field Values
  - NULL_SUBJECT
```
private static final int NULL_SUBJECT
```
    See Also:
    
    Constant Field Values
  - NO_CLIENT_PRINCIPAL
```
private static final int NO_CLIENT_PRINCIPAL
```
    See Also:
    
    Constant Field Values
  - UNSATISFIABLE_CONSTRAINT_REQUIRED
```
private static final int UNSATISFIABLE_CONSTRAINT_REQUIRED
```
    See Also:
    
    Constant Field Values
  - ERROR_STRINGS
```
private static final String[] ERROR_STRINGS
```
- Constructor Detail
  - KerberosEndpoint
```
private KerberosEndpoint(String serverHost,
                         int serverPort,
                         KerberosPrincipal serverPrincipal,
                         SocketFactory csf)
```
    Creates an endpoint of this Kerberos provider.
    
    Parameters:
    
    serverHost - the name or ip address of the server host this endpoint will connect to
    
    serverPort - the server port
    
    serverPrincipal - principal the server can authenticate as
    
    csf - the SocketFactory to use for this KerberosEndpoint, or null
    
    Throws:
    
    NullPointerException - if serverHost or serverPrincipal is null
    
    IllegalArgumentException - if serverPort is not in the range of 1 to 65535
- 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
  - readResolve
```
private Object readResolve()
```
    Resolves deserialized instance to equivalent canonical instance.
  - readObject
```
private void readObject(ObjectInputStream ois)
                 throws IOException,
                        ClassNotFoundException
```
    Read in a serialized instance and check that the deserialized instance has the right fields.
    
    Throws:
    
    IOException
    
    ClassNotFoundException
  - intern
```
private static KerberosEndpoint intern(KerberosEndpoint endpoint)
```
    Returns canonical instance equivalent to given instance.
  - checkEndpoint
```
private void checkEndpoint(KerberosEndpoint ep)
```
    Make sure that the passed in endpoint instance equals the enclosing endpoint instance.
  - checkRequestHandleImpl
```
private KerberosEndpoint.RequestHandleImpl checkRequestHandleImpl(Object h)
```
    Make sure that the passed in request handle has the right type, and was previously instantiated in this endpoint.
  - checkConnection
```
private KerberosEndpoint.ConnectionImpl checkConnection(Object c)
```
    Make sure that the passed in context has the right type, and was previously instantiated in this endpoint.

Class KerberosEndpoint

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

serialVersionUID

logger

serverHost

serverPort

serverPrincipal

csf

classLock

gssManager

maxCacheSize

minGssContextLifetime

maxGssContextRetries

softCache

connectionEndpoint

connManager

disableSocketConnect

internTable

NO_ERROR

UNSUPPORTABLE_CONSTRAINT_REQUIRED

NULL_SUBJECT

NO_CLIENT_PRINCIPAL

UNSATISFIABLE_CONSTRAINT_REQUIRED

ERROR_STRINGS

Constructor Detail

KerberosEndpoint

Method Detail

getInstance

getInstance

getHost

getPort

getPrincipal

getSocketFactory

newRequest

checkTrustEquivalence

hashCode

equals

toString

readResolve

readObject

intern

checkEndpoint

checkRequestHandleImpl

checkConnection