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 KerberosServerEndpoint

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

All Implemented Interfaces:
  ServerCapabilities, ServerEndpoint

public final class KerberosServerEndpoint
extends Object
implements ServerEndpoint

A `ServerEndpoint` implementation that uses Kerberos as the underlying network security protocol to support security related invocation constraints for remote requests. Instances of this class are referred to as the server endpoints of the Kerberos provider, while instances of `KerberosEndpoint` are referred to as the endpoints of the provider.

Instances of this class are intended to be created for use with the `BasicJeriExporter` class. Calls to `enumerateListenEndpoints` return instances of `KerberosEndpoint`.

This class supports at least the following standard constraints:

- `Integrity.YES`
- `Confidentiality`
- `ClientAuthentication.YES`
- `ConnectionAbsoluteTime`, trivially, since this only takes effect on the client side
- `ConnectionRelativeTime`, trivially, since this only takes effect on the client side
- `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

To get an instance of `KerberosServerEndpoint`, one of the `getInstance` methods of the class has to be invoked. The returned server endpoint instance encapsulates a set of properties that it will later use to receive and dispatch inbound requests. The following describes how some of these properties are chosen:

- `serverSubject` - The `Subject` that contains the principal and credential to be used by the server endpoint to authenticate itself to its remote callers. The subject is either provided by the caller of the `getInstance` method as a non-`null` argument, or extracted from the access control context of the current thread when the `getInstance` method is called. The later value is also referred to as the default server subject.
- `serverPrincipal` - The `KerberosPrincipal` that the server endpoint will authenticate itself as to all clients. If the caller of the `getInstance` method provides a non-`null` `serverPrincipal` argument, it is used without any further checking; otherwise the default server principal will be used. The default server principal can be any `KerberosPrincipal` instance in the `serverSubject`'s principal set, whose corresponding `KerberosKey` is found in the subject's private credential set and is still valid, provided the caller has been granted the `AuthenticationPermission` with the principal as its local principal and `listen` as its action.
- `serverHost` - The host name that will be encapsulated in `KerberosEndpoint` instances created by the server endpoint. If a non-`null serverHost` is provided by the caller, it will be used; otherwise the default value is used, which is the IP address of the local host, as obtained from `InetAddress.getLocalHost`. The host name does not affect the behavior of the listen operation itself, which always listens on all of the local system's network addresses, unless a `ServerSocketFactory` is provided by the caller, in which case the factory will be in charge.

This class permits specifying a `SocketFactory` for creating the `Socket` instances that the associated `KerberosEndpoint` instances use to make remote connections back to the server, and a `ServerSocketFactory` for creating the `ServerSocket` instances that the server endpoint uses to accept remote connections.

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. A `ServerSocketFactory` used with instances of this class should implement `Object.equals` to return `true` when passed an instance that represents the same (functionally equivalent) server socket factory.

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:
  `KerberosEndpoint`, `KerberosTrustVerifier`
Implementation Specifics:
  This class uses the following `Logger` to log information at the following logging levels:

  `net.jini.jeri.kerberos.server`
  Level | Description
  --- | ---
  `FAILED` | problems with permission checking, server principal and Kerberos key presence checking, `GSSCredential` creation, socket connect acception, `GSSContext` establishment, credential expiration, or wrap/unwrap GSS tokens
  `HANDLED` | failure to set TCP no delay or keep alive properties on sockets
  `FINE` | server endpoint creation, `checkConstraints` results, server socket creation, socket connect acceptance, server connection creation/destruction, `GSSContext` establishment
  `FINEST` | data message encoding/decoding using `GSSContext`

  When the `ListenEndpoint.listen` method of this implementation is invoked, a search is conducted on the private credentials of the `serverSubject`, the first valid `KerberosKey` whose principal equals to the `serverPrincipal` is chosen as the server credential for the listen operation. The presence of this server credential in the `serverSubject` as well as its validity are checked both when a new incoming connection is received and a new request arrives on an established connection; if the checks fail, the listen operation or the connection will be aborted permanently.

  This implementation uses the standard Java(TM) GSS-API. Additionally, for each inbound connection established, it invokes `GSSUtil.createSubject` to construct a `Subject` instance, which encapsulates the principal and delegated credential, if any, of the corresponding remote caller.

Nested Class Summary

Nested classes inherited from class net.jini.jeri.ServerEndpoint
`ServerEndpoint.ListenContext, ServerEndpoint.ListenCookie, ServerEndpoint.ListenEndpoint, ServerEndpoint.ListenHandle`

Method Summary
`InvocationConstraints` | `checkConstraints(InvocationConstraints constraints)` Verifies that this instance supports the transport layer aspects of all of the specified requirements (both in general and in the current security context), and returns the requirements that must be at least partially implemented by higher layers in order to fully satisfy all of the specified requirements.
`Endpoint` | `enumerateListenEndpoints(ServerEndpoint.ListenContext listenContext)` Enumerates the communication endpoints represented by this `ServerEndpoint` by passing the `ListenEndpoint` for each of them to `listenContext`, which will ensure an active listen operation on each endpoint, and returns an `Endpoint` instance corresponding to the listen operations chosen by `listenContext`.
`boolean` | `equals(Object obj)` Two instances of this class are equal if they have server subjects that compare equal using `==`; have the same server principal; have the same values for server host and port; have socket factories that are either both `null`, or have the same actual class and are equal; and have server socket factories that are either both `null`, or have the same actual class and are equal.
`String` | `getHost()` Returns the host name that will be used in `KerberosEndpoint` instances created by listening on this object.
`static KerberosServerEndpoint` | `getInstance(int port)` Returns a `KerberosServerEndpoint` instance with the specified port, using the default server subject, server principal, and server host.
`static KerberosServerEndpoint` | `getInstance(String serverHost, int port)` Returns a `KerberosServerEndpoint` instance with the specified server host and port, using the default server subject and server principal.
`static KerberosServerEndpoint` | `getInstance(String serverHost, int port, SocketFactory csf, ServerSocketFactory ssf)` Returns a `KerberosServerEndpoint` instance with the specified server host, port, and socket factories, using the default server subject and server principal.
`static KerberosServerEndpoint` | `getInstance(Subject serverSubject, KerberosPrincipal serverPrincipal, String serverHost, int port)` Returns a `KerberosServerEndpoint` instance with the specified server subject, server principal, server host, and port.
`static KerberosServerEndpoint` | `getInstance(Subject serverSubject, KerberosPrincipal serverPrincipal, String serverHost, int port, SocketFactory csf, ServerSocketFactory ssf)` Returns a `KerberosServerEndpoint` instance with the specified server subject, server principal, server host, port, and socket factories.
`int` | `getPort()` Returns the TCP port that the `ListenEndpoint`s created by this server endpoint listen on.
`KerberosPrincipal` | `getPrincipal()` Returns the principal that this server endpoint will authenticate itself as.
`ServerSocketFactory` | `getServerSocketFactory()` Returns the server socket factory that this server endpoint uses to create `ServerSocket` instances, or `null` if it uses default server sockets.
`SocketFactory` | `getSocketFactory()` Returns the socket factory that the associated `KerberosEndpoint` instances, which are created by listening on the `ListenEndpoint` instances of this server endpoint, use to create `Socket` instances, or `null` if they use default sockets.
`int` | `hashCode()` Returns a hash code value for this object.
`String` | `toString()` Returns a string representation of this object.

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

Method Detail

### getInstance

    public static KerberosServerEndpoint getInstance(int port)
                                              throws UnsupportedConstraintException

  Returns a `KerberosServerEndpoint` instance with the specified port, using the default server subject, server principal, and server host.

  Parameters:
    `port` - the port this server endpoint will listen on, 0 to use any free port
  Returns:
    a `KerberosServerEndpoint` instance
  Throws:
    `UnsupportedConstraintException` - if the caller has not been granted the right `AuthenticationPermission`, or there is no default server subject (`serverSubject.getSubject(AccessController.getContext())` returns `null`), or no appropriate Kerberos principal and corresponding Kerberos key can be found in the server subject
    `SecurityException` - if there is a security manager and the following condition is true:
    - The caller has been granted `AuthPermission``("getSubject")` , but no `listen` `AuthenticationPermission` whose local principal is a principal in the server subject's principal set, which is required for accessing any private credentials corresponding to the principal in the server subject.
    `IllegalArgumentException` - if `serverPort` is not in the range of `0` to `65535`

### getInstance

    public static KerberosServerEndpoint getInstance(String serverHost,
                                                     int port)
                                              throws UnsupportedConstraintException

  Returns a `KerberosServerEndpoint` instance with the specified server host and port, using the default server subject and server principal.

  Parameters:
    `serverHost` - the name or IP address of the server host the `KerberosEndpoint` instances created by this server endpoint will connect to. If `null`, the default server host will be used.
    `port` - the port this server endpoint will listen on, 0 to use any free port
  Returns:
    a `KerberosServerEndpoint` instance
  Throws:
    `UnsupportedConstraintException` - if the caller has not been granted the right `AuthenticationPermission`, or there is no default server subject (`serverSubject.getSubject(AccessController.getContext())` returns `null`), or no appropriate Kerberos principal and corresponding Kerberos key can be found in the server subject
    `SecurityException` - if there is a security manager and the following condition is true:
    - The caller has been granted `AuthPermission``("getSubject")` , but no `listen` `AuthenticationPermission` whose local principal is a principal in the server subject's principal set, which is required for accessing any private credentials corresponding to the principal in the server subject.
    `IllegalArgumentException` - if `serverPort` is not in the range of `0` to `65535`

### getInstance

    public static KerberosServerEndpoint getInstance(String serverHost,
                                                     int port,
                                                     SocketFactory csf,
                                                     ServerSocketFactory ssf)
                                              throws UnsupportedConstraintException

  Returns a `KerberosServerEndpoint` instance with the specified server host, port, and socket factories, using the default server subject and server principal.

  Parameters:
    `serverHost` - the name or IP address of the server host the `KerberosEndpoint` instances created by this server endpoint will connect to. If `null`, the default server host will be used.
    `port` - the port this server endpoint will listen on, 0 to use any free port
    `csf` - the `SocketFactory` to be used by the `KerberosEndpoint` created by this server endpoint to create sockets, or `null` to let the `KerberosEndpoint` create `Socket`s directly.
    `ssf` - the `ServerSocketFactory` to use for this `KerberosServerEndpoint`, or `null` to let the `KerberosServerEndpoint` create `ServerSocket`s directly.
  Returns:
    a `KerberosServerEndpoint` instance
  Throws:
    `UnsupportedConstraintException` - if the caller has not been granted the right `AuthenticationPermission`, or there is no default server subject (`serverSubject.getSubject(AccessController.getContext())` returns `null`), or no appropriate Kerberos principal and corresponding Kerberos key can be found in the server subject
    `SecurityException` - if there is a security manager and the following condition is true:
    - The caller has been granted `AuthPermission``("getSubject")` , but no `listen` `AuthenticationPermission` whose local principal is a principal in the server subject's principal set, which is required for accessing any private credentials corresponding to the principal in the server subject.
    `IllegalArgumentException` - if `serverPort` is not in the range of `0` to `65535`

### getInstance

    public static KerberosServerEndpoint getInstance(Subject serverSubject,
                                                     KerberosPrincipal serverPrincipal,
                                                     String serverHost,
                                                     int port)
                                              throws UnsupportedConstraintException

  Returns a `KerberosServerEndpoint` instance with the specified server subject, server principal, server host, and port.

  Parameters:
    `serverSubject` - the server subject to use for authenticating the server. If `null`, the subject associated with the current access control context will be used.
    `serverPrincipal` - the principal server should authenticate as. If `null`, then the default server principal will be used.
    `serverHost` - the name or IP address of the server host the `KerberosEndpoint` instances created by this server endpoint will connect to. If `null`, the default server host will be used.
    `port` - the port this server endpoint will listen on, 0 to use any free port
  Returns:
    a `KerberosServerEndpoint` instance
  Throws:
    `UnsupportedConstraintException` - if the caller has not been granted the right `AuthenticationPermission`, or there is no default server subject (`serverSubject.getSubject(AccessController.getContext())` returns `null`), or no appropriate Kerberos principal and corresponding Kerberos key can be found in the server subject
    `SecurityException` - if there is a security manager and the following condition is true:
    - The passed in serverPrincipal is `null`, the caller has the `AuthPermission``("getSubject")` , but no `listen` `AuthenticationPermission` whose local principal is a principal in the server subject's principal set, which is required for accessing any private credentials corresponding to the principal in the server subject.
    `IllegalArgumentException` - if `serverPort` is not in the range of `0` to `65535`

### getInstance

    public static KerberosServerEndpoint getInstance(Subject serverSubject,
                                                     KerberosPrincipal serverPrincipal,
                                                     String serverHost,
                                                     int port,
                                                     SocketFactory csf,
                                                     ServerSocketFactory ssf)
                                              throws UnsupportedConstraintException

  Returns a `KerberosServerEndpoint` instance with the specified server subject, server principal, server host, port, and socket factories.

  Parameters:
    `serverSubject` - the server subject to use for authenticating the server. If `null`, the subject associated with the current access control context will be used.
    `serverPrincipal` - the principal server should authenticate as. If `null`, then the default server principal will be used.
    `serverHost` - the name or IP address of the server host the `KerberosEndpoint` instances created by this server endpoint will connect to. If `null`, the default server host will be used.
    `port` - the port this server endpoint will listen on, 0 to use any free port
    `csf` - the `SocketFactory` to be used by the `KerberosEndpoint` created by this server endpoint to create sockets, or `null` to let the `KerberosEndpoint` create `Socket`s directly.
    `ssf` - the `ServerSocketFactory` to use for this `KerberosServerEndpoint`, or `null` to let the `KerberosServerEndpoint` create `ServerSocket`s directly.
  Returns:
    a `KerberosServerEndpoint` instance
  Throws:
    `UnsupportedConstraintException` - if the caller has not been granted the right `AuthenticationPermission`, or there is no default server subject (`serverSubject.getSubject(AccessController.getContext())` returns `null`), or no appropriate Kerberos principal and corresponding Kerberos key can be found in the server subject
    `SecurityException` - if there is a security manager and the following condition is true:
    - The passed in serverPrincipal is `null`, the caller has the `AuthPermission``("getSubject")` , but no `listen` `AuthenticationPermission` whose local principal is a principal in the server subject's principal set, which is required for accessing any private credentials corresponding to the principal in the server subject.
    `IllegalArgumentException` - if `serverPort` is not in the range of `0` to `65535`

### getHost

    public String getHost()

  Returns the host name that will be used in `KerberosEndpoint` instances created by listening on this object.

  Returns:
    the host name to use in `KerberosEndpoint` instances created by listening on this object

### getPort

    public int getPort()

  Returns the TCP port that the `ListenEndpoint`s created by this server endpoint listen on.

  Returns:
    the TCP port that the endpoints listen on

### getPrincipal

    public KerberosPrincipal getPrincipal()

  Returns the principal that this server endpoint will authenticate itself as.

  Returns:
    the principal that this server endpoint will authenticate as

### getSocketFactory

    public SocketFactory getSocketFactory()

  Returns the socket factory that the associated `KerberosEndpoint` instances, which are created by listening on the `ListenEndpoint` instances of this server endpoint, use to create `Socket` instances, or `null` if they use default sockets.

  Returns:
    the socket factory that associated endpoints use to create sockets, or `null` if they use default sockets

### getServerSocketFactory

    public ServerSocketFactory getServerSocketFactory()

  Returns the server socket factory that this server endpoint uses to create `ServerSocket` instances, or `null` if it uses default server sockets.

  Returns:
    the server socket factory that this server endpoint uses to create server sockets, or `null` if it uses default server sockets

### checkConstraints

    public InvocationConstraints checkConstraints(InvocationConstraints constraints)
                                           throws UnsupportedConstraintException

  Description copied from interface: `ServerCapabilities`
  Verifies that this instance supports the transport layer aspects of all of the specified requirements (both in general and in the current security context), and returns the requirements that must be at least partially implemented by higher layers in order to fully satisfy all of the specified requirements. This method may also return preferences that must be at least partially implemented by higher layers in order to fully satisfy some of the specified preferences.

  For any given constraint, there must be a clear delineation of which aspects (if any) must be implemented by the transport layer. This method must not return a constraint (as a requirement or a preference, directly or as an element of another constraint) unless this instance can implement all of those aspects. Also, this method must not return a constraint for which all aspects must be implemented by the transport layer. Most of the constraints in the `net.jini.core.constraint` package must be fully implemented by the transport layer and thus must not be returned by this method; the one exception is `Integrity`, for which the transport layer is responsible for the data integrity aspect and higher layers are responsible for the code integrity aspect.

  For any `ConstraintAlternatives` in the specified constraints, this method should only return a corresponding constraint if all of the alternatives supported by this instance need to be at least partially implemented by higher layers in order to be fully satisfied.

  The constraints passed to this method may include constraints based on relative time.

  Specified by:
    `checkConstraints` in interface `ServerCapabilities`
  Parameters:
    `constraints` - the constraints that must be supported
  Returns:
    the constraints that must be at least partially implemented by higher layers
  Throws:
    `UnsupportedConstraintException` - if the transport layer aspects of any of the specified requirements are not supported by this instance (either in general or in the current security context)

### enumerateListenEndpoints

    public Endpoint enumerateListenEndpoints(ServerEndpoint.ListenContext listenContext)
                                      throws IOException

  Enumerates the communication endpoints represented by this `ServerEndpoint` by passing the `ListenEndpoint` for each of them to `listenContext`, which will ensure an active listen operation on each endpoint, and returns an `Endpoint` instance corresponding to the listen operations chosen by `listenContext`.

  If this server endpoint's server host is `null`, then the endpoint returned will contain the default server host. This method computes the default by invoking `InetAddress.getLocalHost` to obtain an `InetAddress` for the local host. If `InetAddress.getLocalHost` throws an exception, this method throws that exception. The default host name will be the string returned by invoking `getHostAddress` on that `InetAddress`. If there is a security manager, its `checkConnect` method will be invoked with the string returned by invoking `getHostName` on that same `InetAddress` as the host argument and `-1` as the port argument; this could result in a `SecurityException`.

  If this server endpoint's `ServerSocketFactory` is not `null`, then the `listen` method defined on the `ListenEndpoint` this method passes to `listenContext` will create new `ServerSocket` instances by invoking one of the factory's `createServerSocket` methods that returns bound server sockets, and otherwise it will create server sockets directly.

  If there is a security manager, the `checkPermissions` and `listen` methods defined on the listen endpoint will call the security manager's `checkListen` method, as well as requiring the caller to have `AuthenticationPermission` with the server principal as its local principal and `listen` as its action.

  Instances of this class will only dispatch inbound requests if the caller of `listen` on this class's `ServerEndpoint.ListenEndpoint` has been granted `AuthenticationPermission` with the server principal as the local principal, the principal representing the authenticated identity of the client for the request as the peer principal, and the `accept` as the action.

  Once a `ListenEndpoint` of this provider starts to listen, each time a new inbound request comes in, it verifies that the `serverSubject` of the corresponding server endpoint still holds a valid `KerberosKey` corresponding to its `serverPrincipal`. It rejects the request if the verification fails. This guarantees that as soon as the `KerberosKey` for the principal in the `Subject` is destroyed (logout) or expired, no more new requests will be accepted.

  Specified by:
    `enumerateListenEndpoints` in interface `ServerEndpoint`
  Parameters:
    `listenContext` - the `ListenContext` to pass this `ServerEndpoint`'s `ListenEndpoint` instances to
  Returns:
    the `Endpoint` instance for sending requests to this `ServerEndpoint`'s communication endpoints being listened on
  Throws:
    `SecurityException` - if there is a security manager, and either its `checkListen` method fails, or `serverHost` is `null` and the security manager's `checkConnect` method fails; or if the calling thread does not have permission to authenticate as the endpoint's server principals when listening for connections
    `IllegalArgumentException` - if an invocation of the `addListenEndpoint` method on the supplied `ListenContext` returns a `ListenCookie` that does not correspond to the `ListenEndpoint` that was passed to it
    `NullPointerException` - if `listenContext` is `null`
    `UnknownHostException` - if this instance's server host is `null` and `InetAddress.getLocalHost` throws an `UnknownHostException`
    `UnsupportedConstraintException` - if the server subject is missing any of the endpoint's server principals or the associated credentials
    `IOException` - if an I/O exception occurs while attempting to listen for requests on the communication endpoints represented by this `ServerEndpoint`. This could occur, for example, if an I/O resource associated with one of the communication endpoints is already in exclusive use, or if there are insufficient I/O resources for the operation.

### 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 have server subjects that compare equal using `==`; have the same server principal; have the same values for server host and port; have socket factories that are either both `null`, or have the same actual class and are equal; and have server socket factories that are either both `null`, or have the same actual class and are equal.

### toString

    public String toString()

  Returns a string representation of this object.

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