/* * 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. UseLines 1–500 of 729. Load more
/* * 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