/*
 * @(#)GSSContext.java	1.10 05/11/17
 *
 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package org.ietf.jgss;

import sun.security.jgss.spi.*;
import java.io.InputStream;
import java.io.OutputStream;

/**  
 * This interface encapsulates the GSS-API security context and provides
 * the security services 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 the tokens that are
 * generated by the security context between the peers.<p>
 *
 * If the caller instantiates the context using the default
 * <code>GSSManager</code> instance, then the Kerberos v5 GSS-API mechanism
 * is guaranteed to be available for context establishment. This mechanism
 * is identified by the Oid "1.2.840.113554.1.2.2" and is defined in RFC
 * 1964.<p>
 *
 * Before the context establishment phase is initiated, the context
 * initiator may request specific characteristics desired of the
 * established context. Not all underlying mechanisms support all
 * characteristics that a caller might desire. After the context is
 * established, the caller can check the actual characteristics and services
 * offered by that context by means of various query methods. When using
 * the Kerberos v5 GSS-API mechanism offered by the default
 * <code>GSSManager</code> instance, all optional services will be
 * available locally. They are mutual authentication, credential
 * delegation, confidentiality and integrity protection, and per-message
 * replay detection and sequencing. Note that in the GSS-API, message integrity
 * is a prerequisite for message confidentiality.<p>
 *
 * The context establishment occurs in a loop where the
 * initiator calls {@link #initSecContext(byte[], int, int) initSecContext}
 * and the acceptor calls {@link #acceptSecContext(byte[], int, int)
 * acceptSecContext} until the context is established. While in this loop
 * the <code>initSecContext</code> and <code>acceptSecContext</code>
 * methods produce tokens that the application sends over to the peer. The
 * peer passes any such token as input to its <code>acceptSecContext</code>
 * or <code>initSecContext</code> as the case may be.<p>
 *
 * During the context establishment phase, the {@link
 * #isProtReady() isProtReady} method may be called to determine if the
 * context can be used for the per-message operations of {@link
 * #wrap(byte[], int, int, MessageProp) wrap} and {@link #getMIC(byte[],
 * int, int, MessageProp) getMIC}.  This allows applications to use
 * per-message operations on contexts which aren't yet fully
 * established.<p>
 *
 * After the context has been established or the <code>isProtReady</code>
 * 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, MessageProp) wrap} and
 * {@link #getMIC(byte[], int, int, MessageProp) getMIC} to obtain
 * cryptographic operations on application supplied data.<p>
 *
 * When the context is no longer needed, the application should call
 * {@link #dispose() dispose} to release any system resources the context
 * may be using.<p>
 *
 * A security context typically maintains sequencing and replay detection
 * information about the tokens it processes. Therefore, the sequence in
 * which any tokens are presented to this context for processing can be
 * important. Also note that none of the methods in this interface are
 * synchronized. Therefore, it is not advisable to share a
 * <code>GSSContext</code> among several threads unless some application
 * level synchronization is in place.<p>
 *
 * Finally, different mechanism providers might place different security
 * restrictions on using GSS-API contexts. These will be documented by the
 * mechanism provider. The application will need to ensure that it has the
 * appropriate permissions if such checks are made in the mechanism layer.<p>
 *
 * The example code presented below demonstrates the usage of the
 * <code>GSSContext</code> interface for the initiating peer.  Different
 * operations on the <code>GSSContext</code> object are presented,
 * including: object instantiation, setting of desired flags, context
 * establishment, query of actual context flags, per-message operations on
 * application data, and finally context deletion.<p>
 *
 * <pre>
 *    // Create a context using default credentials 
 *    // and the implementation specific default mechanism
 *    GSSManager manager ...
 *    GSSName targetName ...
 *    GSSContext context = manager.createContext(targetName, null, null,
 *                                           GSSContext.INDEFINITE_LIFETIME);
 * 
 *    // set desired context options prior to context establishment