| /* |
| * 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; |
| } |
