|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.sun.gssapi.GSSContext
public class GSSContext
This class represents the JGSS security context and its associated operations. JGSS security contexts are established between peers using locally established credentials. Multiple contexts may exist simultaneously between a pair of peers, using the same or different set of credentials. The JGSS is independent of the underlying transport protocols and depends on its callers to transport the tokens between peers.
The context object can be thought of as having 3 implicit states: before it is established, during its context establishment, and after a fully established context exists.
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 init and accept methods will produce GSS-API authentication tokens which the calling application needs to send to its peer. The init and accept methods may return a CONTINUE_NEEDED code which indicates that a token is needed from its peer in order to continue the context establishment phase. A return code of COMPLETE signals that the local end of the context is established. This may still require that a token be sent to the peer, depending if one is produced by GSS-API. The isEstablished method can also be used to determine if the local end of the context has been fully established. 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 implementation 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.
Field Summary | |
---|---|
static int |
ANON
Context option flag - anonymity. |
static int |
COMPLETE
Return value from either accept or init stating that the context creation phase is complete for this peer. |
static int |
CONF
Context option flag - confidentiality. |
static int |
CONTINUE_NEEDED
Return value from either accept or init stating that another token is required from the peer to continue context creation. |
static int |
CRED_DELEG
Context option flag - credential delegation. |
static int |
INDEFINITE
Indefinite lifetime value for a context. |
static int |
INTG
Context option flag - integrity. |
static int |
MUTUAL_AUTH
Context option flag - mutual authentication. |
static int |
REPLAY_DET
Context option flag - replay detection. |
static int |
SEQUENCE_DET
Context option flag - sequence detection. |
static int |
TRANS
Context option flag - transferability (output flag only). |
Constructor Summary | |
---|---|
GSSContext(byte[] interProcessToken)
Constructor for creating a GSSContext from a previously exported context. |
|
GSSContext(GSSCredential myCred)
Constructor for creating a context on the acceptor' side. |
|
GSSContext(GSSName peer,
Oid mechOid,
GSSCredential myCred,
int lifetime)
Constructor for creating a context on the initiator's side. |
Method Summary | |
---|---|
byte[] |
accept(byte[] inTok,
int offset,
int length)
Called by the context acceptor upon receiving a token from the peer. |
int |
accept(java.io.InputStream inputBuf,
java.io.OutputStream outputBuf)
Called by the context acceptor upon receiving a token from the peer. |
void |
dispose()
Release any system resources and cryptographic information stored in the context object. |
byte[] |
export()
Provided to support the sharing of work between multiple processes. |
boolean |
getAnonymityState()
Returns true if this is an anonymous context. |
boolean |
getConfState()
Returns the confidentiality service state over the context. |
GSSCredential |
getDelegCred()
Returns the delegated credential object on the acceptor's side. |
boolean |
getDelegCredState()
Returns the state of the delegated credentials for the context. |
boolean |
getIntegState()
Returns the integrity service state over the context. |
int |
getLifetime()
Returns the context lifetime in seconds. |
Oid |
getMech()
Returns the mechanism oid for the context. |
byte[] |
getMIC(byte[] inMsg,
int offset,
int length,
MessageProp msgProp)
Returns a token containing a cryptographic MIC for the supplied message, for transfer to the peer application. |
void |
getMIC(java.io.InputStream inBuf,
java.io.OutputStream outBuf,
MessageProp msgProp)
Produces a token containing a cryptographic MIC for the supplied message, for transfer to the peer application. |
boolean |
getMutualAuthState()
Returns the state of the mutual authentication option for the context. |
boolean |
getReplayDetState()
Returns the state of the replay detection service for the context. |
boolean |
getSequenceDetState()
Returns the state of the sequence detection service for the context. |
GSSName |
getSrcName()
Retrieves the name of the context initiator. |
GSSName |
getTargName()
Retrieves the name of the context target (acceptor). |
int |
getWrapSizeLimit(int qop,
boolean confReq,
int maxTokenSize)
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 then maxTokenSize bytes. |
byte[] |
init(byte[] inputBuf,
int offset,
int length)
Called by the context initiator to start the context creation process. |
int |
init(java.io.InputStream inputBuf,
java.io.OutputStream outputBuf)
Called by the context initiator to start the context creation process. |
boolean |
isEstablished()
Returns true is this is a fully established context. |
boolean |
isInitiator()
Returns true if this is the initiator of the context. |
boolean |
isProtReady()
Indicates if the per message operations can be applied over the context. |
boolean |
isTransferable()
Indicates if the context is transferable to other processes through the use of the export method. |
void |
requestAnonymity(boolean state)
Requests anonymous support over the context. |
void |
requestConf(boolean state)
Requests that confidentiality service be available over the context. |
void |
requestCredDeleg(boolean state)
Sets the request state of the credential delegation flag for the context. |
void |
requestInteg(boolean state)
Requests that integrity service be available over the context. |
void |
requestLifetime(int lifetime)
Sets the desired lifetime for the context in seconds. |
void |
requestMutualAuth(boolean state)
Sets the request state of the mutual authentication flag for the context. |
void |
requestReplayDet(boolean state)
Sets the request state of the replay detection service for the context. |
void |
requestSequenceDet(boolean state)
Sets the request state of the sequence checking service for the context. |
void |
setChannelBinding(ChannelBinding cb)
Sets the channel bindings to be used during context establishment. |
byte[] |
unwrap(byte[] inBuf,
int offset,
int length,
MessageProp msgProp)
Used by the peer application to process tokens generated with the wrap call. |
void |
unwrap(java.io.InputStream inBuf,
java.io.OutputStream outBuf,
MessageProp msgProp)
Used by the peer application to process tokens generated with the wrap call. |
void |
verifyMIC(byte[] inTok,
int tokOffset,
int tokLen,
byte[] inMsg,
int msgOffset,
int msgLen,
MessageProp msgProp)
Verifies the cryptographic MIC, contained in the token parameter, over the supplied message. |
void |
verifyMIC(java.io.InputStream inTok,
java.io.InputStream inMsg,
MessageProp msgProp)
Verifies the cryptographic MIC, contained in the token parameter, over the supplied message. |
byte[] |
wrap(byte[] inBuf,
int offset,
int length,
MessageProp msgProp)
Allows to apply per-message security services over the established security context. |
void |
wrap(java.io.InputStream inBuf,
java.io.OutputStream outBuf,
MessageProp msgProp)
Allows to apply per-message security services over the established security context. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final int INDEFINITE
getLifetime()
,
Constant Field Valuespublic static final int COMPLETE
init(byte[], int, int)
,
accept(byte[], int, int)
,
Constant Field Valuespublic static final int CONTINUE_NEEDED
init(byte[], int, int)
,
accept(byte[], int, int)
,
Constant Field Valuespublic static final int CRED_DELEG
public static final int MUTUAL_AUTH
public static final int REPLAY_DET
public static final int SEQUENCE_DET
public static final int ANON
public static final int CONF
public static final int INTG
public static final int TRANS
export()
,
Constant Field ValuesConstructor Detail |
---|
public GSSContext(GSSName peer, Oid mechOid, GSSCredential myCred, int lifetime) throws GSSException
peer
- Name of the target peer.mechOid
- Oid of the desired mechanism;
may be null to indicate the default mechanismmyCred
- the credentials for the initiator; may be
null to indicate desire to use the default credentialslifetime
- the request lifetime, in seconds, for the context
GSSException
- with possible major codes of BAD_NAME,
BAD_MECH, BAD_NAMETYPE.init(byte[], int, int)
public GSSContext(GSSCredential myCred) throws GSSException
myCred
- GSSCredential for the acceptor. Use null to
request usage of default credentials.
GSSException
- with possible major codes of BAD_NAME,
BAD_MECH, BAD_NAMETYPE.accept(byte[], int, int)
public GSSContext(byte[] interProcessToken) throws GSSException
interProcessToken
- the token emitted from export routine
GSSException
- with possible major codes of CONTEXT_EXPIRED,
NO_CONTEXT, DEFECTIVE_TOKEN, UNAVAILABLE, UNAUTHORIZED, FAILUREexport()
Method Detail |
---|
public byte[] init(byte[] inputBuf, int offset, int length) throws GSSException
Upon completion of the context establishment, the available context options may be queried through the get methods.
inputBuf
- token generated by the peer; this parameter is
ignored on the first calloutputBuf
- token generated for the peer; this may be empty
GSSException
- with possible major values of DEFECTIVE_TOKEN,
DEFECTIVE_CREDENTIAL, BAD_SIG, NO_CRED, CREDENTIALS_EXPIRED,
BAD_BINDINGS, OLD_TOKEN, DUPLICATE_ELEMENT, BAD_NAMETYPE, BAD_NAME,
BAD_MECH, and FAILUREinit(InputStream,OutputStream)
,
setChannelBinding(com.sun.gssapi.ChannelBinding)
public int init(java.io.InputStream inputBuf, java.io.OutputStream outputBuf) throws GSSException
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.
inputBuf
- token generated by the peer; this parameter is
ignored on the first calloutputBuf
- token generated for the peer; this may be empty
GSSException
- with possible major values of DEFECTIVE_TOKEN,
DEFECTIVE_CREDENTIAL, BAD_SIG, NO_CRED, CREDENTIALS_EXPIRED,
BAD_BINDINGS, OLD_TOKEN, DUPLICATE_ELEMENT, BAD_NAMETYPE, BAD_NAME,
BAD_MECH, and FAILUREinit(byte[],int,int)
,
accept(byte[],int,int)
,
setChannelBinding(com.sun.gssapi.ChannelBinding)
public byte[] accept(byte[] inTok, int offset, int length) throws GSSException
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.
Please note that the accept method may 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. Called by the context acceptor upon receiving a token from the peer. May need to be called again if returns CONTINUE_NEEDED.
inputToken
- token that was received from the initiatoroutputBut
- token generated for the peer; may be empty
GSSException
- may be thrown with major status values of
DEFECTIVE_TOKEN, DEFECTIVE_CREDENTIAL, BAD_SIG, NO_CRED,
CREDENTIALS_EXPIRED, BAD_BINDINGS, OLD_TOKEN, DUPLICATE_ELEMENT,
BAD_MECH, and FAILUREinit(byte[],int,int)
,
accept(InputStream,OutputStream)
,
setChannelBinding(com.sun.gssapi.ChannelBinding)
public int accept(java.io.InputStream inputBuf, java.io.OutputStream outputBuf) throws GSSException
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.
inputToken
- token that was received from the initiatoroutputBut
- token generated for the peer; may be empty
GSSException
- may be thrown with major status values of
DEFECTIVE_TOKEN, DEFECTIVE_CREDENTIAL, BAD_SIG, NO_CRED,
CREDENTIALS_EXPIRED, BAD_BINDINGS, OLD_TOKEN, DUPLICATE_ELEMENT,
BAD_MECH, and FAILUREaccept(byte[],int,int)
,
init(InputStream,OutputStream)
,
setChannelBinding(com.sun.gssapi.ChannelBinding)
public boolean isEstablished()
public void dispose() throws GSSException
GSSException
- with major codes NO_CONTEXT or FAILUREpublic int getWrapSizeLimit(int qop, boolean confReq, int maxTokenSize) throws GSSException
qop
- quality of protection to apply to the messageconfReq
- boolean indicating if privacy should be appliedmaxTokenSize
- the maximum size of the token to be emitted
from wrap
GSSException
- with the possible major codes of BAD_QOP,
CONTEXT_EXPIRED, and FAILURE.wrap(byte[], int, int, com.sun.gssapi.MessageProp)
public byte[] wrap(byte[] inBuf, int offset, int length, MessageProp msgProp) throws GSSException
Supports the wrapping and unwrapping of zero-length messages.
The application will be responsible for sending the token to the peer.
inBuf
- the application data to be protectedoffset
- the offset in the inBuf where the data beginslength
- the length of the data starting at offsetmsgPro
- indicates the desired QOP and confidentiality state,
and upon return the actual QOP and message confidentiality state
GSSException
- with possible major codes of CONTEXT_EXPIRED,
CREDENTIALS_EXPIRED, BAD_QOP, FAILURE.wrap(InputStream,OutputStream, MessageProp)
,
unwrap(byte[],int,int,MessageProp)
,
MessageProp
public void wrap(java.io.InputStream inBuf, java.io.OutputStream outBuf, MessageProp msgProp) throws GSSException
Supports the wrapping and unwrapping of zero-length messages.
The application will be responsible for sending the token to the peer.
inputBuf
- the application data to be protectedoutputBuf
- the token to be sent to the peermsgPro
- indicates the desired QOP and confidentiality state,
and upon return the actual QOP and message confidentiality state
GSSException
- with possible major codes of CONTEXT_EXPIRED,
CREDENTIALS_EXPIRED, BAD_QOP, FAILURE.#wrap(byte,int,int,MessageProp)
,
unwrap(InputStream,OutputStream,MessageProp)
,
MessageProp
public byte[] unwrap(byte[] inBuf, int offset, int length, MessageProp msgProp) throws GSSException
Supports the wrapping and unwrapping of zero-length messages.
inBuf
- token received from peer application which was
generated by call to wrapoffset
- within the inBuf where the token begins.length
- The length of the token in inBuf.msgProp
- Upon return from the this method, will contain
QOP and privacy state of the supplied message as well as
any supplementary status values.
GSSException
- with possible major codes of DEFECTIVE_TOKEN,
BAD_SIG, CONTEXT_EXPIRED, CREDENTIALS_EXPIRED, and FAILURE.unwrap(InputStream,OutputStream,MessageProp)
,
wrap(byte[],int,int,MessageProp)
,
MessageProp
public void unwrap(java.io.InputStream inBuf, java.io.OutputStream outBuf, MessageProp msgProp) throws GSSException
Supports the wrapping and unwrapping of zero-length messages.
inBuf
- token received from peer application which was
generated by call to wrapoutBuf
- original message passed into wrapmsgProp
- Upon return from the this method, will contain
QOP and privacy state of the supplied message as well as
any supplementary status values.
GSSException
- with possible major codes of DEFECTIVE_TOKEN,
BAD_SIG, CONTEXT_EXPIRED, CREDENTIALS_EXPIRED, and FAILURE.unwrap(byte[],int,int,MessageProp)
,
wrap(InputStream,OutputStream,MessageProp)
,
MessageProp
public byte[] getMIC(byte[] inMsg, int offset, int length, MessageProp msgProp) throws GSSException
Note that privacy can only be applied through the wrap call.
Supports the derivation of MICs from zero-length messages.
inBuf
- message to apply security service tooffset
- The offset within the inMsg where the
token begins.length
- the length of the application messagemsgProp
- Indicates the desired QOP to be used. Use QOP of 0
to indicate default value. The confidentiality flag
is ignored. Upon return from this method, this object
will contain the actual QOP applied (in case 0 was selected).
GSSException
- with possible major codes of CONTEXT_EXPIRED,
BAD_QOP, FAILURE.getMIC(InputStream,OutputStream,MessageProp)
,
#verifyMIC(byte[],int,int,MessageProp)
,
MessageProp
public void getMIC(java.io.InputStream inBuf, java.io.OutputStream outBuf, MessageProp msgProp) throws GSSException
Note that privacy can only be applied through the wrap call.
Supports the derivation of MICs from zero-length messages.
inBuf
- Buffer containing the message to generate MIC over.outBuf
- The buffer to write the GSS-API output token into.msgProp
- Indicates the desired QOP to be used. Use QOP of 0
to indicate default value. The confidentiality flag
is ignored. Upon return from this method, this object
will contain the actual QOP applied (in case 0 was selected).
GSSException
- with possible major codes of CONTEXT_EXPIRED,
BAD_QOP, FAILURE.getMIC(byte[],int,int,MessageProp)
,
verifyMIC(byte[],int,int,byte[],int,int,MessageProp)
,
MessageProp
public void verifyMIC(byte[] inTok, int tokOffset, int tokLen, byte[] inMsg, int msgOffset, int msgLen, MessageProp msgProp) throws GSSException
inTok
- token generated by peer's getMIC methodtokOffset
- the offset within the inTok where the token beginstokLen
- the length of the tokeninMsg
- Application message to verify the Cryptographic MIC
over.msgOffset
- the offset within the inMsg where the message
beginsmsgLen
- the length of the messagemsgProp
- upon return from this method, this object
will contain the applied QOP and supplementary status
values for the supplied token. The privacy state will
always be set to false.
GSSException
- with possible major codes DEFECTIVE_TOKEN,
BAD_SIG, CONTEXT_EXPIREDverifyMIC(InputStream,InputStream,MessageProp)
,
wrap(byte[],int,int,MessageProp)
,
MessageProp
public void verifyMIC(java.io.InputStream inTok, java.io.InputStream inMsg, MessageProp msgProp) throws GSSException
inputTok
- Contains the token generated by peer's getMIC
method.inputMsg
- Contains application message to verify the
cryptographic MIC over.msgProp
- upon return from this method, this object
will contain the applied QOP and supplementary statustatus
values for the supplied token. The privacy state will
always be set to false.
GSSException
- with possible major codes DEFECTIVE_TOKEN,
BAD_SIG, CONTEXT_EXPIREDverifyMIC(byte[],int,int,byte[],int,int,MessageProp)
,
#wrap(InputStream,OutputStream)
,
MessageProp
public byte[] export() throws GSSException
This method deactivates the security context and creates an interprocess token which, when passed to the byte array constructor of the GSSContext class 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.
GSSException
- with possible major codes of UNAVAILABLE,
CONTEXT_EXPIRED, NO_CONTEXT, FAILURE.GSSContext(byte[])
,
isTransferable()
public void requestMutualAuth(boolean state) throws GSSException
Boolean
- representing if mutual authentication
should be requested during context establishment.
GSSException
- may be throwngetMutualAuthState()
public void requestReplayDet(boolean state) throws GSSException
Boolean
- representing if replay detection is desired
over the established context.
GSSException
- may be throwngetReplayDetState()
public void requestSequenceDet(boolean state) throws GSSException
Boolean
- representing if sequence checking service
is desired over the established context.
GSSException
- may be throwngetSequenceDetState()
public void requestCredDeleg(boolean state) throws GSSException
Boolean
- representing if credential delegation is desired.
GSSException
- may be throwngetDelegCredState()
public void requestAnonymity(boolean state) throws GSSException
Boolean
- representing if anonymity support is desired.
GSSException
- may be throwngetAnonymityState()
public void requestConf(boolean state) throws GSSException
Boolean
- indicating if confidentiality services are to
be requested for the context.
GSSException
- may be throwngetConfState()
public void requestInteg(boolean state) throws GSSException
Boolean
- indicating if integrity services are to
be requested for the context.
GSSException
- may be throwngetIntegState()
public void requestLifetime(int lifetime) throws GSSException
The
- desired context lifetime in seconds.
GSSException
- may be throwngetLifetime()
public void setChannelBinding(ChannelBinding cb) throws GSSException
Channel
- binding to be used.
GSSException
- may be thrownChannelBinding
public boolean getDelegCredState()
requestCredDeleg(boolean)
,
isProtReady()
public boolean getMutualAuthState()
requestMutualAuth(boolean)
,
isProtReady()
public boolean getReplayDetState()
requestReplayDet(boolean)
,
isProtReady()
public boolean getSequenceDetState()
requestSequenceDet(boolean)
,
isProtReady()
public boolean getAnonymityState()
requestAnonymity(boolean)
,
isProtReady()
public boolean isTransferable() throws GSSException
GSSException
- may be thrownexport()
public boolean isProtReady()
public boolean getConfState()
requestConf(boolean)
,
isProtReady()
public boolean getIntegState()
requestInteg(boolean)
,
isProtReady()
public int getLifetime()
requestLifetime(int)
,
isProtReady()
public GSSName getSrcName() throws GSSException
GSSException
- with possible major codes of CONTEXT_EXPIRED
and FAILUREisProtReady()
public GSSName getTargName() throws GSSException
GSSException
- with possible major codes of
CONTEXT_EXPIRED and FAILUREisProtReady()
public Oid getMech() throws GSSException
GSSException
- may be thrown when the mechanism
oid can't be determinedpublic GSSCredential getDelegCred() throws GSSException
GSSException
- with possible major codes of
CONTEXT_EXPIRED and FAILUREgetDelegCredState()
public boolean isInitiator() throws GSSException
GSSException
- with possible major codes of
CONTEXT_EXPIRED and FAILURE
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |