OpenJDK 1.23 · sun.security.jgss.spi.GSSContextSpi · APIdia, the JavaDoc alternative

This interface is implemented by a mechanism specific instance of a GSS security context. A GSSContextSpi object can be thought of having 3 states: -before initialization -during initialization with its peer -after it is established

The context options can only be requested in state 1. In state 3, the per message operations are available to the callers. The get methods for the context options will return the requested options while in state 1 and 2, and the established values in state 3. Some mechanisms may allow the access to the per-message operations and the context flags before the context is fully established. The isProtReady method is used to indicate that these services are available.

Context establishment tokens are defined in a mechanism independent format in section 3.1 of RFC 2743. The GSS-Framework will add and remove the mechanism independent header portion of this token format depending on whether a token is received or is being sent. The mechanism should only generate or expect to read the inner-context token portion.
On the other hands, tokens used for per-message calls are generated entirely by the mechanism. It is possible that the mechanism chooses to encase inner-level per-message tokens in a header similar to that used for initial tokens, however, this is up to the mechanism to do. The token to/from the per-message calls are opaque to the GSS-Framework.

An attempt has been made to allow for reading the peer's tokens from an InputStream and writing tokens for the peer to an OutputStream. This allows applications to pass in streams that are obtained from their network connections and thus minimize the buffer copies that will happen. This is especially important for tokens generated by wrap() which are proportional in size to the length of the application data being wrapped, and are probably also the most frequently used type of tokens.

It is anticipated that most applications will want to use wrap() in a fashion where they obtain the application bytes to wrap from a byte[] but want to output the wrap token straight to an OutputStream. Similarly, they will want to use unwrap() where they read the token directly form an InputStream but output it to some byte[] for the application to process. Unfortunately the high level GSS bindings do not contain overloaded forms of wrap() and unwrap() that do just this, however we have accommodated those cases here with the expectation that this will be rolled into the high level bindings sooner or later.

Method Summary

