Back to index...

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

	package org.ietf.jgss;

	import java.security.Provider;

	/**
	* This class serves as a factory for other important
	* GSS-API classes and also provides information about the mechanisms that
	* are supported. It can create instances of classes
	* implementing the following three GSS-API interfaces: {@link
	* GSSName GSSName}, {@link GSSCredential GSSCredential}, and {@link
	* GSSContext GSSContext}. It also has methods to query for the list
	* of available mechanisms and the nametypes that each mechanism
	* supports.<p>
	*
	* An instance of the default <code>GSSManager</code> subclass
	* may be obtained through the static method {@link #getInstance()
	* getInstance}, but applications are free to instantiate other subclasses
	* of <code>GSSManager</code>. The default <code>GSSManager</code> instance
	* will support the Kerberos v5 GSS-API mechanism in addition to any
	* others. This mechanism is identified by the Oid "1.2.840.113554.1.2.2"
	* and is defined in RFC 1964.<p>
	*
	* A subclass extending the <code>GSSManager</code> abstract class may be
	* implemented as a modular provider based layer that utilizes some well
	* known service provider specification. The <code>GSSManager</code> API
	* allows the application to set provider preferences on
	* such an implementation. These methods also allow the implementation to
	* throw a well-defined exception in case provider based configuration is
	* not supported. Applications that expect to be portable should be aware
	* of this and recover cleanly by catching the exception.<p>
	*
	* It is envisioned that there will be three most common ways in which
	* providers will be used:<p>
	* <ol>
	* <li> The application does not care about what provider is used (the
	* default case).
	* <li> The application wants a particular provider to be used
	* preferentially, either for a particular mechanism or all the
	* time, irrespective of mechanism.
	* <li> The application wants to use the locally configured providers
	* as far as possible but if support is missing for one or more
	* mechanisms then it wants to fall back on its own provider.
	*</ol><p>
	*
	* The <code>GSSManager</code> class has two methods that enable these modes of
	* usage: {@link #addProviderAtFront(Provider, Oid) addProviderAtFront} and
	* {@link #addProviderAtEnd(Provider, Oid) addProviderAtEnd}. These methods
	* have the effect of creating an ordered list of <i><provider,
	* oid></i> pairs where each pair indicates a preference of provider
	* for a given oid.<p>
	*
	* It is important to note that there are certain interactions
	* between the different GSS-API objects that are created by a
	* GSSManager, where the provider that is used for a particular mechanism
	* might need to be consistent across all objects. For instance, if a
	* GSSCredential contains elements from a provider <i>p</i> for a mechanism
	* <i>m</i>, it should generally be passed in to a GSSContext that will use
	* provider <i>p</i> for the mechanism <i>m</i>. A simple rule of thumb
	* that will maximize portability is that objects created from different
	* GSSManager's should not be mixed, and if possible, a different
	* GSSManager instance should be created if the application wants to invoke
	* the <code>addProviderAtFront</code> method on a GSSManager that has
	* already created an object.<p>
	*
	* Here is some sample code showing how the GSSManager might be used: <p>
	* <pre>
	* GSSManager manager = GSSManager.getInstance();
	*
	* Oid krb5Mechanism = new Oid("1.2.840.113554.1.2.2");
	* Oid krb5PrincipalNameType = new Oid("1.2.840.113554.1.2.2.1");
	*
	* // Identify who the client wishes to be
	* GSSName userName = manager.createName("duke", GSSName.NT_USER_NAME);
	*
	* // Identify the name of the server. This uses a Kerberos specific
	* // name format.
	* GSSName serverName = manager.createName("nfs/foo.sun.com",
	* krb5PrincipalNameType);
	*
	* // Acquire credentials for the user
	* GSSCredential userCreds = manager.createCredential(userName,
	* GSSCredential.DEFAULT_LIFETIME,
	* krb5Mechanism,
	* GSSCredential.INITIATE_ONLY);
	*
	* // Instantiate and initialize a security context that will be
	* // established with the server
	* GSSContext context = manager.createContext(serverName,
	* krb5Mechanism,
	* userCreds,
	* GSSContext.DEFAULT_LIFETIME);
	* </pre><p>
	*
	* The server side might use the following variation of this source:<p>
	*
	* <pre>
	* // Acquire credentials for the server
	* GSSCredential serverCreds = manager.createCredential(serverName,
	* GSSCredential.DEFAULT_LIFETIME,
	* krb5Mechanism,
	* GSSCredential.ACCEPT_ONLY);
	*
	* // Instantiate and initialize a security context that will
	* // wait for an establishment request token from the client
	* GSSContext context = manager.createContext(serverCreds);
	* </pre>
	*
	* @author Mayank Upadhyay
	* @see GSSName
	* @see GSSCredential
	* @see GSSContext
	* @since 1.4
	*/
	public abstract class GSSManager {

	/**
	* Returns the default GSSManager implementation.
	*
	* @return a GSSManager implementation
	*/
	public static GSSManager getInstance() {
	return new sun.security.jgss.GSSManagerImpl();
	}

	/**
	* Returns a list of mechanisms that are available to GSS-API callers
	* through this GSSManager. The default GSSManager obtained from the
	* {@link #getInstance() getInstance()} method includes the Oid
	* "1.2.840.113554.1.2.2" in its list. This Oid identifies the Kerberos
	* v5 GSS-API mechanism that is defined in RFC 1964.
	*
	* @return an array of Oid objects corresponding to the mechanisms that
	* are available. A <code>null</code> value is returned when no
	* mechanism are available (an example of this would be when mechanism
	* are dynamically configured, and currently no mechanisms are
	* installed).
	*/
	public abstract Oid[] getMechs();

	/**
	* Returns then name types supported by the indicated mechanism.<p>
	*
	* The default GSSManager instance includes support for the Kerberos v5
	* mechanism. When this mechanism ("1.2.840.113554.1.2.2") is indicated,
	* the returned list will contain at least the following nametypes:
	* {@link GSSName#NT_HOSTBASED_SERVICE GSSName.NT_HOSTBASED_SERVICE},
	* {@link GSSName#NT_EXPORT_NAME GSSName.NT_EXPORT_NAME}, and the
	* Kerberos v5 specific Oid "1.2.840.113554.1.2.2.1". The namespace for
	* the Oid "1.2.840.113554.1.2.2.1" is defined in RFC 1964.
	*
	* @return an array of Oid objects corresponding to the name types that
	* the mechanism supports.
	* @param mech the Oid of the mechanism to query
	*
	* @see #getMechsForName(Oid)
	*
	* @throws GSSException containing the following
	* major error codes:
	* {@link GSSException#BAD_MECH GSSException.BAD_MECH}
	* {@link GSSException#FAILURE GSSException.FAILURE}
	*/
	public abstract Oid[] getNamesForMech(Oid mech)
	throws GSSException;

	/**
	* Returns a list of mechanisms that support the indicated name type.<p>
	*
	* The Kerberos v5 mechanism ("1.2.840.113554.1.2.2") will always be
	* returned in this list when the indicated nametype is one of
	* {@link GSSName#NT_HOSTBASED_SERVICE GSSName.NT_HOSTBASED_SERVICE},
	* {@link GSSName#NT_EXPORT_NAME GSSName.NT_EXPORT_NAME}, or
	* "1.2.840.113554.1.2.2.1".
	*
	* @return an array of Oid objects corresponding to the mechanisms that
	* support the specified name type. <code>null</code> is returned when no
	* mechanisms are found to support the specified name type.
	* @param nameType the Oid of the name type to look for
	*
	* @see #getNamesForMech(Oid)
	*/
	public abstract Oid[] getMechsForName(Oid nameType);

	/**
	* Factory method to convert a string name from the
	* specified namespace to a GSSName object. In general, the
	* <code>GSSName</code> object created will contain multiple
	* representations of the name, one for each mechanism that is
	* supported; two examples that are exceptions to this are when
	* the namespace type parameter indicates NT_EXPORT_NAME or when the
	* GSS-API implementation is not multi-mechanism. It is
	* not recommended to use this method with a NT_EXPORT_NAME type because
	* representing a previously exported name consisting of arbitrary bytes
	* as a String might cause problems with character encoding schemes. In
	* such cases it is recommended that the bytes be passed in directly to
	* the overloaded form of this method {@link #createName(byte[],
	* Oid) createName}.
	*
	* @param nameStr the string representing a printable form of the name to
	* create.
	* @param nameType the Oid specifying the namespace of the printable name
	* supplied. <code>null</code> can be used to specify
	* that a mechanism specific default printable syntax should
	* be assumed by each mechanism that examines nameStr.
	* It is not advisable to use the nametype NT_EXPORT_NAME with this
	* method.
	* @return a GSSName representing the indicated principal
	*
	* @see GSSName
	* @see GSSName#NT_EXPORT_NAME
	*
	* @throws GSSException containing the following
	* major error codes:
	* {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
	* {@link GSSException#BAD_NAME GSSException.BAD_NAME},
	* {@link GSSException#BAD_MECH GSSException.BAD_MECH},
	* {@link GSSException#FAILURE GSSException.FAILURE}
	*/
	public abstract GSSName createName(String nameStr, Oid nameType)
	throws GSSException;

	/**
	* Factory method to convert a byte array containing a
	* name from the specified namespace to a GSSName object. In general,
	* the <code>GSSName</code> object created will contain multiple
	* representations of the name, one for each mechanism that is
	* supported; two examples that are exceptions to this are when the
	* namespace type parameter indicates NT_EXPORT_NAME or when the
	* GSS-API implementation is not multi-mechanism. The bytes that are
	* passed in are interpreted by each underlying mechanism according to
	* some encoding scheme of its choice for the given nametype.
	*
	* @param name the byte array containing the name to create
	* @param nameType the Oid specifying the namespace of the name supplied
	* in the byte array. <code>null</code> can be used to specify that a
	* mechanism specific default syntax should be assumed by each mechanism
	* that examines the byte array.
	* @return a GSSName representing the indicated principal
	*
	* @see GSSName
	* @see GSSName#NT_EXPORT_NAME
	*
	* @throws GSSException containing the following
	* major error codes:
	* {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
	* {@link GSSException#BAD_NAME GSSException.BAD_NAME},
	* {@link GSSException#BAD_MECH GSSException.BAD_MECH},
	* {@link GSSException#FAILURE GSSException.FAILURE}
	*/
	public abstract GSSName createName(byte name[], Oid nameType)
	throws GSSException;

	/**
	* Factory method to convert a string name from the
	* specified namespace to a GSSName object and canonicalize it at the
	* same time for a mechanism. In other words, this method is
	* a utility that does the equivalent of two steps: the {@link
	* #createName(String, Oid) createName} and then also the {@link
	* GSSName#canonicalize(Oid) GSSName.canonicalize}.
	*
	* @param nameStr the string representing a printable form of the name to
	* create.
	* @param nameType the Oid specifying the namespace of the printable name
	* supplied. <code>null</code> can be used to specify
	* that a mechanism specific default printable syntax should
	* be assumed by each mechanism that examines nameStr.
	* It is not advisable to use the nametype NT_EXPORT_NAME with this
	* method.
	* @param mech Oid specifying the mechanism for which the name should be
	* canonicalized
	* @return a GSSName representing the indicated principal
	*
	* @see GSSName#canonicalize(Oid)
	* @see GSSName#NT_EXPORT_NAME
	*
	* @throws GSSException containing the following
	* major error codes:
	* {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
	* {@link GSSException#BAD_NAME GSSException.BAD_NAME},
	* {@link GSSException#BAD_MECH GSSException.BAD_MECH},
	* {@link GSSException#FAILURE GSSException.FAILURE}
	*/
	public abstract GSSName createName(String nameStr, Oid nameType,
	Oid mech) throws GSSException;

	/**
	* Factory method to convert a byte array containing a
	* name from the specified namespace to a GSSName object and canonicalize
	* it at the same time for a mechanism. In other words, this method is a
	* utility that does the equivalent of two steps: the {@link
	* #createName(byte[], Oid) createName} and then also {@link
	* GSSName#canonicalize(Oid) GSSName.canonicalize}.
	*
	* @param name the byte array containing the name to create
	* @param nameType the Oid specifying the namespace of the name supplied
	* in the byte array. <code>null</code> can be used to specify that a
	* mechanism specific default syntax should be assumed by each mechanism
	* that examines the byte array.
	* @param mech Oid specifying the mechanism for which the name should be
	* canonicalized
	* @return a GSSName representing the indicated principal
	*
	* @see GSSName#canonicalize(Oid)
	* @see GSSName#NT_EXPORT_NAME
	*
	* @throws GSSException containing the following
	* major error codes:
	* {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
	* {@link GSSException#BAD_NAME GSSException.BAD_NAME},
	* {@link GSSException#BAD_MECH GSSException.BAD_MECH},
	* {@link GSSException#FAILURE GSSException.FAILURE}
	*/
	public abstract GSSName createName(byte name[], Oid nameType, Oid mech)
	throws GSSException;

	/**
	* Factory method for acquiring default credentials. This will cause
	* the GSS-API to use system specific defaults for the set of mechanisms,
	* name, and lifetime.<p>
	*
	* GSS-API mechanism providers must impose a local access-control
	* policy on callers to prevent unauthorized callers from acquiring
	* credentials to which they are not entitled. The kinds of permissions
	* needed by different mechanism providers will be documented on a
	* per-mechanism basis. A failed permission check might cause a {@link
	* java.lang.SecurityException SecurityException} to be thrown from
	* this method.
	*
	* @param usage The intended usage for this credential object. The value
	* of this parameter must be one of:
	* {@link GSSCredential#INITIATE_AND_ACCEPT
	* GSSCredential.INITIATE_AND_ACCEPT},
	* {@link GSSCredential#ACCEPT_ONLY GSSCredential.ACCEPT_ONLY}, and
	* {@link GSSCredential#INITIATE_ONLY GSSCredential.INITIATE_ONLY}.
	* @return a GSSCredential of the requested type.
	*
	* @see GSSCredential
	*
	* @throws GSSException containing the following
	* major error codes:
	* {@link GSSException#BAD_MECH GSSException.BAD_MECH},
	* {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
	* {@link GSSException#BAD_NAME GSSException.BAD_NAME},
	* {@link GSSException#CREDENTIALS_EXPIRED
	* GSSException.CREDENTIALS_EXPIRED},
	* {@link GSSException#NO_CRED GSSException.NO_CRED},
	* {@link GSSException#FAILURE GSSException.FAILURE}
	*/
	public abstract GSSCredential createCredential (int usage)
	throws GSSException;

	/**
	* Factory method for acquiring a single mechanism credential.<p>
	*
	* GSS-API mechanism providers must impose a local access-control
	* policy on callers to prevent unauthorized callers from acquiring
	* credentials to which they are not entitled. The kinds of permissions
	* needed by different mechanism providers will be documented on a
	* per-mechanism basis. A failed permission check might cause a {@link
	* java.lang.SecurityException SecurityException} to be thrown from
	* this method. <p>
	*
	* Non-default values for lifetime cannot always be honored by the
	* underlying mechanisms, thus applications should be prepared to call
	* {@link GSSCredential#getRemainingLifetime() getRemainingLifetime}
	* on the returned credential.<p>
	*
	* @param name the name of the principal for whom this credential is to be
	* acquired. Use <code>null</code> to specify the default principal.
	* @param lifetime The number of seconds that credentials should remain
	* valid. Use {@link GSSCredential#INDEFINITE_LIFETIME
	* GSSCredential.INDEFINITE_LIFETIME} to request that the credentials
	* have the maximum permitted lifetime. Use {@link
	* GSSCredential#DEFAULT_LIFETIME GSSCredential.DEFAULT_LIFETIME} to
	* request default credential lifetime.
	* @param mech the Oid of the desired mechanism. Use <code>(Oid) null
	* </code> to request the default mechanism.
	* @param usage The intended usage for this credential object. The value
	* of this parameter must be one of:
	* {@link GSSCredential#INITIATE_AND_ACCEPT
	* GSSCredential.INITIATE_AND_ACCEPT},
	* {@link GSSCredential#ACCEPT_ONLY GSSCredential.ACCEPT_ONLY}, and
	* {@link GSSCredential#INITIATE_ONLY GSSCredential.INITIATE_ONLY}.
	* @return a GSSCredential of the requested type.
	*
	* @see GSSCredential
	*
	* @throws GSSException containing the following
	* major error codes:
	* {@link GSSException#BAD_MECH GSSException.BAD_MECH},
	* {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
	* {@link GSSException#BAD_NAME GSSException.BAD_NAME},
	* {@link GSSException#CREDENTIALS_EXPIRED
	* GSSException.CREDENTIALS_EXPIRED},
	* {@link GSSException#NO_CRED GSSException.NO_CRED},
	* {@link GSSException#FAILURE GSSException.FAILURE}
	*/
	public abstract GSSCredential createCredential (GSSName name,
	int lifetime, Oid mech, int usage)
	throws GSSException;

	/**
	* Factory method for acquiring credentials over a set of
	* mechanisms. This method attempts to acquire credentials for
	* each of the mechanisms specified in the array called mechs. To
	* determine the list of mechanisms for which the acquisition of
	* credentials succeeded, the caller should use the {@link
	* GSSCredential#getMechs() GSSCredential.getMechs} method.<p>
	*
	* GSS-API mechanism providers must impose a local access-control
	* policy on callers to prevent unauthorized callers from acquiring
	* credentials to which they are not entitled. The kinds of permissions
	* needed by different mechanism providers will be documented on a
	* per-mechanism basis. A failed permission check might cause a {@link
	* java.lang.SecurityException SecurityException} to be thrown from
	* this method.<p>
	*
	* Non-default values for lifetime cannot always be honored by the
	* underlying mechanisms, thus applications should be prepared to call
	* {@link GSSCredential#getRemainingLifetime() getRemainingLifetime}
	* on the returned credential.<p>
	*
	* @param name the name of the principal for whom this credential is to
	* be acquired. Use <code>null</code> to specify the default
	* principal.
	* @param lifetime The number of seconds that credentials should remain
	* valid. Use {@link GSSCredential#INDEFINITE_LIFETIME
	* GSSCredential.INDEFINITE_LIFETIME} to request that the credentials
	* have the maximum permitted lifetime. Use {@link
	* GSSCredential#DEFAULT_LIFETIME GSSCredential.DEFAULT_LIFETIME} to
	* request default credential lifetime.
	* @param mechs an array of Oid's indicating the mechanisms over which
	* the credential is to be acquired. Use <code>(Oid[]) null</code> for
	* requesting a system specific default set of mechanisms.
	* @param usage The intended usage for this credential object. The value
	* of this parameter must be one of:
	* {@link GSSCredential#INITIATE_AND_ACCEPT
	* GSSCredential.INITIATE_AND_ACCEPT},
	* {@link GSSCredential#ACCEPT_ONLY GSSCredential.ACCEPT_ONLY}, and
	* {@link GSSCredential#INITIATE_ONLY GSSCredential.INITIATE_ONLY}.
	* @return a GSSCredential of the requested type.
	*
	* @see GSSCredential
	*
	* @throws GSSException containing the following
	* major error codes:
	* {@link GSSException#BAD_MECH GSSException.BAD_MECH},
	* {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},
	* {@link GSSException#BAD_NAME GSSException.BAD_NAME},
	* {@link GSSException#CREDENTIALS_EXPIRED
	* GSSException.CREDENTIALS_EXPIRED},
	* {@link GSSException#NO_CRED GSSException.NO_CRED},
	* {@link GSSException#FAILURE GSSException.FAILURE}
	*/
	public abstract GSSCredential createCredential(GSSName name,
	int lifetime, Oid mechs[], int usage)
	throws GSSException;

	/**
	* Factory method for creating a context on the initiator's
	* side.
	*
	* Some mechanism providers might require that the caller be granted
	* permission to initiate a security context. A failed permission check
	* might cause a {@link java.lang.SecurityException SecurityException}
	* to be thrown from this method.<p>
	*
	* Non-default values for lifetime cannot always be honored by the
	* underlying mechanism, thus applications should be prepared to call
	* {@link GSSContext#getLifetime() getLifetime} on the returned
	* context.<p>
	*
	* @param peer the name of the target peer.
	* @param mech the Oid of the desired mechanism. Use <code>null</code>
	* to request the default mechanism.
	* @param myCred the credentials of the initiator. Use
	* <code>null</code> to act as the default initiator principal.
	* @param lifetime the lifetime, in seconds, requested for the
	* context. Use {@link GSSContext#INDEFINITE_LIFETIME
	* GSSContext.INDEFINITE_LIFETIME} to request that the context have the
	* maximum permitted lifetime. Use {@link GSSContext#DEFAULT_LIFETIME
	* GSSContext.DEFAULT_LIFETIME} to request a default lifetime for the
	* context.
	* @return an unestablished GSSContext
	*
	* @see GSSContext
	*
	* @throws GSSException containing the following
	* major error codes:
	* {@link GSSException#NO_CRED GSSException.NO_CRED}
	* {@link GSSException#CREDENTIALS_EXPIRED
	* GSSException.CREDENTIALS_EXPIRED}
	* {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE}
	* {@link GSSException#BAD_MECH GSSException.BAD_MECH}
	* {@link GSSException#FAILURE GSSException.FAILURE}
	*/
	public abstract GSSContext createContext(GSSName peer, Oid mech,
	GSSCredential myCred, int lifetime)
	throws GSSException;

	/**
	* Factory method for creating a context on the acceptor' side. The
	* context's properties will be determined from the input token supplied
	* to the accept method.
	*
	* Some mechanism providers might require that the caller be granted
	* permission to accept a security context. A failed permission check
	* might cause a {@link java.lang.SecurityException SecurityException}
	* to be thrown from this method.
	*
	* @param myCred the credentials for the acceptor. Use
	* <code>null</code> to act as a default acceptor principal.
	* @return an unestablished GSSContext
	*
	* @see GSSContext
	*
	* @throws GSSException containing the following
	* major error codes:
	* {@link GSSException#NO_CRED GSSException.NO_CRED}
	* {@link GSSException#CREDENTIALS_EXPIRED
	* GSSException.CREDENTIALS_EXPIRED}
	* {@link GSSException#BAD_MECH GSSException.BAD_MECH}
	* {@link GSSException#FAILURE GSSException.FAILURE}
	*/
	public abstract GSSContext createContext(GSSCredential myCred)
	throws GSSException;

	/**
	* Factory method for creating a previously exported context. The
	* context properties will be determined from the input token and
	* cannot be modified through the set methods.<p>
	*
	* Implementations are not required to support the inter-process
	* transfer of security contexts. Before exporting a context, calling
	* the {@link GSSContext#isTransferable() GSSContext.isTransferable}
	* will indicate if the context is transferable. Calling this method in
	* an implementation that does not support it will result in a
	* <code>GSSException</code> with the error
	* code {@link GSSException#UNAVAILABLE GSSException.UNAVAILABLE}.
	*
	* Some mechanism providers might require that the caller be granted
	* permission to initiate or accept a security context. A failed
	* permission check might cause a {@link java.lang.SecurityException
	* SecurityException} to be thrown from this method.
	*
	* @param interProcessToken the token previously emitted from the
	* export method.
	* @return the previously established GSSContext
	*
	* @see GSSContext
	*
	* @throws GSSException containing the following
	* major error codes:
	* {@link GSSException#NO_CONTEXT GSSException.NO_CONTEXT},
	* {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN},
	* {@link GSSException#UNAVAILABLE GSSException.UNAVAILABLE},
	* {@link GSSException#UNAUTHORIZED GSSException.UNAUTHORIZED},
	* {@link GSSException#FAILURE GSSException.FAILURE}
	*/
	public abstract GSSContext createContext(byte [] interProcessToken)
	throws GSSException;

	/**
	* This method is used to indicate to the GSSManager that the
	* application would like a particular provider to be used ahead of all
	* others when support is desired for the given mechanism. When a value
	* of null is used instead of an <code>Oid</code> for the mechanism,
	* the GSSManager must use the indicated provider ahead of all others
	* no matter what the mechanism is. Only when the indicated provider
	* does not support the needed mechanism should the GSSManager move on
	* to a different provider.<p>
	*
	* Calling this method repeatedly preserves the older settings but
	* lowers them in preference thus forming an ordered list of provider
	* and <code>Oid</code> pairs that grows at the top.<p>
	*
	* Calling addProviderAtFront with a null <code>Oid</code> will remove
	* all previous preferences that were set for this provider in the
	* GSSManager instance. Calling addProviderAtFront with a non-null
	* <code>Oid</code> will remove any previous preference that was set
	* using this mechanism and this provider together.<p>
	*
	* If the GSSManager implementation does not support an SPI with a
	* pluggable provider architecture it should throw a GSSException with
	* the status code GSSException.UNAVAILABLE to indicate that the
	* operation is unavailable.<p>
	*
	* Suppose an application desired that the provider A always be checked
	* first when any mechanism is needed, it would call:<p>
	* <pre>
	* GSSManager mgr = GSSManager.getInstance();
	* // mgr may at this point have its own pre-configured list
	* // of provider preferences. The following will prepend to
	* // any such list:
	*
	* mgr.addProviderAtFront(A, null);
	* </pre>
	* Now if it also desired that the mechanism of Oid m1 always be
	* obtained from the provider B before the previously set A was checked,
	* it would call:<p>
	* <pre>
	* mgr.addProviderAtFront(B, m1);
	* </pre>
	* The GSSManager would then first check with B if m1 was needed. In
	* case B did not provide support for m1, the GSSManager would continue
	* on to check with A. If any mechanism m2 is needed where m2 is
	* different from m1 then the GSSManager would skip B and check with A
	* directly.<p>
	*
	* Suppose at a later time the following call is made to the same
	* GSSManager instance:<p>
	* <pre>
	* mgr.addProviderAtFront(B, null)
	* </pre>
	* then the previous setting with the pair (B, m1) is subsumed by this
	* and should be removed. Effectively the list of preferences now
	* becomes {(B, null), (A, null),
	* ... //followed by the pre-configured list.<p>
	*
	* Please note, however, that the following call:
	* <pre>
	* mgr.addProviderAtFront(A, m3)
	* </pre>
	* does not subsume the previous setting of (A, null) and the list will
	* effectively become {(A, m3), (B, null), (A, null), ...}
	*
	* @param p the provider instance that should be used whenever support
	* is needed for mech.
	* @param mech the mechanism for which the provider is being set
	*
	* @throws GSSException containing the following
	* major error codes:
	* {@link GSSException#UNAVAILABLE GSSException.UNAVAILABLE},
	* {@link GSSException#FAILURE GSSException.FAILURE}
	*/
	public abstract void addProviderAtFront(Provider p, Oid mech)
	throws GSSException;

	/**
	* This method is used to indicate to the GSSManager that the
	* application would like a particular provider to be used if no other
	* provider can be found that supports the given mechanism. When a value
	* of null is used instead of an Oid for the mechanism, the GSSManager
	* must use the indicated provider for any mechanism.<p>
	*
	* Calling this method repeatedly preserves the older settings but
	* raises them above newer ones in preference thus forming an ordered
	* list of providers and Oid pairs that grows at the bottom. Thus the
	* older provider settings will be utilized first before this one is.<p>
	*
	* If there are any previously existing preferences that conflict with
	* the preference being set here, then the GSSManager should ignore this
	* request.<p>
	*
	* If the GSSManager implementation does not support an SPI with a
	* pluggable provider architecture it should throw a GSSException with
	* the status code GSSException.UNAVAILABLE to indicate that the
	* operation is unavailable.<p>
	*
	* Suppose an application desired that when a mechanism of Oid m1 is
	* needed the system default providers always be checked first, and only
	* when they do not support m1 should a provider A be checked. It would
	* then make the call:<p>
	* <pre>
	* GSSManager mgr = GSSManager.getInstance();
	* mgr.addProviderAtEnd(A, m1);
	* </pre>
	* Now, if it also desired that for all mechanisms the provider B be
	* checked after all configured providers have been checked, it would
	* then call:<p>
	* <pre>
	* mgr.addProviderAtEnd(B, null);
	* </pre>
	* Effectively the list of preferences now becomes {..., (A, m1), (B,
	* null)}.<p>
	*
	* Suppose at a later time the following call is made to the same
	* GSSManager instance:<p>
	* <pre>
	* mgr.addProviderAtEnd(B, m2)
	* </pre>
	* then the previous setting with the pair (B, null) subsumes this and
	* therefore this request should be ignored. The same would happen if a
	* request is made for the already existing pairs of (A, m1) or (B,
	* null).<p>
	*
	* Please note, however, that the following call:<p>
	* <pre>
	* mgr.addProviderAtEnd(A, null)
	* </pre>
	* is not subsumed by the previous setting of (A, m1) and the list will
	* effectively become {..., (A, m1), (B, null), (A, null)}
	*
	* @param p the provider instance that should be used whenever support
	* is needed for mech.
	* @param mech the mechanism for which the provider is being set
	*
	* @throws GSSException containing the following
	* major error codes:
	* {@link GSSException#UNAVAILABLE GSSException.UNAVAILABLE},
	* {@link GSSException#FAILURE GSSException.FAILURE}
	*/
	public abstract void addProviderAtEnd(Provider p, Oid mech)
	throws GSSException;
	}

Back to index...