/*
 * Copyright (c) 2000, 2009, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

/*
 *
 *  (C) Copyright IBM Corp. 1999 All Rights Reserved.
 *  Copyright 1997 The Open Group Research Institute.  All rights reserved.
 */
package sun.security.jgss.spi;

import org.ietf.jgss.*;
import java.io.InputStream;
import java.io.OutputStream;
import java.security.Provider;
import com.sun.security.jgss.*;

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/**
 * 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
 * <p>
 * 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.
 *<p>
 * <strong>
 * 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..
 * <p>
 * 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.
 * </strong>
 * <p>
 * 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.
 * <p>
 * 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
 */

public interface GSSContextSpi {

    public Provider getProvider();

    // The specification for the following methods mirrors the
    // specification of the same methods in the GSSContext interface, as
    // defined in RFC 2853.

    public void requestLifetime(int lifetime) throws GSSException;

    public void requestMutualAuth(boolean state) throws GSSException;

    public void requestReplayDet(boolean state) throws GSSException;

    public void requestSequenceDet(boolean state) throws GSSException;

    public void requestCredDeleg(boolean state) throws GSSException;

    public void requestAnonymity(boolean state) throws GSSException;

    public void requestConf(boolean state) throws GSSException;

    public void requestInteg(boolean state) throws GSSException;

    public void requestDelegPolicy(boolean state) throws GSSException;

    public void setChannelBinding(ChannelBinding cb) throws GSSException;

    public boolean getCredDelegState();

    public boolean getMutualAuthState();

    public boolean getReplayDetState();

    public boolean getSequenceDetState();

    public boolean getAnonymityState();

    public boolean getDelegPolicyState();

    public boolean isTransferable() throws GSSException;

    public boolean isProtReady();

    public boolean isInitiator();

    public boolean getConfState();

    public boolean getIntegState();

    public int getLifetime();

    public boolean isEstablished();

    public GSSNameSpi getSrcName() throws GSSException;

    public GSSNameSpi getTargName() throws GSSException;

    public Oid getMech() throws GSSException;

