Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## net.jini.jeri.kerberos
Class KerberosEndpoint

    java.lang.Object
      net.jini.jeri.kerberos.KerberosEndpoint

All Implemented Interfaces:
  Endpoint, Serializable, 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/REALM@REALM"`. 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(TM) 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.

Since:
  2.0
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` | failure to set TCP no delay or keep alive properties on sockets
  `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:

  - com.sun.jini.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.
  - com.sun.jini.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
`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)

  Description copied from interface: `Endpoint`
  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.

  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

### 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.

### 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.

### toString

    public String toString()

  Returns a string representation of this endpoint.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 Sun Microsystems, Inc. All rights reserved