Modifier and Type	Method and Description
public byte[]	Returns: any inner-context token required to be sent to the peer as part of a GSS token. The mechanism should not add the mechanism independent part of the token. The GSS-Framework will add that on the way out. acceptSecContext(InputStream contains the inner context token portion of the GSS token received from the peer. is, int the size of the inner context token as read by the GSS-Framework from the mechanism independent GSS-API level header. mechTokenSize) Acceptor's context establishment call.
public void	dispose() Releases context resources and terminates the context between 2 peer.
public byte[]	Returns: exported context token export() Produces a token representing this context.
public boolean	getAnonymityState()
public boolean	getConfState()
public boolean	getCredDelegState()
public GSSCredentialSpi	getDelegCred()
public boolean	getDelegPolicyState()
public boolean	getIntegState()
public int	getLifetime()
public Oid	getMech()
public void	getMIC(InputStream the user-provided message is, OutputStream the token to be sent to the peer along with the message token. The message token is not encapsulated. os, MessageProp on input the desired QOP and output the applied QOP msgProp) Applies per-message integrity services.
public byte[]	getMIC(byte[] inMsg, int offset, int len, MessageProp msgProp)
public boolean	getMutualAuthState()
public Provider	getProvider()
public boolean	getReplayDetState()
public boolean	getSequenceDetState()
public GSSNameSpi	getSrcName()
public GSSNameSpi	getTargName()
public int	Returns: the maximum size for the input message that can be provided to the wrap() method in order to guarantee that these requirements are met. getWrapSizeLimit(int the quality of protection that the context will be asked to provide. qop, boolean a flag indicating whether confidentiality will be requested or not confReq, int the maximum size of the output token maxTokSize) Queries the context for largest data size to accommodate the specified protection and for the token to remain less than maxTokSize.
public byte[]	Returns: any inner-context token required to be sent to the peer as part of a GSS token. The mechanism should not add the mechanism independent part of the token. The GSS-Framework will add that on the way out. initSecContext(InputStream contains the inner context token portion of the GSS token received from the peer. On the first call to initSecContext, there will be no token hence it will be ignored. is, int the size of the inner context token as read by the GSS-Framework from the mechanism independent GSS-API level header. mechTokenSize) Initiator context establishment call.
public Object	Returns: the attribute inquireSecContext(String the type of the attribute requested type) Return the mechanism-specific attribute associated with `type`.
public boolean	isEstablished()
public boolean	isInitiator()
public boolean	isProtReady()
public boolean	isTransferable()
public void	requestAnonymity(boolean state)
public void	requestConf(boolean state)
public void	requestCredDeleg(boolean state)
public void	requestDelegPolicy(boolean state)
public void	requestInteg(boolean state)
public void	requestLifetime(int lifetime)
public void	requestMutualAuth(boolean state)
public void	requestReplayDet(boolean state)
public void	requestSequenceDet(boolean state)
public void	setChannelBinding(ChannelBinding cb)
public void	unwrap(InputStream the token from the peer is, OutputStream unprotected message data os, MessageProp will contain the applied qop and confidentiality of the input token and any informatory status values msgProp) Retrieves the message token previously encapsulated in the wrap call.
public byte[]	unwrap(byte[] inBuf, int offset, int len, MessageProp msgProp) For apps that want simplicity and don't care about buffer copies.
public void	verifyMIC(InputStream token generated by getMIC is, InputStream the message to check integrity for msgStr, MessageProp will contain the applied QOP and confidentiality states of the token as well as any informatory status codes mProp) Checks the integrity of the supplied tokens.
public void	verifyMIC(byte[] inTok, int tokOffset, int tokLen, byte[] inMsg, int msgOffset, int msgLen, MessageProp msgProp)
public void	wrap(InputStream the user-provided message to be protected is, OutputStream the token to be sent to the peer. It includes the message from is with the requested protection. os, MessageProp on input, contains the requested qop and confidentiality state, on output, the applied values msgProp) Provides per-message token encapsulation.
public byte[]	wrap(byte[] inBuf, int offset, int len, MessageProp msgProp) For apps that want simplicity and don't care about buffer copies.

Method Detail

acceptSecContext	back to summary
public byte[] acceptSecContext(InputStream is, int mechTokenSize) throws GSSException Acceptor's context establishment call. This method may be required to be called several times. A CONTINUE_NEEDED return call indicates that more calls are needed after the next token is received from the peer. This method is called by the GSS-Framework when the application calls the acceptSecContext method on the GSSContext implementation that it has a reference to. All overloaded forms of GSSContext.acceptSecContext() can be handled with this mechanism level acceptSecContext. Since the output token from this method is a fixed size, not exceedingly large, and a one time deal, an overloaded form that takes an OutputStream has not been defined. The GSS-Framework can write the returned byte[] to any application provided OutputStream. Similarly, any application input in the form of byte arrays will be wrapped in an input stream by the GSS-Framework and then passed here. The GSS-Framework will strip off the leading mechanism independent GSS-API header. In other words, only the mechanism specific inner-context token of RFC 2743 section 3.1 will be available on the InputStream. Parameters is:InputStream contains the inner context token portion of the GSS token received from the peer. mechTokenSize:int the size of the inner context token as read by the GSS-Framework from the mechanism independent GSS-API level header. Returns:byte[] any inner-context token required to be sent to the peer as part of a GSS token. The mechanism should not add the mechanism independent part of the token. The GSS-Framework will add that on the way out. Exceptions GSSException: may be thrown

acceptSecContext

back to summary

public byte[] acceptSecContext(InputStream is, int mechTokenSize) throws GSSException

Acceptor's context establishment call. This method may be required to be called several times. A CONTINUE_NEEDED return call indicates that more calls are needed after the next token is received from the peer.

This method is called by the GSS-Framework when the application calls the acceptSecContext method on the GSSContext implementation that it has a reference to.

