gsscontext.java

gcc的组建

/* GSSContext.java -- The GSS context interface.
   Copyright (C) 2004 Free Software Foundation, Inc.

This file is part of GNU Classpath.

GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

GNU Classpath 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 for more details.

You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING.  If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA.

Linking this library statically or dynamically with other modules is
making a combined work based on this library.  Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.

As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module.  An independent module is a module which is not derived from
or based on this library.  If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so.  If you do not wish to do so, delete this
exception statement from your version. */


package org.ietf.jgss;

import java.io.InputStream;
import java.io.OutputStream;

/**
 * <p>This interface encapsulates the GSS-API security context and provides
 * the security services ({@link #wrap(byte[],int,int,org.ietf.jgss.MessageProp)},
 * {@link #unwrap(byte[],int,int,org.ietf.jgss.MessageProp)}, {@link
 * #getMIC(byte[],int,int,org.ietf.jgss.MessageProp)}, {@link
 * #verifyMIC(byte[],int,int,byte[],int,int,org.ietf.jgss.MessageProp)}) that
 * are available over the context.  Security contexts are established
 * between peers using locally acquired credentials.  Multiple contexts
 * may exist simultaneously between a pair of peers, using the same or
 * different set of credentials.  GSS-API functions in a manner
 * independent of the underlying transport protocol and depends on its
 * calling application to transport its tokens between peers.</p>
 *
 * <p>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.</p>
 *
 * <p>The context establishment phase begins with the first call to the
 * init method by the context initiator.  During this phase the
 * {@link #initSecContext(byte[],int,int)} and {@link
 * #acceptSecContext(byte[],int,int)} methods will produce GSS-API
 * authentication tokens which the calling application needs to send to
 * its peer.  If an error occurs at any point, an exception will get
 * thrown and the code will start executing in a catch block.  If not,
 * the normal flow of code continues and the application can make a call
 * to the {@link #isEstablished()} method. If this method returns false it
 * indicates that a token is needed from its peer in order to continue
 * the context establishment phase.  A return value of true signals that
 * the local end of the context is established.  This may still require
 * that a token be sent to the peer, if one is produced by GSS-API.
 * During the context establishment phase, the {@link #isProtReady()}
 * method may be called to determine if the context can be used for the
 * per-message operations.  This allows applications to use per-message
 * operations on contexts which aren't fully established.</p>
 *
 * <p>After the context has been established or the {@link #isProtReady()}
 * method returns <code>true</code>, 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 {@link #wrap(byte[],int,int,org.ietf.jgss.MessageProp)} and
 * {@link #getMIC(byte[],int,int,org.ietf.jgss.MessageProp)} to obtain
 * cryptographic operations on application supplied data.</p>
 *
 * <p>When the context is no longer needed, the application should call
 * {@link dispose()} to release any system resources the context may be
 * using.</p>
 *
 * <h3>Example Code</h3>
 *
 * <pre>
GSSManager mgr = GSSManager.getInstance();

// start by creating the name for a service entity
GSSName targetName = mgr.createName("service@host",
                                    GSSName.NT_HOSTBASED_SERVICE);

// create a context using default credentials for the above entity
// and the implementation specific default mechanism
GSSContext context = mgr.createContext(targetName,
                                       null,   // default mechanism
                                       null,   // default credentials
                                       GSSContext.INDEFINITE_LIFETIME);

// set desired context options - all others are false by default
context.requestConf(true);
context.requestMutualAuth(true);
context.requestReplayDet(true);
context.requestSequenceDet(true);

// establish a context between peers - using byte arrays
byte []inTok = new byte[0];

try
  {
    do
      {
        byte[] outTok = context.initSecContext(inTok, 0,
                                               inTok.length);

        // send the token if present
        if (outTok != null)
          sendToken(outTok);

        // check if we should expect more tokens
        if (context.isEstablished())
          break;

        // another token expected from peer
        inTok = readToken();

      }
    while (true);
  }
catch (GSSException e)
  {
    print("GSSAPI error: " + e.getMessage());
  }

// display context information
print("Remaining lifetime in seconds = " + context.getLifetime());
print("Context mechanism = " + context.getMech().toString());
print("Initiator = " + context.getSrcName().toString());
print("Acceptor = " + context.getTargName().toString());

if (context.getConfState())
  print("Confidentiality security service available");

if (context.getIntegState())
  print("Integrity security service available");

// perform wrap on an application supplied message, appMsg,
// using QOP = 0, and requesting privacy service
byte[] appMsg ...
MessageProp mProp = new MessageProp(0, true);
byte[] tok = context.wrap(appMsg, 0, appMsg.length, mProp);

if (mProp.getPrivacy())
  print("Message protected with privacy.");

sendToken(tok);


// release the local-end of the context
context.dispose();
 * </pre>
 */
public interface GSSContext
{

  // Constants.
  // -------------------------------------------------------------------------

  /**
   * A lifetime constant representing the default context lifetime.
   */
  int DEFAULT_LIFETIME = 0;

  /**
   * A lifetime constant representing indefinite context lifetime.
   */
  int INDEFINITE_LIFETIME = Integer.MAX_VALUE;

