method that will allow the creation of duplicate credentials. This
is useful when called just before the add() call to retain a copy of
the original credential.
6.3.1. Example Code
This example code demonstrates the creation of a GSSCredential
implementation for a specific entity, querying of its fields, and its
release when it is no longer needed.
GSSManager mgr = GSSManager.getInstance();
// start by creating a name object for the entity
GSSName name = mgr.createName("userName", GSSName.NT_USER_NAME);
// now acquire credentials for the entity
GSSCredential cred = mgr.createCredential(name,
GSSCredential.ACCEPT_ONLY);
// display credential information - name, remaining lifetime,
// and the mechanisms it has been acquired over
print(cred.getName().toString());
print(cred.getRemainingLifetime());
Oid [] mechs = cred.getMechs();
if (mechs != null) {
for (int i = 0; i < mechs.length; i++)
print(mechs[i].toString());
}
// release system resources held by the credential
cred.dispose();
6.3.2. Static Constants
public static final int INITIATE_AND_ACCEPT
Credential usage flag requesting that it be able to be used for both
context initiation and acceptance.
public static final int INITIATE_ONLY
Credential usage flag requesting that it be able to be used for
context initiation only.
public static final int ACCEPT_ONLY
Credential usage flag requesting that it be able to be used for
context acceptance only.
public static final int DEFAULT_LIFETIME
A lifetime constant representing the default credential lifetime.
This value must be set to 0.
public static final int INDEFINITE_LIFETIME
A lifetime constant representing indefinite credential lifetime.
This value must be set to the maximum integer value in Java -
Integer.MAX_VALUE.
6.3.3. dispose
public void dispose() throws GSSException
Releases any sensitive information that the GSSCredential object may
be containing. Applications should call this method as soon as the
credential is no longer needed to minimize the time any sensitive
information is maintained.
6.3.4. getName
public GSSName getName() throws GSSException
Retrieves the name of the entity that the credential asserts.
6.3.5. getName
public GSSName getName(Oid mechOID) throws GSSException
Retrieves a mechanism name of the entity that the credential asserts.
Equivalent to calling canonicalize() on the name returned by 7.3.3.
Parameters:
mechOID The mechanism for which information should be
returned.
6.3.6. getRemainingLifetime
public int getRemainingLifetime() throws GSSException
Returns the remaining lifetime in seconds for a credential. The
remaining lifetime is the minimum lifetime for any of the underlying
credential mechanisms. A return value of
GSSCredential.INDEFINITE_LIFETIME indicates that the credential does
not expire. A return value of 0 indicates that the credential is
already expired.
6.3.7. getRemainingInitLifetime
public int getRemainingInitLifetime(Oid mech) throws GSSException
Returns the remaining lifetime is seconds for the credential to
remain capable of initiating security contexts under the specified
mechanism. A return value of GSSCredential.INDEFINITE_LIFETIME
indicates that the credential does not expire for context initiation.
A return value of 0 indicates that the credential is already expired.
Parameters:
mechOID The mechanism for which information should be
returned.
6.3.8. getRemainingAcceptLifetime
public int getRemainingAcceptLifetime(Oid mech) throws GSSException
Returns the remaining lifetime is seconds for the credential to
remain capable of accepting security contexts under the specified
mechanism. A return value of GSSCredential.INDEFINITE_LIFETIME
indicates that the credential does not expire for context acceptance.
A return value of 0 indicates that the credential is already expired.
Parameters:
mechOID The mechanism for which information should be
returned.
6.3.9. getUsage
public int getUsage() throws GSSException
Returns the credential usage flag. The return value will be one of
GSSCredential.INITIATE_ONLY, GSSCredential.ACCEPT_ONLY, or
GSSCredential.INITIATE_AND_ACCEPT.
6.3.10. getUsage
public int getUsage(Oid mechOID) throws GSSException
Returns the credential usage flag for the specified credential
mechanism. The return value will be one of
GSSCredential.INITIATE_ONLY, GSSCredential.ACCEPT_ONLY, or
GSSCredential.INITIATE_AND_ACCEPT.
Parameters:
mechOID The mechanism for which information should be
returned.
6.3.11. getMechs
public Oid[] getMechs() throws GSSException
Returns an array of mechanisms supported by this credential.
6.3.12. add
public void add(GSSName aName, int initLifetime, int acceptLifetime,
Oid mech, int usage) throws GSSException
Adds a mechanism specific credential-element to an existing
credential. This method allows the construction of credentials one
mechanism at a time.
This routine is envisioned to be used mainly by context acceptors
during the creation of acceptance credentials which are to be used
with a variety of clients using different security mechanisms.
This routine adds the new credential element "in-place". To add the
element in a new credential, first call clone() to obtain a copy of
this credential, then call its add() method.
Parameters:
aName Name of the principal for whom this credential is to
be acquired. Use "null" to specify the default
principal.
initLifetime
The number of seconds that credentials should remain
valid for initiating of security contexts. Use
GSSCredential.INDEFINITE_LIFETIME to request that the
credentials have the maximum permitted lifetime. Use
GSSCredential.DEFAULT_LIFETIME to request default
credential lifetime.
acceptLifetime
The number of seconds that credentials should remain
valid for accepting of security contexts. Use
GSSCredential.INDEFINITE_LIFETIME to request that the
credentials have the maximum permitted lifetime. Use
GSSCredential.DEFAULT_LIFETIME to request default
credential lifetime.
mech The mechanisms over which the credential is to be
acquired.
usage The intended usage for this credential object. The
value of this parameter must be one of:
GSSCredential.ACCEPT_AND_INITIATE,
GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY
6.3.13. equals
public boolean equals(Object another)
Tests if this GSSCredential refers to the same entity as the supplied
object. The two credentials must be acquired over the same
mechanisms and must refer to the same principal. Returns "true" if
the two GSSCredentials refer to the same entity; "false" otherwise.
(Note that the Java language specification requires that two objects
that are equal according to the equals(Object) method must return the
same integer result when the hashCode() method is called on them.)
Parameters:
another Another GSSCredential object for comparison.
6.4. public interface GSSContext
This interface encapsulates the GSS-API security context and provides
the security services (wrap, unwrap, getMIC, verifyMIC) 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 its tokens between peers.
Before the context establishment phase is initiated, the context
initiator may request specific characteristics desired of the
established context. These can be set using the set methods. After
the context is established, the caller can check the actual
characteristic and services offered by the context using the query
methods.
The context establishment phase begins with the first call to the
init method by the context initiator. During this phase the
initSecContext and acceptSecContext methods will produce GSS-API
authentication tokens which the calling application needs to send to
its peer. If an error occurs at any point, an exception will get
thrown and the code will start executing in a catch block. If not,
the normal flow of code continues and the application can make a call
to the isEstablished() method. If this method returns false it
indicates that a token is needed from its peer in order to continue
the context establishment phase. A return value of true signals that
the local end of the context is established. This may still require
that a token be sent to the peer, if one is produced by GSS-API.
During the context establishment phase, the isProtReady() method may
be called to determine if the context can be used for the per-message
operations. This allows applications to use per-message operations
on contexts which aren't 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.
6.4.1. Example Code
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.
GSSManager mgr = GSSManager.getInstance();
// start by creating the name for a service entity
GSSName targetName = mgr.createName("service@host",
GSSName.NT_HOSTBASED_SERVICE);
// create a context using default credentials for the above entity
// and the implementation specific default mechanism
GSSContext context = mgr.createContext(targetName,
null, /* default mechanism */
null, /* default credentials */
GSSContext.INDEFINITE_LIFETIME);
// set desired context options - all others are false by default
context.requestConf(true);
context.requestMutualAuth(true);
context.requestReplayDet(true);
context.requestSequenceDet(true);
// establish a context between peers - using byte arrays
byte []inTok = new byte[0];
try {
do {
byte[] outTok = context.initSecContext(inTok, 0,
inTok.length);
// send the token if present
if (outTok != null)
sendToken(outTok);
// check if we should expect more tokens
if (context.isEstablished())
break;
// another token expected from peer
inTok = readToken();
} while (true);
} catch (GSSException e) {
print("GSSAPI error: " + e.getMessage());
}
// display context information
print("Remaining lifetime in seconds = " + context.getLifetime());
print("Context mechanism = " + context.getMech().toString());
print("Initiator = " + context.getSrcName().toString());
print("Acceptor = " + context.getTargName().toString());
if (context.getConfState())
print("Confidentiality security service available");
if (context.getIntegState())
print("Integrity security service 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);
if (mProp.getPrivacy())
print("Message protected with privacy.");
sendToken(tok);
// release the local-end of the context
context.dispose();
6.4.2. Static Constants
public static final int DEFAULT_LIFETIME
A lifetime constant representing the default context lifetime. This
value must be set to 0.
public static final int INDEFINITE_LIFETIME
A lifetime constant representing indefinite context lifetime. This
value must be set to the maximum integer value in Java -
Integer.MAX_VALUE.
6.4.3. initSecContext
public byte[] initSecContext(byte inputBuf[], int offset, int len)
throws GSSException
Called by the context initiator to start the context creation
process. This is equivalent to the stream based method except that
the token buffers are handled as byte arrays instead of using stream
objects. This method may return an output token which the
application will need to send to the peer for processing by the
accept call. Typically, the application would do so by calling the
flush() method on an OutputStream that encapsulates the connection
between the two peers. The application can call isEstablished() to
determine if the context establishment phase is complete for this
peer. A return value of "false" from isEstablished() indicates that
more tokens are expected to be supplied to the initSecContext()
method. Note that it is possible that the initSecContext() method
return a token for the peer, and isEstablished() return "true" also.
This indicates that the token needs to be sent to the peer, but the
local end of the context is now fully established.
Upon completion of the context establishment, the available context
options may be queried through the get methods.
Parameters:
inputBuf Token generated by the peer. This parameter is ignored
on the first call.
offset The offset within the inputBuf where the token begins.
len The length of the token within the inputBuf (starting
at the offset).
6.4.3.1. Example Code
// Create a new GSSContext implementation object.
// GSSContext wrapper implements interface GSSContext.
GSSContext context = mgr.createContext(...);
byte []inTok = new byte[0];
try {
do {
byte[] outTok = context.initSecContext(inTok, 0,
inTok.length);
// send the token if present
if (outTok != null)
sendToken(outTok);
// check if we should expect more tokens
if (context.isEstablished())
break;
// another token expected from peer
inTok = readToken();
} while (true);
} catch (GSSException e) {
print("GSSAPI error: " + e.getMessage());
}
6.4.4. initSecContext
public int initSecContext(InputStream inStream,
OutputStream outStream) throws GSSException
Called by the context initiator to start the context creation
process. This is equivalent to the byte array based method. This
method may write an output token to the outStream, which the
application will need to send to the peer for processing by the
accept call. Typically, the application would do so by calling the
flush() method on an OutputStream that encapsulates the connection
between the two peers. The application can call isEstablished() to
determine if the context establishment phase is complete for this
peer. A return value of "false" from isEstablished indicates that
more tokens are expected to be supplied to the initSecContext method.
Note that it is possible that the initSecContext() method return a
token for the peer, and isEstablished() return "true" also. This
indicates that the token needs to be sent to the peer, but the local
end of the context is now fully established.
The GSS-API authentication tokens contain a definitive start and end.
This method will attempt to read one of these tokens per invocation,
and may block on the stream if only part of the token is available.
Upon completion of the context establishment, the available context
options may be queried through the get methods.
Parameters:
inStream Contains the token generated by the peer. This
parameter is ignored on the first call.
outStream Output stream where the output token will be written.
During the final stage of context establishment, there
may be no bytes written.
6.4.4.1. Example Code
This sample code merely demonstrates the token exchange during the
context establishment phase. It is expected that most Java
applications will use custom implementations of the Input and Output
streams that encapsulate the communication routines. For instance, a
simple read on the application InputStream, when called by the
Context, might cause a token to be read from the peer, and a simple
flush() on the application OutputStream might cause a previously
written token to be transmitted to the peer.
// Create a new GSSContext implementation object.
// GSSContext wrapper implements interface GSSContext.
GSSContext context = mgr.createContext(...);
// use standard java.io stream objects
ByteArrayOutputStream os = new ByteArrayOutputStream();
ByteArrayInputStream is = null;
try {
do {
context.initSecContext(is, os);
// send token if present
if (os.size() > 0)
sendToken(os);
// check if we should expect more tokens
if (context.isEstablished())
break;
// another token expected from peer
is = recvToken();
} while (true);
} catch (GSSException e) {
print("GSSAPI error: " + e.getMessage());
}
6.4.5. acceptSecContext
public byte[] acceptSecContext(byte inTok[], int offset, int len)
throws GSSException
Called by the context acceptor upon receiving a token from the peer.
This call is equivalent to the stream based method except that the
token buffers are handled as byte arrays instead of using stream
objects.
This method may return an output token which the application will
need to send to the peer for further processing by the init call.
"null" return value indicates that no token needs to be sent to the
peer. The application can call isEstablished() to determine if the
context establishment phase is complete for this peer. A return
value of "false" from isEstablished() indicates that more tokens are
expected to be supplied to this method.
Note that it is possible that acceptSecContext() return a token for
the peer, and isEstablished() return "true" also. This indicates
that the token needs to be sent to the peer, but the local end of the
context is now fully established.
Upon completion of the context establishment, the available context
options may be queried through the get methods.
Parameters:
inTok Token generated by the peer.
offset The offset within the inTok where the token begins.
len The length of the token within the inTok (starting at
the offset).
6.4.5.1. Example Code
// acquire server credentials
GSSCredential server = mgr.createCredential(...);
// create acceptor GSS-API context from the default provider
GSSContext context = mgr.createContext(server, null);
try {
do {
byte [] inTok = readToken();
byte []outTok = context.acceptSecContext(inTok, 0,
inTok.length);
// possibly send token to peer
if (outTok != null)
sendToken(outTok);
// check if local context establishment is complete
if (context.isEstablished())
break;
} while (true);
} catch (GSSException e) {
print("GSS-API error: " + e.getMessage());
}
6.4.6. acceptSecContext
public void acceptSecContext(InputStream inStream,
OutputStream outStream) throws GSSException
Called by the context acceptor upon receiving a token from the peer.
This call is equivalent to the byte array method. It may write an
output token to the outStream, which the application will need to
send to the peer for processing by its initSecContext method.
Typically, the application would do so by calling the flush() method
on an OutputStream that encapsulates the connection between the two
peers. The application can call isEstablished() to determine if the
context establishment phase is complete for this peer. A return
value of "false" from isEstablished() indicates that more tokens are
expected to be supplied to this method.
Note that it is possible that acceptSecContext() return a token for
the peer, and isEstablished() return "true" also. This indicates
that the token needs to be sent to the peer, but the local end of the
context is now fully established.
The GSS-API authentication tokens contain a definitive start and end.
This method will attempt to read one of these tokens per invocation,
and may block on the stream if only part of the token is available.
Upon completion of the context establishment, the available context
options may be queried through the get methods.
Parameters:
inStream Contains the token generated by the peer.
outStream Output stream where the output token will be written.
During the final stage of context establishment, there
may be no bytes written.
6.4.6.1. Example Code
This sample code merely demonstrates the token exchange during the
context establishment phase. It is expected that most Java
applications will use custom implementations of the Input and Output
streams that encapsulate the communication routines. For instance, a
simple read on the application InputStream, when called by the
Context, might cause a token to be read from the peer, and a simple
flush() on the application OutputStream might cause a previously
written token to be transmitted to the peer.
// acquire server credentials
GSSCredential server = mgr.createCredential(...);
// create acceptor GSS-API context from the default provider
GSSContext context = mgr.createContext(server, null);
// use standard java.io stream objects
ByteArrayOutputStream os = new ByteArrayOutputStream();
ByteArrayInputStream is = null;
try {
do {
is = recvToken();
context.acceptSecContext(is, os);
// possibly send token to peer
if (os.size() > 0)
sendToken(os);
// check if local context establishment is complete
if (context.isEstablished())
break;
} while (true);
} catch (GSSException e) {
print("GSS-API error: " + e.getMessage());
}
6.4.7. isEstablished
public boolean isEstablished()
Used during context establishment to determine the state of the
context. Returns "true" if this is a fully established context on
the caller's side and no more tokens are needed from the peer.
Should be called after a call to initSecContext() or
acceptSecContext() when no GSSException is thrown.
6.4.8. dispose
public void dispose() throws GSSException
Releases any system resources and cryptographic information stored in
the context object. This will invalidate the context.
6.4.9. getWrapSizeLimit
public int getWrapSizeLimit(int qop, boolean confReq,
int maxTokenSize) throws GSSException
Returns the maximum message size that, if presented to the wrap
method with the same confReq and qop parameters, will result in an
output token containing no more than the maxTokenSize bytes.
This call is intended for use by applications that communicate over
protocols that impose a maximum message size. It enables the
application to fragment messages prior to applying protection.
GSS-API implementations are recommended but not required to detect
invalid QOP values when getWrapSizeLimit is called. This routine
guarantees only a maximum message size, not the availability of
specific QOP values for message protection.
Successful completion of this call does not guarantee that wrap will
be able to protect a message of the computed length, since this
ability may depend on the availability of system resources at the
time that wrap is called. However, if the implementation itself
imposes an upper limit on the length of messages that may be
processed by wrap, the implementation should not return a value that
is greater than this length.
Parameters:
qop Indicates the level of protection wrap will be asked
to provide.
confReq Indicates if wrap will be asked to provide privacy
service.
maxTokenSize
The desired maximum size of the token emitted by wrap.
6.4.10. wrap
public byte[] wrap(byte inBuf[], int offset, int len,
MessageProp msgProp) throws GSSException
Applies per-message security services over the established security
context. The method will return a token with a cryptographic MIC and
may optionally encrypt the specified inBuf. This method is
equivalent in functionality to its stream counterpart. The returned
byte array will contain both the MIC and the message.
The MessageProp object is instantiated by the application and used to
specify a QOP value which selects cryptographic algorithms, and a
privacy service to optionally encrypt the message. The underlying
mechanism that is used in the call may not be able to provide the
privacy service. It sets the actual privacy service that it does
provide in this MessageProp object which the caller should then query
upon return. If the mechanism is not able to provide the requested
QOP, it throws a GSSException with the BAD_QOP code.
Since some application-level protocols may wish to use tokens emitted
by wrap to provide "secure framing", implementations should support
the wrapping of zero-length messages.
The application will be responsible for sending the token to the
peer.
Parameters:
inBuf Application data to be protected.
offset The offset within the inBuf where the data begins.
len The length of the data within the inBuf (starting at
the offset).
msgProp Instance of MessageProp that is used by the
application to set the desired QOP and privacy state.
Set the desired QOP to 0 to request the default QOP.
Upon return from this method, this object will contain
the the actual privacy state that was applied to the
message by the underlying mechanism.
6.4.11. wrap
public void wrap(InputStream inStream, OutputStream outStream,
MessageProp msgProp) throws GSSException
Allows to apply per-message security services over the established
security context. The method will produce a token with a
cryptographic MIC and may optionally encrypt the message in inStream.
The outStream will contain both the MIC and the message.
The MessageProp object is instantiated by the application and used to
specify a QOP value which selects cryptographic algorithms, and a
privacy service to optionally encrypt the message. The underlying
mechanism that is used in the call may not be able to provide the
privacy service. It sets the actual privacy service that it does
provide in this MessageProp object which the caller should then query
upon return. If the mechanism is not able to provide the requested
QOP, it throws a GSSException with the BAD_QOP code.
Since some application-level protocols may wish to use tokens emitted
by wrap to provide "secure framing", implementations should support
the wrapping of zero-length messages.
The application will be responsible for sending the token to the
peer.
Parameters:
inStream Input stream containing the application data to be
protected.
outStream The output stream to write the protected message to.
The application is responsible for sending this to the
other peer for processing in its unwrap method.
msgProp Instance of MessageProp that is used by the
application to set the desired QOP and privacy state.
Set the desired QOP to 0 to request the default QOP.
Upon return from this method, this object will contain
the the actual privacy state that was applied to the
message by the underlying mechanism.
6.4.12. unwrap
public byte [] unwrap(byte[] inBuf, int offset, int len,
MessageProp msgProp) throws GSSException
Used by the peer application to process tokens generated with the
wrap call. This call is equal in functionality to its stream
counterpart. The method will return the message supplied in the peer
application to the wrap call, verifying the embedded MIC.
The MessageProp object is instantiated by the application and is used
by the underlying mechanism to return information to the caller such
as the QOP, whether confidentiality was applied to the message, and
other supplementary message state information.
Since some application-level protocols may wish to use tokens emitted
by wrap to provide "secure framing", implementations should support
the wrapping and unwrapping of zero-length messages.
Parameters:
inBuf GSS-API wrap token received from peer.
offset The offset within the inBuf where the token begins.
len The length of the token within the inBuf (starting at
the offset).
msgProp Upon return from the method, this object will contain
the applied QOP, the privacy state of the message, and
supplementary information described in 4.12.3 stating
whether the token was a duplicate, old, out of
sequence or arriving after a gap.
6.4.13. unwrap
public void unwrap(InputStream inStream, OutputStream outStream,
MessageProp msgProp) throws GSSException
Used by the peer application to process tokens generated with the
wrap call. This call is equal in functionality to its byte array
counterpart. It will produce the message supplied in the peer
application to the wrap call, verifying the embedded MIC.
The MessageProp object is instantiated by the application and is used
by the underlying mechanism to return information to the caller such
as the QOP, whether confidentiality was applied to the message, and
other supplementary message state information.
Since some application-level protocols may wish to use tokens emitted
by wrap to provide "secure framing", implementations should support
the wrapping and unwrapping of zero-length messages.
Parameters:
inStream Input stream containing the GSS-API wrap token
received from the peer.
outStream The output stream to write the application message to.
msgProp Upon return from the method, this object will contain
the applied QOP, the privacy state of the message, and
supplementary information described in 4.12.3 stating
whether the token was a duplicate, old, out of
sequence or arriving after a gap.
6.4.14. getMIC
public byte[] getMIC(byte []inMsg, int offset, int len,
MessageProp msgProp) throws GSSException
Returns a token containing a cryptographic MIC for the supplied
message, for transfer to the peer application. Unlike wrap, which
encapsulates the user message in the returned token, only the message
MIC is returned in the output token. This method is identical in
functionality to its stream counterpart.
Note that privacy can only be applied through the wrap call.
Since some application-level protocols may wish to use tokens emitted
by getMIC to provide "secure framing", implementations should support
derivation of MICs from zero-length messages.
Parameters:
inMsg Message to generate MIC over.
offset The offset within the inMsg where the token begins.
len The length of the token within the inMsg (starting at
the offset).
msgProp Instance of MessageProp that is used by the
application to set the desired QOP. Set the desired
QOP to 0 in msgProp to request the default QOP.
Alternatively pass in "null" for msgProp to request
default QOP.
6.4.15. getMIC
public void getMIC(InputStream inStream, OutputStream outStream,
MessageProp msgProp) throws GSSException
Produces a token containing a cryptographic MIC for the supplied
message, for transfer to the peer application. Unlike wrap, which
encapsulates the user message in the returned token, only the message
MIC is produced in the output token. This method is identical in
functionality to its byte array counterpart.
Note that privacy can only be applied through the wrap call.
Since some application-level protocols may wish to use tokens emitted
by getMIC to provide "secure framing", implementations should support
derivation of MICs from zero-length messages.
Parameters:
inStream inStream Input stream containing the message to
generate MIC over.
outStream outStream Output stream to write the GSS-API output
token to.
msgProp Instance of MessageProp that is used by the
application to set the desired QOP. Set the desired
QOP to 0 in msgProp to request the default QOP.
Alternatively pass in "null" for msgProp to request
default QOP.
6.4.16. verifyMIC
public void verifyMIC(byte []inTok, int tokOffset, int tokLen,
byte[] inMsg, int msgOffset, int msgLen,
MessageProp msgProp) throws GSSException
Verifies the cryptographic MIC, contained in the token parameter,
over the supplied message. This method is equivalent in
functionality to its stream counterpart.
The MessageProp object is instantiated by the application and is used
by the underlying mechanism to return information to the caller such
as the QOP indicating the strength of protection that was applied to
the message and other supplementary message state information.
Since some application-level protocols may wish to use tokens emitted
by getMIC to provide "secure framing", implementations should support
the calculation and verification of MICs over zero-length messages.
Parameters:
inTok Token generated by peer's getMIC method.
tokOffset The offset within the inTok where the token begins.
tokLen The length of the token within the inTok (starting at
the offset).
inMsg Application message to verify the cryptographic MIC
over.
msgOffset The offset within the inMsg where the message begins.
msgLen The length of the message within the inMsg (starting
at the offset).
msgProp Upon return from the method, this object will contain
the applied QOP and supplementary information
described in 4.12.3 stating whether the token was a
duplicate, old, out of sequence or arriving after a
gap. The confidentiality state will be set to
"false".
6.4.17. verifyMIC
public void verifyMIC(InputStream tokStream, InputStream msgStream,
MessageProp msgProp) throws GSSException
Verifies the cryptographic MIC, contained in the token parameter,
over the supplied message. This method is equivalent in
functionality to its byte array counterpart.
The MessageProp object is instantiated by the application and is used
by the underlying mechanism to return information to the caller such
as the QOP indicating the strength of protection that was applied to
the message and other supplementary message state information.
Since some application-level protocols may wish to use tokens emitted
by getMIC to provide "secure framing", implementations should support
the calculation and verification of MICs over zero-length messages.
Parameters:
tokStream Input stream containing the token generated by peer's
getMIC method.
msgStream Input stream containing the application message to
verify the cryptographic MIC over.
msgProp Upon return from the method, this object will contain
the applied QOP and supplementary information
described in 4.12.3 stating whether the token was a
duplicate, old, out of sequence or arriving after a
gap. The confidentiality state will be set to
"false".
6.4.18. export
public byte [] export() throws GSSException
Provided to support the sharing of work between multiple processes.
This routine will typically be used by the context-acceptor, in an
application where a single process receives incoming connection
requests and accepts security contexts over them, then passes the
established context to one or more other processes for message
exchange.
This method deactivates the security context and creates an
interprocess token which, when passed to the byte array constructor
of the GSSContext interface in another process, will re-activate the
context in the second process. Only a single instantiation of a
given context may be active at any one time; a subsequent attempt by
a context exporter to access the exported security context will fail.
The implementation may constrain the set of processes by which the
interprocess token may be imported, either as a function of local
security policy, or as a result of implementation decisions. For
example, some implementations may constrain contexts to be passed
only between processes that run under the same account, or which are
part of the same process group.
The interprocess token may contain security-sensitive information
(for example cryptographic keys). While mechanisms are encouraged to
either avoid placing such sensitive information within interprocess
tokens, or to encrypt the token before returning it to the
application, in a typical GSS-API implementation this may not be
possible. Thus the application must take care to protect the
interprocess token, and ensure that any process to which the token is
transferred is trustworthy.
6.4.19. requestMutualAuth
public void requestMutualAuth(boolean state) throws GSSException
Sets the request state of the mutual authentication flag for the
context. This method is only valid before the context creation
process begins and only for the initiator.
Parameters:
state Boolean representing if mutual authentication should
be requested during context establishment.
6.4.20. requestReplayDet
public void requestReplayDet(boolean state) throws GSSException
Sets the request state of the replay detection service for the
context. This method is only valid before the context creation
process begins and only for the initiator.
Parameters:
state Boolean representing if replay detection is desired
over the established context.
6.4.21. requestSequenceDet
public void requestSequenceDet(boolean state) throws GSSException
Sets the request state for the sequence checking service of the
context. This method is only valid before the context creation
process begins and only for the initiator.
Parameters:
state Boolean representing if sequence detection is desired
over the established context.
6.4.22. requestCredDeleg
public void requestCredDeleg(boolean state) throws GSSException
Sets the request state for the credential delegation flag for the
context. This method is only valid before the context creation
process begins and only for the initiator.
Parameters:
state Boolean representing if credential delegation is
desired.
6.4.23. requestAnonymity
public void requestAnonymity(boolean state) throws GSSException
Requests anonymous support over the context. This method is only
valid before the context creation process begins and only for the
initiator.
Parameters:
state Boolean representing if anonymity support is
requested.
6.4.24. requestConf
public void requestConf(boolean state) throws GSSException
Requests that confidentiality service be available over the context.
This method is only valid before the context creation process begins
and only for the initiator.
Parameters:
state Boolean indicating if confidentiality services are to
be requested for the context.
6.4.25. requestInteg
public void requestInteg(boolean state) throws GSSException
Requests that integrity services be available over the context. This
method is only valid before the context creation process begins and
only for the initiator.
Parameters:
state Boolean indicating if integrity services are to be
requested for the context.
6.4.26. requestLifetime
public void requestLifetime(int lifetime) throws GSSException
Sets the desired lifetime for the context in seconds. This method is
only valid before the context creation process begins and only for
the initiator. Use GSSContext.INDEFINITE_LIFETIME and
GSSContext.DEFAULT_LIFETIME to request indefinite or default context
lifetime.
Parameters:
lifetime The desired context lifetime in seconds.
6.4.27. setChannelBinding
public void setChannelBinding(ChannelBinding cb) throws GSSException
Sets the channel bindings to be used during context establishment.
This method is only valid before the context creation process begins.
Parameters:
cb Channel bindings to be used.
6.4.28. getCredDelegState
public boolean getCredDelegState()
Returns the state of the delegated credentials for the context. When
issued before context establishment is completed or when the
isProtReady method returns "false", it returns the desired state,
otherwise it will indicate the actual state over the established
context.
6.4.29. getMutualAuthState
public boolean getMutualAuthState()
Returns the state of the mutual authentication option for the
context. When issued before context establishment completes or when
the isProtReady method returns "false", it returns the desired state,
otherwise it will indicate the actual state over the established
context.
6.4.30. getReplayDetState
public boolean getReplayDetState()
Returns the state of the replay detection option for the context.
When issued before context establishment completes or when the
isProtReady method returns "false", it returns the desired state,
otherwise it will indicate the actual state over the established
context.
6.4.31. getSequenceDetState
public boolean getSequenceDetState()
Returns the state of the sequence detection option for the context.
When issued before context establishment completes or when the
isProtReady method returns "false", it returns the desired state,
otherwise it will indicate the actual state over the established
context.
6.4.32. getAnonymityState
public boolean getAnonymityState()
Returns "true" if this is an anonymous context. When issued before
context establishment completes or when the isProtReady method
returns "false", it returns the desired state, otherwise it will
indicate the actual state over the established context.
6.4.33. isTransferable
public boolean isTransferable() throws GSSException
Returns "true" if the context is transferable to other processes
through the use of the export method. This call is only valid on
fully established contexts.
6.4.34. isProtReady
public boolean isProtReady()
Returns "true" if the per message operations can be applied over the
context. Some mechanisms may allow the usage of per-message
operations before the context is fully established. This will also
indicate that the get methods will return actual context state
characteristics instead of the desired ones.
6.4.35. getConfState
public boolean getConfState()
Returns the confidentiality service state over the context. When
issued before context establishment completes or when the isProtReady
method returns "false", it returns the desired state, otherwise it
will indicate the actual state over the established context.
6.4.36. getIntegState
public boolean getIntegState()
Returns the integrity service state over the context. When issued
before context establishment completes or when the isProtReady method
returns "false", it returns the desired state, otherwise it will
indicate the actual state over the established context.
6.4.37. getLifetime
public int getLifetime()
Returns the context lifetime in seconds. When issued before context
establishment completes or when the isProtReady method returns
"false", it returns the desired lifetime, otherwise it will indicate
the remaining lifetime for the context.
6.4.38. getSrcName
public GSSName getSrcName() throws GSSException
Returns the name of the context initiator. This call is valid only
after the context is fully established or the isProtReady method
returns "true". It is guaranteed to return an MN.
6.4.39. getTargName
public GSSName getTargName() throws GSSException
Returns the name of the context target (acceptor). This call is
valid only after the context is fully established or the isProtReady
method returns "true". It is guaranteed to return an MN.
6.4.40. getMech
public Oid getMech() throws GSSException
Returns the mechanism oid for this context. This method may be called
before the context is fully established, but the mechanism returned
may change on successive calls in negotiated mechanism case.
6.4.41. getDelegCred
public GSSCredential getDelegCred() throws GSSException
Returns the delegated credential object on the acceptor's side. To
check for availability of delegated credentials call
getDelegCredState. This call is only valid on fully established
contexts.
6.4.42. isInitiator
public boolean isInitiator() throws GSSException
Returns "true" if this is the initiator of the context. This call is
only valid after the context creation process has started.
6.5. public class MessageProp
This is a utility class used within the per-message GSSContext
methods to convey per-message properties.
When used with the GSSContext interface's wrap and getMIC methods, an
instance of this class is used to indicate the desired QOP and to
request if confidentiality services are to be applied to caller
supplied data (wrap only). To request default QOP, the value of 0
should be used for QOP.
When used with the unwrap and verifyMIC methods of the GSSContext
interface, an instance of this class will be used to indicate the
applied QOP and confidentiality services over the supplied message.
In the case of verifyMIC, the confidentiality state will always be
"false". Upon return from these methods, this object will also
contain any supplementary status values applicable to the processed
token. The supplementary status values can indicate old tokens, out
of sequence tokens, gap tokens or duplicate tokens.
6.5.1. Constructors
public MessageProp(boolean privState)
Constructor which sets QOP to 0 indicating that the default QOP is
requested.
Parameters:
privState The desired privacy state. "true" for privacy and
"false" for integrity only.
public MessageProp(int qop, boolean privState)
Constructor which sets the values for the qop and privacy state.
Parameters:
qop The desired QOP. Use 0 to request a default QOP.
privState The desired privacy state. "true" for privacy and
"false" for integrity only.
6.5.2. getQOP
public int getQOP()
Retrieves the QOP value.
6.5.3. getPrivacy
public boolean getPrivacy()
Retrieves the privacy state.
6.5.4. getMinorStatus
public int getMinorStatus()
Retrieves the minor status that the underlying mechanism might have
set.
6.5.5. getMinorString
public String getMinorString()
Returns a string explaining the mechanism specific error code. null
will be returned when no mechanism error code has been set.
6.5.6. setQOP
public void setQOP(int qopVal)
Sets the QOP value.
Parameters:
qopVal The QOP value to be set. Use 0 to request a default
QOP value.
6.5.7. setPrivacy
public void setPrivacy(boolean privState)
Sets the privacy state.
Parameters:
privState The privacy state to set.
6.5.8. isDuplicateToken
public boolean isDuplicateToken()
Returns "true" if this is a duplicate of an earlier token.
6.5.9. isOldToken
public boolean isOldToken()
Returns "true" if the token's validity period has expired.
6.5.10. isUnseqToken
public boolean isUnseqToken()
Returns "true" if a later token has already been processed.
6.5.11. isGapToken
public boolean isGapToken()
Returns "true" if an expected per-message token was not received.
6.5.12. setSupplementaryStates
public void setSupplementaryStates(boolean duplicate,
boolean old, boolean unseq, boolean gap,
int minorStatus, String minorString)
This method sets the state for the supplementary information flags
and the minor status in MessageProp. It is not used by the
application but by the GSS implementation to return this information