This interface encapsulates the GSS-API security context and provides
the security services that are available over the context. Security
contexts are established between peers using locally acquired
credentials. Multiple contexts may exist simultaneously between a pair
of peers, using the same or different set of credentials. GSS-API
functions in a manner independent of the underlying transport protocol
and depends on its calling application to transport the tokens that are
generated by the security context between the peers.
If the caller instantiates the context using the default
GSSManager
instance, then the Kerberos v5 GSS-API mechanism
is guaranteed to be available for context establishment. This mechanism
is identified by the Oid "1.2.840.113554.1.2.2" and is defined in RFC
1964.
Before the context establishment phase is initiated, the context
initiator may request specific characteristics desired of the
established context. Not all underlying mechanisms support all
characteristics that a caller might desire. After the context is
established, the caller can check the actual characteristics and services
offered by that context by means of various query methods. When using
the Kerberos v5 GSS-API mechanism offered by the default
GSSManager
instance, all optional services will be
available locally. They are mutual authentication, credential
delegation, confidentiality and integrity protection, and per-message
replay detection and sequencing. Note that in the GSS-API, message integrity
is a prerequisite for message confidentiality.
The context establishment occurs in a loop where the
initiator calls initSecContext
and the acceptor calls acceptSecContext
until the context is established. While in this loop
the initSecContext
and acceptSecContext
methods produce tokens that the application sends over to the peer. The
peer passes any such token as input to its acceptSecContext
or initSecContext
as the case may be.
During the context establishment phase, the isProtReady
method may be called to determine if the
context can be used for the per-message operations of wrap
and getMIC
. This allows applications to use
per-message operations on contexts which aren't yet fully
established.
After the context has been established or the isProtReady
method returns true
, the query routines can be invoked to
determine the actual characteristics and services of the established
context. The application can also start using the per-message methods
of wrap
and
getMIC
to obtain
cryptographic operations on application supplied data.
When the context is no longer needed, the application should call
dispose
to release any system resources the context
may be using.
A security context typically maintains sequencing and replay detection
information about the tokens it processes. Therefore, the sequence in
which any tokens are presented to this context for processing can be
important. Also note that none of the methods in this interface are
synchronized. Therefore, it is not advisable to share a
GSSContext
among several threads unless some application
level synchronization is in place.
Finally, different mechanism providers might place different security
restrictions on using GSS-API contexts. These will be documented by the
mechanism provider. The application will need to ensure that it has the
appropriate permissions if such checks are made in the mechanism layer.
The example code presented below demonstrates the usage of the
GSSContext
interface for the initiating peer. Different
operations on the GSSContext
object are presented,
including: object instantiation, setting of desired flags, context
establishment, query of actual context flags, per-message operations on
application data, and finally context deletion.
// Create a context using default credentials
// and the implementation specific default mechanism
GSSManager manager ...
GSSName targetName ...
GSSContext context = manager.createContext(targetName, null, null,
GSSContext.INDEFINITE_LIFETIME);
// set desired context options prior to context establishment
context.requestConf(true);
context.requestMutualAuth(true);
context.requestReplayDet(true);
context.requestSequenceDet(true);
// establish a context between peers
byte []inToken = new byte[0];
// Loop while there still is a token to be processed
while (!context.isEstablished()) {
byte[] outToken
= context.initSecContext(inToken, 0, inToken.length);
// send the output token if generated
if (outToken != null)
sendToken(outToken);
if (!context.isEstablished()) {
inToken = readToken();
}
// display context information
System.out.println("Remaining lifetime in seconds = "
+ context.getLifetime());
System.out.println("Context mechanism = " + context.getMech());
System.out.println("Initiator = " + context.getSrcName());
System.out.println("Acceptor = " + context.getTargName());
if (context.getConfState())
System.out.println("Confidentiality (i.e., privacy) is available");
if (context.getIntegState())
System.out.println("Integrity is available");
// perform wrap on an application supplied message, appMsg,
// using QOP = 0, and requesting privacy service
byte [] appMsg ...
MessageProp mProp = new MessageProp(0, true);
byte []tok = context.wrap(appMsg, 0, appMsg.length, mProp);
sendToken(tok);
// release the local-end of the context
context.dispose();