  // Methods.
  // -------------------------------------------------------------------------

  /**
   * <p>Called by the context initiator to start the context creation
   * process.  This is equivalent to the stream based method except that
   * the token buffers are handled as byte arrays instead of using stream
   * objects.  This method may return an output token which the
   * application will need to send to the peer for processing by the
   * accept call.  Typically, the application would do so by calling the
   * {@link OutputStream#flush()} method on an OutputStream that
   * encapsulates the connection between the two peers.  The application
   * can call {@link #isEstablished()} to determine if the context
   * establishment phase is complete for this peer.  A return value of
   * <code>false</code> from {@link #isEstablished()} indicates that more
   * tokens are expected to be supplied to the initSecContext() method. Note
   * that it is possible that the initSecContext() method return a token for
   * the peer, and {@link #isEstablished()} to return <code>true</code> also.
   * This indicates that the token needs to be sent to the peer, but the local
   * end of the context is now fully established.</p>
   *
   * <p>Upon completion of the context establishment, the available context
   * options may be queried through the get methods.</p>
   *
   * @param inputBuf Token generated by the peer. This parameter is ignored
   *                 on the first call.
   * @param offset   The offset within the <i>inputBuf</i> where the token
   *                 begins.
   * @param len      The length of the token within the <i>inputBuf</i>
   *                 (starting at the offset).
   * @return The output token, if any.
   * @throws GSSException If this operation fails.
   */
  byte[] initSecContext(byte[] inputBuf, int offset, int len)
    throws GSSException;

  /**
   * <p>Called by the context initiator to start the context creation
   * process.  This is equivalent to the byte array based method.  This
   * method may write an output token to the <i>outStream</i>, which the
   * application will need to send to the peer for processing by the
   * accept call. Typically, the application would do so by calling the
   * {@link OutputStream#flush()} method on an OutputStream that encapsulates
   * the connection between the two peers. The application can call {@link
   * #isEstablished()} to determine if the context establishment phase is
   * complete for this peer. A return value of <code>false</code> from
   * isEstablished indicates that more tokens are expected to be supplied
   * to the initSecContext() method. Note that it is possible that the
   * initSecContext() method return a token for the peer, and {@link
   * #isEstablished() return <code>true</code> also. This indicates that
   * the token needs to be sent to the peer, but the local end of the context
   * is now fully established.</p>
   *
   * <p>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.</p>
   *
   * <p>Upon completion of the context establishment, the available context
   * options may be queried through the get methods.</p>
   *
   * @param inStream  Contains the token generated by the peer. This
   *                  parameter is ignored on the first call.
   * @param outStream Output stream where the output token will be written.
   *                  During the final stage of context establishment, there
   *                  may be no bytes written.
   * @return The number of bytes written to <i>outStream</i>, or 0 if no
   *         token is written.
   * @throws GSSException If this operation fails.
   */
  int initSecContext(InputStream inStream, OutputStream outStream)
    throws GSSException;

  /**
   * <p>Called by the context acceptor upon receiving a token from the peer.
   * This call is equivalent to the stream based method except that the
   * token buffers are handled as byte arrays instead of using stream
   * objects.</p>
   *
   * <p>This method may return an output token which the application will
   * need to send to the peer for further processing by the init call.</p>
   *
   * <p><code>null</code> return value indicates that no token needs to be
   * sent to the peer. The application can call {@link #isEstablished()}
   * to determine if the context establishment phase is complete for this
   * peer. A return value of <code>false</code> from {@link #isEstablished()}
   * indicates that more tokens are expected to be supplied to this
   * method.</p>
   *
   * <p>Note that it is possible that acceptSecContext() return a token for
   * the peer, and isEstablished() return <code>true</code> also. This
   * indicates that the token needs to be sent to the peer, but the local
   * end of the context is now fully established.</p>
   *
   * <p>Upon completion of the context establishment, the available context
   * options may be queried through the get methods.</p>
   *
   * @param inTok  Token generated by the peer.
   * @param offset The offset within the <i>inTok</i> where the token begins.
   * @param len    The length of the token within the <i>inTok</i> (starting
   *               at the offset).
   * @return The output token, if any.
   * @throws GSSException If this operation fails.
   */
  byte[] acceptSecContext(byte[] inTok, int offset, int len)
    throws GSSException;

  /**
   * <p>Called by the context acceptor upon receiving a token from the peer.
   * This call is equivalent to the byte array method.  It may write an
   * output token to the outStream, which the application will need to
   * send to the peer for processing by its initSecContext method.
   * Typically, the application would do so by calling the {@link
   * OutputStream#flush()} method on an OutputStream that encapsulates the
   * connection between the two peers. The application can call {@link
   * #isEstablished()} to determine if the context establishment phase is
   * complete for this peer. A return value of <code>false</code> from
   * {@link #isEstablished()} indicates that more tokens are expected to be
   * supplied to this method.</p>
   *
   * <p>Note that it is possible that acceptSecContext() return a token for
   * the peer, and isEstablished() return <code>true</code> also. This