All overloaded forms of GSSContext.acceptSecContext() can be handled with this mechanism level acceptSecContext. Since the output token from this method is a fixed size, not exceedingly large, and a one time deal, an overloaded form that takes an OutputStream has not been defined. The GSS-Framework can write the returned byte[] to any application provided OutputStream. Similarly, any application input in the form of byte arrays will be wrapped in an input stream by the GSS-Framework and then passed here.

The GSS-Framework will strip off the leading mechanism independent GSS-API header. In other words, only the mechanism specific inner-context token of RFC 2743 section 3.1 will be available on the InputStream.

Parameters

is:InputStream: contains the inner context token portion of the GSS token received from the peer.
mechTokenSize:int: the size of the inner context token as read by the GSS-Framework from the mechanism independent GSS-API level header.

Returns:byte[]

any inner-context token required to be sent to the peer as part of a GSS token. The mechanism should not add the mechanism independent part of the token. The GSS-Framework will add that on the way out.

Exceptions

GSSException:: may be thrown

dispose	back to summary
public void dispose() throws GSSException Releases context resources and terminates the context between 2 peer. Exceptions GSSException: may be thrown

dispose

back to summary

public void dispose() throws GSSException

Releases context resources and terminates the context between 2 peer.

Exceptions

GSSException:: may be thrown

export	back to summary
public byte[] export() throws GSSException Produces a token representing this context. After this call the context will no longer be usable until an import is performed on the returned token. Returns:byte[] exported context token Exceptions GSSException: may be thrown

export

back to summary

public byte[] export() throws GSSException

Produces a token representing this context. After this call the context will no longer be usable until an import is performed on the returned token.

Returns:byte[]

exported context token

Exceptions

GSSException:: may be thrown

getAnonymityState	back to summary
public boolean getAnonymityState()

getConfState	back to summary
public boolean getConfState()

getCredDelegState	back to summary
public boolean getCredDelegState()

getDelegCred	back to summary
public GSSCredentialSpi getDelegCred() throws GSSException

getDelegPolicyState	back to summary
public boolean getDelegPolicyState()

getIntegState	back to summary
public boolean getIntegState()

getLifetime	back to summary
public int getLifetime()

getMech	back to summary
public Oid getMech() throws GSSException

getMIC	back to summary
public void getMIC(InputStream is, OutputStream os, MessageProp msgProp) throws GSSException Applies per-message integrity services. Parameters is:InputStream the user-provided message os:OutputStream the token to be sent to the peer along with the message token. The message token is not encapsulated. msgProp:MessageProp on input the desired QOP and output the applied QOP

getMIC

back to summary

public void getMIC(InputStream is, OutputStream os, MessageProp msgProp) throws GSSException

Applies per-message integrity services.

Parameters

is:InputStream: the user-provided message
os:OutputStream: the token to be sent to the peer along with the message token. The message token is not encapsulated.
msgProp:MessageProp: on input the desired QOP and output the applied QOP

getMIC	back to summary
public byte[] getMIC(byte[] inMsg, int offset, int len, MessageProp msgProp) throws GSSException

getMutualAuthState	back to summary
public boolean getMutualAuthState()

getProvider	back to summary
public Provider getProvider()

getReplayDetState	back to summary
public boolean getReplayDetState()

getSequenceDetState	back to summary
public boolean getSequenceDetState()

getSrcName	back to summary
public GSSNameSpi getSrcName() throws GSSException

getTargName	back to summary
public GSSNameSpi getTargName() throws GSSException

getWrapSizeLimit	back to summary
public int getWrapSizeLimit(int qop, boolean confReq, int maxTokSize) throws GSSException Queries the context for largest data size to accommodate the specified protection and for the token to remain less than maxTokSize. Parameters qop:int the quality of protection that the context will be asked to provide. confReq:boolean a flag indicating whether confidentiality will be requested or not maxTokSize:int the maximum size of the output token Returns:int the maximum size for the input message that can be provided to the wrap() method in order to guarantee that these requirements are met. Exceptions GSSException: may be thrown

getWrapSizeLimit

back to summary

