Java example source code file (GSSContextSpi.java)

This example Java source code file (GSSContextSpi.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

gsscontextspi, gsscredentialspi, gssexception, gssnamespi, inputstream, messageprop, object, oid, outputstream, provider, security

The GSSContextSpi.java Java example source code

/*
 * Copyright (c) 2000, 2013, 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
 * <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.
     * <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.
     * <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.
     *
     * @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.
     *
     * @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 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.
     */
    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.
     *
     * @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.
     */
    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.
     *
     * @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 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.
     *
     * @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.
     *
     * @return exported context token
     * @exception GSSException may be thrown
     */
    public byte[] export() throws GSSException;

    /**
     * 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}.
     *
     * @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;
}