sun.security.mule.jgss.spi
Interface GSSContextSpi

All Known Implementing Classes:

Krb5Context, SpNegoContext

public interface GSSContextSpi

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 upto 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 accomodated those cases here with the expectation that this will be rolled into the high level bindings sooner or later.

Author:

Mayank Upadhyay

Method Summary

byte[]	acceptSecContext(InputStream is, int mechTokenSize) Acceptor's context establishment call.
void	dispose() Releases context resources and terminates the context between 2 peer.
byte[]	export() Produces a token representing this context.
boolean	getAnonymityState()
boolean	getConfState()
boolean	getCredDelegState()
GSSCredentialSpi	getDelegCred()
boolean	getIntegState()
int	getLifetime()
Oid	getMech()
byte[]	getMIC(byte[] inMsg, int offset, int len, MessageProp msgProp)
void	getMIC(InputStream is, OutputStream os, MessageProp msgProp) Applies per-message integrity services.
boolean	getMutualAuthState()
Provider	getProvider()
boolean	getReplayDetState()
boolean	getSequenceDetState()
GSSNameSpi	getSrcName()
GSSNameSpi	getTargName()
int	getWrapSizeLimit(int qop, boolean confReq, int maxTokSize) Queries the context for largest data size to accomodate the specified protection and for the token to remain less then maxTokSize.
byte[]	initSecContext(InputStream is, int mechTokenSize) Initiator context establishment call.
boolean	isEstablished()
boolean	isInitiator()
boolean	isProtReady()
boolean	isTransferable()
void	requestAnonymity(boolean state)
void	requestConf(boolean state)
void	requestCredDeleg(boolean state)
void	requestInteg(boolean state)
void	requestLifetime(int lifetime)
void	requestMutualAuth(boolean state)
void	requestReplayDet(boolean state)
void	requestSequenceDet(boolean state)
void	setChannelBinding(ChannelBinding cb)
byte[]	unwrap(byte[] inBuf, int offset, int len, MessageProp msgProp) For apps that want simplicity and dont care about buffer copies.
void	unwrap(InputStream is, OutputStream os, MessageProp msgProp) Retrieves the message token previously encapsulated in the wrap call.
void	verifyMIC(byte[] inTok, int tokOffset, int tokLen, byte[] inMsg, int msgOffset, int msgLen, MessageProp msgProp)
void	verifyMIC(InputStream is, InputStream msgStr, MessageProp mProp) Checks the integrity of the supplied tokens.
byte[]	wrap(byte[] inBuf, int offset, int len, MessageProp msgProp) For apps that want simplicity and don't care about buffer copies.
void	wrap(InputStream is, OutputStream os, MessageProp msgProp) Provides per-message token encapsulation.

Method Detail

getProvider

Provider getProvider()

requestLifetime

void requestLifetime(int lifetime)
                     throws GSSException

Throws:

GSSException

requestMutualAuth

void requestMutualAuth(boolean state)
                       throws GSSException

Throws:

GSSException

requestReplayDet

void requestReplayDet(boolean state)
                      throws GSSException

Throws:

GSSException

requestSequenceDet

void requestSequenceDet(boolean state)
                        throws GSSException

Throws:

GSSException

requestCredDeleg

void requestCredDeleg(boolean state)
                      throws GSSException

Throws:

GSSException

requestAnonymity

void requestAnonymity(boolean state)
                      throws GSSException

Throws:

GSSException

requestConf

void requestConf(boolean state)
                 throws GSSException

Throws:

GSSException

requestInteg

void requestInteg(boolean state)
                  throws GSSException

Throws:

GSSException

setChannelBinding

void setChannelBinding(ChannelBinding cb)
                       throws GSSException

Throws:

GSSException

getCredDelegState

boolean getCredDelegState()

getMutualAuthState

boolean getMutualAuthState()

getReplayDetState

boolean getReplayDetState()

getSequenceDetState

boolean getSequenceDetState()

getAnonymityState

boolean getAnonymityState()

isTransferable

boolean isTransferable()
                       throws GSSException

Throws:

GSSException

isProtReady

boolean isProtReady()

isInitiator

boolean isInitiator()

getConfState

boolean getConfState()

getIntegState

boolean getIntegState()

getLifetime

int getLifetime()

isEstablished

boolean isEstablished()

getSrcName

GSSNameSpi getSrcName()
                      throws GSSException

Throws:

GSSException

getTargName

GSSNameSpi getTargName()
                       throws GSSException

Throws:

GSSException

getMech

Oid getMech()
            throws GSSException

Throws:

GSSException

getDelegCred

GSSCredentialSpi getDelegCred()
                              throws GSSException

Throws:

GSSException

initSecContext

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 exeedingly large, and a one time deal, an overloaded form that takes an OutputStream has not been defined. The GSS-Framwork can write the returned byte[] to any application provided OutputStream. Similarly, any application input int he 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 - 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 - the size of the inner context token as read by the GSS-Framework from the mechanism independent GSS-API level header.

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.

Throws:

GSSException - may be thrown

acceptSecContext

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 exeedingly large, and a one time deal, an overloaded form that takes an OutputStream has not been defined. The GSS-Framwork can write the returned byte[] to any application provided OutputStream. Similarly, any application input int he 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 - contains the inner context token portion of the GSS token received from the peer.

mechTokenSize - the size of the inner context token as read by the GSS-Framework from the mechanism independent GSS-API level header.

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.

Throws:

GSSException - may be thrown

getWrapSizeLimit

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

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

Parameters:

qop - the quality of protection that the context will be asked to provide.

confReq - a flag indicating whether confidentiality will be requested or not

outputSize - the maximum size of the output token

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.

Throws:

GSSException - may be thrown

wrap

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

Provides per-message token encapsulation.

Parameters:

is - the user-provided message to be protected

os - the token to be sent to the peer. It includes the message from is with the requested protection.

msgPro - on input it contains the requested qop and confidentiality state, on output, the applied values

Throws:

GSSException - may be thrown

See Also:

MessageInfo, unwrap

wrap

byte[] wrap(byte[] inBuf,
            int offset,
            int len,
            MessageProp msgProp)
            throws GSSException

For apps that want simplicity and don't care about buffer copies.

Throws:

GSSException

unwrap

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

Retrieves the message token previously encapsulated in the wrap call.

Parameters:

is - the token from the peer

os - unprotected message data

msgProp - will contain the applied qop and confidentiality of the input token and any informatory status values

Throws:

GSSException - may be thrown

See Also:

MessageInfo, wrap

unwrap

byte[] unwrap(byte[] inBuf,
              int offset,
              int len,
              MessageProp msgProp)
              throws GSSException

For apps that want simplicity and dont care about buffer copies.

Throws:

GSSException

getMIC

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

Applies per-message integrity services.

Parameters:

is - the user-provided message

os - the token to be sent to the peer along with the message token. The message token is not encapsulated.

msgProp - on input the desired QOP and output the applied QOP

Throws:

GSSException

getMIC

byte[] getMIC(byte[] inMsg,
              int offset,
              int len,
              MessageProp msgProp)
              throws GSSException

Throws:

GSSException

verifyMIC

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 - token generated by getMIC

msgStr - the message to check integrity for

msgProp - will contain the applied QOP and confidentiality states of the token as well as any informatory status codes

Throws:

GSSException - may be thrown

verifyMIC

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

Throws:

GSSException

export

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:

exported context token

Throws:

GSSException - may be thrown

dispose

void dispose()
             throws GSSException

Releases context resources and terminates the context between 2 peer.

Throws:

GSSException - may be thrown