public int getWrapSizeLimit(int qop, boolean confReq, int maxTokSize) throws GSSException

Queries the context for largest data size to accommodate the specified protection and for the token to remain less than maxTokSize.

Parameters

qop:int: the quality of protection that the context will be asked to provide.
confReq:boolean: a flag indicating whether confidentiality will be requested or not
maxTokSize:int: the maximum size of the output token

Returns:int

the maximum size for the input message that can be provided to the wrap() method in order to guarantee that these requirements are met.

Exceptions

GSSException:: may be thrown

initSecContext	back to summary
public byte[] initSecContext(InputStream is, int mechTokenSize) throws GSSException Initiator context establishment call. This method may be required to be called several times. A CONTINUE_NEEDED return call indicates that more calls are needed after the next token is received from the peer. This method is called by the GSS-Framework when the application calls the initSecContext method on the GSSContext implementation that it has a reference to. All overloaded forms of GSSContext.initSecContext() can be handled with this mechanism level initSecContext. Since the output token from this method is a fixed size, not exceedingly large, and a one time deal, an overloaded form that takes an OutputStream has not been defined. The GSS-Framework can write the returned byte[] to any application provided OutputStream. Similarly, any application input in the form of byte arrays will be wrapped in an input stream by the GSS-Framework and then passed here. The GSS-Framework will strip off the leading mechanism independent GSS-API header. In other words, only the mechanism specific inner-context token of RFC 2743 section 3.1 will be available on the InputStream. Parameters is:InputStream contains the inner context token portion of the GSS token received from the peer. On the first call to initSecContext, there will be no token hence it will be ignored. mechTokenSize:int the size of the inner context token as read by the GSS-Framework from the mechanism independent GSS-API level header. Returns:byte[] any inner-context token required to be sent to the peer as part of a GSS token. The mechanism should not add the mechanism independent part of the token. The GSS-Framework will add that on the way out. Exceptions GSSException: may be thrown

initSecContext

back to summary

public byte[] initSecContext(InputStream is, int mechTokenSize) throws GSSException

Initiator context establishment call. This method may be required to be called several times. A CONTINUE_NEEDED return call indicates that more calls are needed after the next token is received from the peer.

This method is called by the GSS-Framework when the application calls the initSecContext method on the GSSContext implementation that it has a reference to.

All overloaded forms of GSSContext.initSecContext() can be handled with this mechanism level initSecContext. Since the output token from this method is a fixed size, not exceedingly large, and a one time deal, an overloaded form that takes an OutputStream has not been defined. The GSS-Framework can write the returned byte[] to any application provided OutputStream. Similarly, any application input in the form of byte arrays will be wrapped in an input stream by the GSS-Framework and then passed here.

Parameters

is:InputStream: contains the inner context token portion of the GSS token received from the peer. On the first call to initSecContext, there will be no token hence it will be ignored.
mechTokenSize:int: the size of the inner context token as read by the GSS-Framework from the mechanism independent GSS-API level header.

Returns:byte[]

Exceptions

GSSException:: may be thrown

inquireSecContext back to summary

inquireSecContext	back to summary
public Object inquireSecContext(String type) throws GSSException Return the mechanism-specific attribute associated with `type`. Parameters type:String the type of the attribute requested Returns:Object the attribute Exceptions GSSException: see `ExtendedGSSContext#inquireSecContext` for details

public Object inquireSecContext(String type) throws GSSException

Return the mechanism-specific attribute associated with type.

Parameters

type:String: the type of the attribute requested

Returns:Object

the attribute

Exceptions

GSSException:: see ExtendedGSSContext#inquireSecContext for details

isEstablished	back to summary
public boolean isEstablished()

isInitiator	back to summary
public boolean isInitiator()

isProtReady	back to summary
public boolean isProtReady()

isTransferable	back to summary
public boolean isTransferable() throws GSSException

requestAnonymity	back to summary
public void requestAnonymity(boolean state) throws GSSException

