KerberosEndpoint (Apache River v3.0.0 API Documentation)

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

**`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.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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

Class KerberosEndpoint

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getInstance

getInstance

getHost

getPort

getPrincipal

getSocketFactory

newRequest

checkTrustEquivalence

hashCode

equals

toString