    public GSSCredentialSpi getDelegCred() 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.

Params:
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.
Throws:
GSSException – may be thrown
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./**
     * 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.
     * <p>
     * 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.
     * <p>
     * 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.
     * <p>
     * <strong>
     * 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.
     * </strong>
     *
     * @param 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.
     * @param mechTokenSize the size of the inner context token as read by
     * the GSS-Framework from the mechanism independent GSS-API level
     * header.
     * @return 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.
     * @exception GSSException may be thrown
     */
    public byte[] initSecContext(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.

Params:
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.
Throws:
GSSException – may be thrown
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./**
     * 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.
     * <p>
     * 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.
     * <p>
     * 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.
     * <p>
     * <strong>
     * 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.
     * </strong>
     *
     * @param is contains the inner context token portion of the GSS token
     * received from the peer.
     * @param mechTokenSize the size of the inner context token as read by
     * the GSS-Framework from the mechanism independent GSS-API level
     * header.
     * @return 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.
     * @exception GSSException may be thrown
     */
    public byte[] acceptSecContext(InputStream is, int mechTokenSize)
                        throws GSSException;

    
Queries the context for largest data size to accommodate
the specified protection and for the token to remain less then
maxTokSize.
Params:
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
Throws:
GSSException – may be thrown
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./**
     * Queries the context for largest data size to accommodate
     * the specified protection and for the token to remain less then
     * maxTokSize.
     *
     * @param qop the quality of protection that the context will be
     *    asked to provide.
     * @param confReq a flag indicating whether confidentiality will be
     *    requested or not
     * @param outputSize the maximum size of the output token
     * @return the maximum size for the input message that can be
     *    provided to the wrap() method in order to guarantee that these
     *    requirements are met.
     * @exception GSSException may be thrown
     */
    public int getWrapSizeLimit(int qop, boolean confReq, int maxTokSize)
                        throws GSSException;

    
Provides per-message token encapsulation.
Params:
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:
unwrap/**
     * Provides per-message token encapsulation.
     *
     * @param is the user-provided message to be protected
     * @param os the token to be sent to the peer. It includes
     *    the message from <i>is</i> with the requested protection.
     * @param msgPro on input it contains the requested qop and
     *    confidentiality state, on output, the applied values
     * @exception GSSException may be thrown
     * @see unwrap
     */
    public void wrap(InputStream is, OutputStream os, MessageProp msgProp)
        throws GSSException;

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

    /**
     * For apps that care about buffer copies but either cannot use streams
     * or want to avoid them for whatever reason. (Say, they are using
     * block ciphers.)
     *
     * NOTE: This method is not defined in public class org.ietf.jgss.GSSContext
     *
    public int wrap(byte inBuf[], int inOffset, int len,
                    byte[] outBuf, int outOffset,
                    MessageProp msgProp) throws GSSException;

    */

    /**
     * For apps that want to read from a specific application provided
     * buffer but want to write directly to the network stream.
     */
    /*
     * Can be achieved by converting the input buffer to a
     * ByteInputStream. Provided to keep the API consistent
     * with unwrap.
     *
     * NOTE: This method is not defined in public class org.ietf.jgss.GSSContext
     *
    public void wrap(byte inBuf[], int offset, int len,
                     OutputStream os, MessageProp msgProp)
        throws GSSException;
    */

    
Retrieves the message token previously encapsulated in the wrap
call.
Params:
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:
wrap/**
     * Retrieves the message token previously encapsulated in the wrap
     * call.
     *
     * @param is the token from the peer
     * @param os unprotected message data
     * @param msgProp will contain the applied qop and confidentiality
     *    of the input token and any informatory status values
     * @exception GSSException may be thrown
     * @see wrap
     */
    public void unwrap(InputStream is, OutputStream os,
                        MessageProp msgProp) throws GSSException;

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

    /**
     * For apps that care about buffer copies but either cannot use streams
     * or want to avoid them for whatever reason. (Say, they are using
     * block ciphers.)
     *
     * NOTE: This method is not defined in public class org.ietf.jgss.GSSContext
     *
    public int unwrap(byte inBuf[], int inOffset, int len,
                      byte[] outBuf, int outOffset,
                      MessageProp msgProp) throws GSSException;

    */

    /**
     * For apps that care about buffer copies and want to read
     * straight from the network, but also want the output in a specific
     * application provided buffer, say to reduce buffer allocation or
     * subsequent copy.
     *
     * NOTE: This method is not defined in public class org.ietf.jgss.GSSContext
     *
    public int unwrap(InputStream is,
                       byte[] outBuf, int outOffset,
                       MessageProp msgProp) throws GSSException;
    */

    
Applies per-message integrity services.
Params:
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 – /**
     * Applies per-message integrity services.
     *
     * @param is the user-provided message
     * @param os the token to be sent to the peer along with the
     *    message token. The message token <b>is not</b> encapsulated.
     * @param msgProp on input the desired QOP and output the applied QOP
     * @exception GSSException
     */
    public void getMIC(InputStream is, OutputStream os,
                        MessageProp msgProp)
                throws GSSException;

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

    
Checks the integrity of the supplied tokens.
This token was previously generated by getMIC.
Params:
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/**
     * Checks the integrity of the supplied tokens.
     * This token was previously generated by getMIC.
     *
     * @param is token generated by getMIC
     * @param msgStr the message to check integrity for
     * @param msgProp will contain the applied QOP and confidentiality
     *    states of the token as well as any informatory status codes
     * @exception GSSException may be thrown
     */
    public void verifyMIC(InputStream is, InputStream msgStr,
                           MessageProp mProp) throws GSSException;

    public void verifyMIC(byte []inTok, int tokOffset, int tokLen,
                          byte[] inMsg, int msgOffset, int msgLen,
                          MessageProp msgProp) 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.
Throws:
GSSException – may be thrown
Returns:
exported context token/**
     * 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.
     *
     * @return exported context token
     * @exception GSSException may be thrown
     */
    public byte[] export() throws GSSException;

    
Releases context resources and terminates the
context between 2 peer.
Throws:
GSSException – may be thrown/**
     * Releases context resources and terminates the
     * context between 2 peer.
     *
     * @exception GSSException may be thrown
     */
    public void dispose() throws GSSException;

    
Return the mechanism-specific attribute associated with (@code type}.
Params:
type – the type of the attribute requested
Throws:
GSSException – see ExtendedGSSContext.inquireSecContext for details
Returns:
the attribute/**
     * Return the mechanism-specific attribute associated with (@code type}.
     *
     * @param type the type of the attribute requested
     * @return the attribute
     * @throws GSSException see {@link ExtendedGSSContext#inquireSecContext}
     * for details
     */
    public Object inquireSecContext(InquireType type)
            throws GSSException;
}