requestConf	back to summary
public void requestConf(boolean state) throws GSSException

requestCredDeleg	back to summary
public void requestCredDeleg(boolean state) throws GSSException

requestDelegPolicy	back to summary
public void requestDelegPolicy(boolean state) throws GSSException

requestInteg	back to summary
public void requestInteg(boolean state) throws GSSException

requestLifetime	back to summary
public void requestLifetime(int lifetime) throws GSSException

requestMutualAuth	back to summary
public void requestMutualAuth(boolean state) throws GSSException

requestReplayDet	back to summary
public void requestReplayDet(boolean state) throws GSSException

requestSequenceDet	back to summary
public void requestSequenceDet(boolean state) throws GSSException

setChannelBinding	back to summary
public void setChannelBinding(ChannelBinding cb) throws GSSException

unwrap back to summary

unwrap	back to summary
public void unwrap(InputStream is, OutputStream os, MessageProp msgProp) throws GSSException Retrieves the message token previously encapsulated in the wrap call. Parameters is:InputStream the token from the peer os:OutputStream unprotected message data msgProp:MessageProp will contain the applied qop and confidentiality of the input token and any informatory status values Exceptions GSSException: may be thrown See Also `wrap`

public void unwrap(InputStream is, OutputStream os, MessageProp msgProp) throws GSSException

Retrieves the message token previously encapsulated in the wrap call.

Parameters

is:InputStream: the token from the peer
os:OutputStream: unprotected message data
msgProp:MessageProp: will contain the applied qop and confidentiality of the input token and any informatory status values

Exceptions

GSSException:: may be thrown

See Also

wrap

unwrap	back to summary
public byte[] unwrap(byte[] inBuf, int offset, int len, MessageProp msgProp) throws GSSException For apps that want simplicity and don't care about buffer copies.

verifyMIC	back to summary
public void verifyMIC(InputStream is, InputStream msgStr, MessageProp mProp) throws GSSException Checks the integrity of the supplied tokens. This token was previously generated by getMIC. Parameters is:InputStream token generated by getMIC msgStr:InputStream the message to check integrity for mProp:MessageProp will contain the applied QOP and confidentiality states of the token as well as any informatory status codes Exceptions GSSException: may be thrown

verifyMIC

back to summary

public void verifyMIC(InputStream is, InputStream msgStr, MessageProp mProp) throws GSSException

Checks the integrity of the supplied tokens. This token was previously generated by getMIC.

Parameters

is:InputStream: token generated by getMIC
msgStr:InputStream: the message to check integrity for
mProp:MessageProp: will contain the applied QOP and confidentiality states of the token as well as any informatory status codes

Exceptions

GSSException:: may be thrown

verifyMIC	back to summary
public void verifyMIC(byte[] inTok, int tokOffset, int tokLen, byte[] inMsg, int msgOffset, int msgLen, MessageProp msgProp) throws GSSException

wrap back to summary

wrap	back to summary
public void wrap(InputStream is, OutputStream os, MessageProp msgProp) throws GSSException Provides per-message token encapsulation. Parameters is:InputStream the user-provided message to be protected os:OutputStream the token to be sent to the peer. It includes the message from is with the requested protection. msgProp:MessageProp on input, contains the requested qop and confidentiality state, on output, the applied values Exceptions GSSException: may be thrown See Also `unwrap`

public void wrap(InputStream is, OutputStream os, MessageProp msgProp) throws GSSException

Provides per-message token encapsulation.

Parameters

is:InputStream: the user-provided message to be protected
os:OutputStream: the token to be sent to the peer. It includes the message from is with the requested protection.
msgProp:MessageProp: on input, contains the requested qop and confidentiality state, on output, the applied values

Exceptions

GSSException:: may be thrown

See Also

unwrap

wrap	back to summary
public byte[] wrap(byte[] inBuf, int offset, int len, MessageProp msgProp) throws GSSException For apps that want simplicity and don't care about buffer copies.

public Interface GSSContextSpi

Method Summary

Method Detail