/*
* Copyright (c) 2000, 2001, 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 abitrary 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;
}