Provides implementations of {@link net.jini.jeri.Endpoint} and {@link net.jini.jeri.ServerEndpoint} that use Kerberos as the underlying network security protocol to support security related invocation constraints for remote requests. The `ServerEndpoint` abstraction is implemented by the {@link net.jini.jeri.kerberos.KerberosServerEndpoint}, while the client side `Endpoint` abstraction is implemented by the {@link net.jini.jeri.kerberos.KerberosEndpoint}.

The package also includes the {@link net.jini.jeri.kerberos.KerberosTrustVerifier} for establishing trust in remote proxies that use instances of the `KerberosEndpoint`, as well as principals of type {@link javax.security.auth.kerberos.KerberosPrincipal}.

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 {@link net.jini.jeri.BasicJeriExporter}, all DGC remote calls through this provider will silently fail.

## Supported Constraints

The endpoint classes in this package support at least the following standard constraints:

- {@link net.jini.core.constraint.Integrity#YES}
- {@link net.jini.core.constraint.Confidentiality}
- {@link net.jini.core.constraint.ClientAuthentication#YES}
- {@link net.jini.core.constraint.ConnectionAbsoluteTime}
- {@link net.jini.core.constraint.ConnectionRelativeTime}, trivially on the server side, since this only takes effect on the client side
- {@link net.jini.core.constraint.ServerAuthentication#YES}
- {@link net.jini.core.constraint.ClientMaxPrincipal}, when it contains at least one `KerberosPrincipal`
- {@link net.jini.core.constraint.ClientMaxPrincipalType}, when it contains the `KerberosPrincipal` class
- {@link net.jini.core.constraint.ClientMinPrincipal}, when it contains exactly one `KerberosPrincipal`
- {@link net.jini.core.constraint.ClientMinPrincipalType}, when it contains only the `KerberosPrincipal` class
- {@link net.jini.core.constraint.ServerMinPrincipal}, when it contains exactly one `KerberosPrincipal`
- {@link net.jini.core.constraint.Delegation}
- {@link net.jini.core.constraint.ConstraintAlternatives}, if the elements all have the same actual class and at least one element is supported

@org.apache.river.impl Classes in this package use the Java(TM) GSS-API to provide the underlying Kerberos network authentication protocol support. The Kerberos network authentication protocol is defined in RFC 1510. The GSS-API is defined in a language independent way in RFC 2743. The Java programming language bindings for GSS-API using Kerberos are defined in RFC 2853. The Java 2 Platform Standard Edition (J2SE(TM)) contains support for GSS-API Kerberos Java bindings via the {@link org.ietf.jgss} package. An Introduction to JAAS and Java GSS-API Tutorial is also available.

A Kerberos login module can be used to populate a `Subject` with {@link javax.security.auth.kerberos.KerberosPrincipal}s and credentials ({@link javax.security.auth.kerberos.KerberosTicket}s or {@link javax.security.auth.kerberos.KerberosKey}s). Note that by default the login module only stores a Ticket Granting Tickets (TGT), not the Kerberos key of the principal in the subject after a successful login. A `KerberosServerEndpoint` instance requires the Kerberos key of its server principal to be present in the subject, while a `KerberosEndpoint` instance only needs the TGT. For this reason `storeKey=true` has to be set as an option in the login module configuration on the server side.

This provider does not automatically renew any TGTs in the `Subject` used by a `KerberosEndpoint`. The assumption is that the endpoint 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 expire.

Due to security concerns, this implementation sometimes only throws an exception revealing the specific cause of a problem if the caller is granted {@link javax.security.auth.AuthPermission}`("getSubject")`, otherwise it throws a generic exception that enumerates possible causes.

Logging

The endpoint classes use the following {@link java.util.logging.Logger} instances to log information at the following levels:

`net.jini.jeri.kerberos.client`
Level | Description
--- | ---
{@link java.util.logging.Level#WARNING WARNING} | failure to register with discovery provider
{@link org.apache.river.logging.Levels#FAILED FAILED} | problem to support constraint requirements, connect to server through socket, establish {@link org.ietf.jgss.GSSContext} to server over established connections, or wrap/unwrap GSS tokens
{@link org.apache.river.logging.Levels#HANDLED HANDLED} | exceptions caught attempting to set TCP no delay or keep alive properties on sockets, connect a socket, or reuse a connection
{@link java.util.logging.Level#FINE FINE} | endpoint creation, {@link net.jini.jeri.Endpoint#newRequest newRequest} invocation, request handle creation, connection configuration decesions, socket creation, connection open/close, connection reuse decesions, `GSSContext` establishment
{@link java.util.logging.Level#FINEST FINEST} | data message encoding/decoding using `GSSContext`

`net.jini.jeri.kerberos.server`
Level | Description
--- | ---
{@link java.util.logging.Level#WARNING WARNING} | unexpected failure while accepting connections on the created `ServerSocket`.
{@link org.apache.river.logging.Levels#FAILED FAILED} | problems with permission checking, server principal and Kerberos key presence checking, {@link org.ietf.jgss.GSSCredential} creation, socket connect exception, `GSSContext` establishment, credential expiration, or wrap/unwrap GSS tokens
{@link org.apache.river.logging.Levels#HANDLED HANDLED} | failure to set TCP no delay or keep alive properties on sockets
{@link java.util.logging.Level#FINE FINE} | server endpoint creation, {@link net.jini.jeri.ServerCapabilities#checkConstraints checkConstraints} results, server socket creation, socket connect acceptance, server connection creation/destruction, `GSSContext` establishment
{@link java.util.logging.Level#FINEST FINEST} | data message encoding/decoding using `GSSContext`

Configuration

KDC and realm configuration:

As described in the {@link javax.security.auth.kerberos} package, a user can provide the default realm and default Key Distribution Center (KDC) host using the system properties `java.security.krb5.realm` and `java.security.krb5.kdc`. Alternatively, he/she can provide an MIT style configuration file: `<java-home>/lib/security/krb5.conf`, where `<java-home>` is the directory where J2SE is installed. If the file is placed elsewhere, the system property `java.security.krb5.conf` can be used to specify its location. A more detailed description of the searching scheme for `krb5.conf` can be found at here.

System properties supported by this provider

The client endpoints of this provider recognize the following system property:

- org.apache.river.jeri.kerberos.KerberosEndpoint.minGssContextLifetime - Minimum number of seconds of remaining lifetime a {@link org.ietf.jgss.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.

@since 2.0 @version 2.0