Package net.jini.jeri.kerberos

Provides implementations of Endpoint and ServerEndpoint that use Kerberos as the underlying network security protocol to support security related invocation constraints for remote requests.

See: Description

Class Summary

Class	Description
KerberosEndpoint	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.
KerberosServerEndpoint	A ServerEndpoint implementation that uses Kerberos as the underlying network security protocol to support security related invocation constraints for remote requests.
KerberosTrustVerifier	Trust verifier for verifying the Jini extensible remote invocation (Jini ERI) endpoints of type KerberosEndpoint, and principals of type KerberosPrincipal.

Package net.jini.jeri.kerberos Description

Provides implementations of Endpoint and 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 KerberosServerEndpoint, while the client side Endpoint abstraction is implemented by the KerberosEndpoint.

The package also includes the KerberosTrustVerifier for establishing trust in remote proxies that use instances of the KerberosEndpoint, as well as principals of type 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 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:

• Integrity.YES
• Confidentiality
• ClientAuthentication.YES
• ConnectionAbsoluteTime
• ConnectionRelativeTime, trivially on the server side, 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

Since:

2.0

Version:

2.0

Implementation Specifics:

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 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 KerberosPrincipals and credentials (KerberosTickets or KerberosKeys). 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 AuthPermission("getSubject"), otherwise it throws a generic exception that enumerates possible causes.

Logging

The endpoint classes use the following Logger instances to log information at the following 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.server

Level	Description
WARNING	unexpected failure while accepting connections on the created ServerSocket.
FAILED	problems with permission checking, server principal and Kerberos key presence checking, GSSCredential creation, socket connect exception, 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

Configuration

KDC and realm configuration:

As described in the 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 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.