The GSSManager class is an abstract class that serves as a factory * for three GSS interfaces: {@link GSSName}, {@link GSSCredential}, and * {@link GSSContext}. It also provides methods for applications to determine * what mechanisms are available from the GSS implementation and what * nametypes these mechanisms support. An instance of the default GSSManager * subclass may be obtained through the static method {@link #getInstance()}, * but applications are free to instantiate other subclasses of GSSManager.
* *All but one method in this class are declared abstract. This means * that subclasses have to provide the complete implementation for those * methods. The only exception to this is the static method {@link * #getInstance()} which will have platform specific code to return an * instance of the default subclass.
* *Platform providers of GSS are required not to add any constructors to * this class, private, public, or protected. This will ensure that all * subclasses invoke only the default constructor provided to the base * class by the compiler.
* *A subclass extending the GSSManager abstract class may be implemented * as a modular provider based layer that utilizes some well known * service provider specification. The GSSManager API provides the * application with methods 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.
* *It is envisioned that there will be three most common ways in which * providers will be used:
* *The GSSManager class has two methods that enable these modes of * usage: {@link #addProviderAtFront(java.security.Provider,org.ietf.jgss.Oid)} * and {@link #addProviderAtEnd(java.security.Provider,org.ietf.jgss.Oid)}. * These methods have the effect of creating an ordered list of * (provider, oid) pairs where each pair indicates a preference * of provider for a given oid.
* *The use of these methods does not require any knowledge of whatever * service provider specification the GSSManager subclass follows. It is * hoped that these methods will serve the needs of most applications. * Additional methods may be added to an extended GSSManager that could * be part of a service provider specification that is standardized * later.
* *
GSSManager mgr = GSSManager.getInstance();
// What mechs are available to us?
Oid[] supportedMechs = mgr.getMechs();
// Set a preference for the provider to be used when support is needed
// for the mechanisms "1.2.840.113554.1.2.2" and "1.3.6.1.5.5.1.1".
Oid krb = new Oid("1.2.840.113554.1.2.2");
Oid spkm1 = new Oid("1.3.6.1.5.5.1.1");
Provider p = (Provider) (new com.foo.security.Provider());
mgr.addProviderAtFront(p, krb);
mgr.addProviderAtFront(p, spkm1);
// What name types does this spkm implementation support?
Oid[] nameTypes = mgr.getNamesForMech(spkm1);
*/
public abstract class GSSManager
{
// Constructor.
// -------------------------------------------------------------------------
public GSSManager()
{
}
// Class method.
// -------------------------------------------------------------------------
/**
* Returns the default GSSManager implementation.
*
* @return The default GSSManager implementation.
*/
public static synchronized GSSManager getInstance()
{
String impl = Security.getProperty("org.ietf.jgss.GSSManager");
if (impl == null)
impl = "gnu.crypto.gssapi.GSSManagerImpl";
try
{
ClassLoader loader = GSSManager.class.getClassLoader();
if (loader == null)
loader = ClassLoader.getSystemClassLoader();
Class c = loader.loadClass(impl);
return (GSSManager) c.newInstance();
}
catch (Exception x)
{
throw new RuntimeException(x.toString());
}
}
// Abstract methods.
// -------------------------------------------------------------------------
/**
* 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.
* *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.
* *If there are any previously existing preferences that conflict with * the preference being set here, then the GSSManager should ignore this * request.
* *If the GSSManager implementation does not support an SPI with a * pluggable provider architecture it should throw a GSSException with * the status code {@link GSSException#UNAVAILABLE} to indicate that the * operation is unavailable.
* * @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 If this service is unavailable. */ public abstract void addProviderAtEnd(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 ahead of all * others when support is desired for the given mechanism. When a value * of null is used instead of an Oid 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.
* *Calling this method repeatedly preserves the older settings but * lowers them in preference thus forming an ordered list of provider * and Oid pairs that grows at the top.
* *Calling addProviderAtFront with a null Oid will remove all previous * preferences that were set for this provider in the GSSManager * instance. Calling addProviderAtFront with a non-null Oid will remove * any previous preference that was set using this mechanism and this * provider together.
* *If the GSSManager implementation does not support an SPI with a * pluggable provider architecture it should throw a GSSException with * the status code {@link GSSException#UNAVAILABLE} to indicate that the * operation is unavailable.
* * @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 If this service is unavailable. */ public abstract void addProviderAtFront(Provider p, Oid mech) throws GSSException; /** * Factory method for creating a previously exported context. The * context properties will be determined from the input token and can't * be modified through the set methods. * * @param interProcessToken The token previously emitted from the * export method. * @return The context. * @throws GSSException If this operation fails. */ public abstract GSSContext createContext(byte[] interProcessToken) 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. * * @param myCred Credentials for the acceptor. Usenull to
* act as a default acceptor principal.
* @return The context.
* @throws GSSException If this operation fails.
*/
public abstract GSSContext createContext(GSSCredential myCred)
throws GSSException;
/**
* Factory method for creating a context on the initiator's side.
* Context flags may be modified through the mutator methods prior to
* calling {@link
* GSSContext#initSecContext(java.io.InputStream,java.io.OutputStream)}.
*
* @param peer Name of the target peer.
* @param mech Oid of the desired mechanism. Use null
* to request default mechanism.
* @param myCred Credentials of the initiator. Use null
* default initiator principal.
* @param lifetime The request lifetime, in seconds, for the context.
* Use {@link GSSContext#INDEFINITE_LIFETIME} and
* {@link GSSContext#DEFAULT_LIFETIME} to request
* indefinite or default context lifetime.
* @return The context.
* @throws GSSException If this operation fails.
*/
public abstract GSSContext createContext(GSSName peer, Oid mech,
GSSCredential myCred, int lifetime)
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 a DEFAULT lifetime.
*
* @param usage The intended usage for this credential object. The
* value of this parameter must be one of:
* {@link GSSCredential#ACCEPT_AND_INITIATE},
* {@link GSSCredential#ACCEPT_ONLY},
* {@link GSSCredential#INITIATE_ONLY}.
* @return The credential.
* @throws GSSException If this operation fails.
*/
public abstract GSSCredential createCredential(int usage) throws GSSException;
/**
* Factory method for acquiring a single mechanism credential.
*
* @param aName Name of the principal for whom this credential is to
* be acquired. Use null to specify the
* default principal.
* @param lifetime The number of seconds that credentials should remain
* valid. Use {@link GSSCredential#INDEFINITE_LIFETIME}
* to request that the credentials have the maximum
* permitted lifetime. Use {@link
* GSSCredential#DEFAULT_LIFETIME} to request default
* credential lifetime.
* @param mech The oid of the desired mechanism. Use null
* to request the default mechanism(s).
* @param usage The intended usage for this credential object. The
* value of this parameter must be one of:
* {@link GSSCredential#ACCEPT_AND_INITIATE},
* {@link GSSCredential#ACCEPT_ONLY},
* {@link GSSCredential#INITIATE_ONLY}.
* @return The credential.
* @throws GSSException If this operation fails.
*/
public abstract GSSCredential createCredential(GSSName aName, int lifetime,
Oid mech, int usage)
throws GSSException;
/**
* Factory method for acquiring credentials over a set of mechanisms.
* Acquires 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()} method.
*
* @param aName Name of the principal for whom this credential is to
* be acquired. Use null to specify the
* default principal.
* @param lifetime The number of seconds that credentials should remain
* valid. Use {@link GSSCredential#INDEFINITE_LIFETIME}
* to request that the credentials have the maximum
* permitted lifetime. Use {@link
* GSSCredential#DEFAULT_LIFETIME} to request default
* credential lifetime.
* @param mechs The array of mechanisms over which the credential is
* to be acquired. Use null 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#ACCEPT_AND_INITIATE},
* {@link GSSCredential#ACCEPT_ONLY},
* {@link GSSCredential#INITIATE_ONLY}.
* @return The credential.
* @throws GSSException If this operation fails.
*/
public abstract GSSCredential createCredential(GSSName aName, int lifetime,
Oid[] mechs, int usage)
throws GSSException;
/**
* Factory method to convert a contiguous byte array containing a name
* from the specified namespace to a {@link GSSName} object. In general,
* the {@link GSSName} object created will not be an MN; two examples that
* are exceptions to this are when the namespace type parameter indicates
* {@link GSSName#NT_EXPORT_NAME} or when the GSS-API implementation is not
* multi-mechanism.
*
* @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. Note that nameType serves to
* describe and qualify the interpretation of the input
* name byte array, it does not necessarily imply a type
* for the output GSSName implementation. "null" value
* can be used to specify that a mechanism specific
* default syntax should be assumed by each mechanism
* that examines the byte array.
* @return The name.
* @throws GSSException If this operation fails.
*/
public abstract GSSName createName(byte[] name, Oid nameType)
throws GSSException;
/**
* Factory method to convert a contiguous byte array containing a name
* from the specified namespace to a GSSName object that is an MN. In
* other words, this method is a utility that does the equivalent of two
* steps: {@link #createName(byte[],org.ietf.jgss.Oid)} and then also
* {@link GSSName#canonicalize(org.ietf.jgss.Oid)}.
*
* @param name The byte array representing the name to create.
* @param nameType The Oid specifying the namespace of the name supplied
* in the byte array. Note that nameType serves to
* describe and qualify the interpretation of the input
* name byte array, it does not necessarily imply a type
* for the output GSSName implementation. "null" value
* 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 this name
* should be created.
* @return The name.
* @throws GSSException If this operation fails.
*/
public abstract GSSName createName(byte[] name, Oid nameType, Oid mech)
throws GSSException;
/**
* Factory method to convert a contiguous string name from the specified
* namespace to a {@link GSSName} object. In general, the {@link GSSName}
* object created will not be an MN; two examples that are exceptions to
* this are when the namespace type parameter indicates {@link
* GSSName#NT_EXPORT_NAME} or when the GSS-API implementation is not
* multi-mechanism.
*
* @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. Note that nameType serves to describe and
* qualify the interpretation of the input nameStr, it
* does not necessarily imply a type for the output
* GSSName implementation. "null" value can be used to
* specify that a mechanism specific default printable
* syntax should be assumed by each mechanism that
* examines nameStr.
* @return The name.
* @throws GSSException If this operation fails.
*/
public abstract GSSName createName(String nameStr, Oid nameType)
throws GSSException;
/**
* Factory method to convert a contiguous string name from the specified
* namespace to an GSSName object that is a mechanism name (MN). In
* other words, this method is a utility that does the equivalent of two
* steps: the {@link #createName(java.lang.String,org.ietf.jgss.Oid)}
* and then also {@link GSSName#canonicalize(org.ietf.jgss.Oid)}.
*
* @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. Note that nameType serves to describe and
* qualify the interpretation of the input nameStr, it
* does not necessarily imply a type for the output
* GSSName implementation. "null" value can be used to
* specify that a mechanism specific default printable
* syntax should be assumed when the mechanism examines
* nameStr.
* @param mech Oid specifying the mechanism for which this name
* should be created.
* @return The name.
* @throws GSSException If this operation fails.
*/
public abstract GSSName createName(String nameStr, Oid nameType, Oid mech)
throws GSSException;
/**
* Returns an array of {@link Oid} objects indicating mechanisms available
* to GSS-API callers. A null 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).
*
* @return The array of available mechanisms, or null.
*/
public abstract Oid[] getMechs();
/**
* Returns an array of {@link Oid} objects corresponding to the mechanisms
* that support the specific name type. null is returned when
* no mechanisms are found to support the specified name type.
*
* @param name The Oid object for the name type.
* @return The array of mechanisms, or null.
*/
public abstract Oid[] getMechsForName(Oid name);
/**
* Returns name type Oid's supported by the specified mechanism.
*
* @param mechanism The Oid object for the mechanism to query.
* @return The name type Oid's supported by the mechanism.
* @throws GSSException If this operation fails.
*/
public abstract Oid[] getNamesForMech(Oid mechanism) throws GSSException;
}