/*

 * Copyright (c) 2000, 2015, 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:

 * <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>&lt;provider,

 * oid&gt;</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:

 * <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:

 *

 * <pre>

 *     // Acquire credentials for the server

 *     GSSCredential serverCreds = manager.createCredential(serverName,

 *                                             GSSCredential.DEFAULT_LIFETIME,

 *                                             krb5Mechanism,

 *                                             GSSCredential.ACCEPT_ONLY);

 *

 *     // Instantiate and initialize a security context that will

 *     // wait for an establishment request token from the client

 *     GSSContext context = manager.createContext(serverCreds);

 * </pre>

 *

 * @author Mayank Upadhyay

 * @see GSSName

 * @see GSSCredential

 * @see GSSContext

 * @since 1.4

 */

public abstract class GSSManager {

    /**

     * Returns the default GSSManager implementation.

     *

     * @return a GSSManager implementation

     */

    public static GSSManager getInstance() {

        return new sun.security.jgss.GSSManagerImpl();

    }

    /**

     * Returns a list of mechanisms that are available to GSS-API callers

     * through this GSSManager. The default GSSManager obtained from the

     * {@link #getInstance() getInstance()} method includes the Oid

     * "1.2.840.113554.1.2.2" in its list. This Oid identifies the Kerberos

     * v5 GSS-API mechanism that is defined in RFC 1964.

     *

     * @return an array of Oid objects corresponding to the mechanisms that

     * are available. A <code>null</code> value is returned when no

     * mechanism are available (an example of this would be when mechanism

     * are dynamically configured, and currently no mechanisms are

     * installed).

     */

    public  abstract Oid[] getMechs();

    /**

     * Returns then name types supported by the indicated mechanism.<p>

     *

     * The default GSSManager instance includes support for the Kerberos v5

     * mechanism. When this mechanism ("1.2.840.113554.1.2.2") is indicated,

     * the returned list will contain at least the following nametypes:

     * {@link GSSName#NT_HOSTBASED_SERVICE GSSName.NT_HOSTBASED_SERVICE},

     * {@link GSSName#NT_EXPORT_NAME GSSName.NT_EXPORT_NAME}, and the

     * Kerberos v5 specific Oid "1.2.840.113554.1.2.2.1". The namespace for

     * the Oid "1.2.840.113554.1.2.2.1" is defined in RFC 1964.

     *

     * @return an array of Oid objects corresponding to the name types that

     * the mechanism supports.

     * @param mech the Oid of the mechanism to query

     *

     * @see #getMechsForName(Oid)

     *

     * @throws GSSException containing the following

     * major error codes:

     *    {@link GSSException#BAD_MECH GSSException.BAD_MECH}

     *    {@link GSSException#FAILURE GSSException.FAILURE}

     */

    public abstract  Oid[] getNamesForMech(Oid mech)

        throws GSSException;

    /**

     * Returns a list of mechanisms that support the indicated name type.<p>

     *

     * The Kerberos v5 mechanism ("1.2.840.113554.1.2.2") will always be

     * returned in this list when the indicated nametype is one of

     * {@link GSSName#NT_HOSTBASED_SERVICE GSSName.NT_HOSTBASED_SERVICE},

     * {@link GSSName#NT_EXPORT_NAME GSSName.NT_EXPORT_NAME}, or

     * "1.2.840.113554.1.2.2.1".

     *

     * @return an array of Oid objects corresponding to the mechanisms that

     * support the specified name type.  <code>null</code> is returned when no

     * mechanisms are found to support the specified name type.

     * @param nameType the Oid of the name type to look for

     *

     * @see #getNamesForMech(Oid)

     */

    public abstract  Oid[] getMechsForName(Oid nameType);

    /**

     * Factory method to convert a string name from the

     * specified namespace to a GSSName object. In general, the

     * <code>GSSName</code> object created  will contain multiple

     * representations of the name, one for each mechanism that is

     * supported; two examples that are exceptions to this are when

     * the namespace type parameter indicates NT_EXPORT_NAME or when the

     * GSS-API implementation is not multi-mechanism. It is

     * not recommended to use this method with a NT_EXPORT_NAME type because

     * representing a previously exported name consisting of arbitrary bytes

     * as a String might cause problems with character encoding schemes. In

     * such cases it is recommended that the bytes be passed in directly to

     * the overloaded form of this method {@link #createName(byte[],

     * Oid) createName}.

     *

     * @param nameStr the string representing a printable form of the name to

     * create.

     * @param nameType the Oid specifying the namespace of the printable name

     * supplied. <code>null</code> can be used to specify

     * that a mechanism specific default printable syntax should

     * be assumed by each mechanism that examines nameStr.

     * It is not advisable to use the nametype NT_EXPORT_NAME with this

     * method.

     * @return a GSSName representing the indicated principal

     *

     * @see GSSName

     * @see GSSName#NT_EXPORT_NAME

     *

     * @throws GSSException containing the following

     * major error codes:

     *    {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},

     *    {@link GSSException#BAD_NAME GSSException.BAD_NAME},

     *    {@link GSSException#BAD_MECH GSSException.BAD_MECH},

     *    {@link GSSException#FAILURE GSSException.FAILURE}

     */

    public abstract GSSName createName(String nameStr, Oid nameType)

        throws GSSException;

    /**

     * Factory method to convert a byte array containing a

     * name from the specified namespace to a GSSName object. In general,

     * the <code>GSSName</code> object created  will contain multiple

     * representations of the name, one for each mechanism that is

     * supported; two examples that are exceptions to this are when the

     * namespace type parameter indicates NT_EXPORT_NAME or when the

     * GSS-API implementation is not multi-mechanism. The bytes that are

     * passed in are interpreted by each underlying mechanism according to

     * some encoding scheme of its choice for the given nametype.

     *

     * @param name the byte array containing the name to create

     * @param nameType the Oid specifying the namespace of the name supplied

     * in the byte array. <code>null</code> can be used to specify that a

     * mechanism specific default syntax should be assumed by each mechanism

     * that examines the byte array.

     * @return a GSSName representing the indicated principal

     *

     * @see GSSName

     * @see GSSName#NT_EXPORT_NAME

     *

     * @throws GSSException containing the following

     * major error codes:

     *    {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},

     *    {@link GSSException#BAD_NAME GSSException.BAD_NAME},

     *    {@link GSSException#BAD_MECH GSSException.BAD_MECH},

     *    {@link GSSException#FAILURE GSSException.FAILURE}

     */

    public abstract GSSName createName(byte name[], Oid nameType)

        throws GSSException;

    /**

     *  Factory method to convert a string name from the

     * specified namespace to a GSSName object and canonicalize it at the

     * same time for a mechanism. In other words, this method is

     * a utility that does the equivalent of two steps: the {@link

     * #createName(String, Oid) createName} and then also the {@link

     * GSSName#canonicalize(Oid) GSSName.canonicalize}.

     *

     * @param nameStr the string representing a printable form of the name to

     * create.

     * @param nameType the Oid specifying the namespace of the printable name

     * supplied. <code>null</code> can be used to specify

     * that a mechanism specific default printable syntax should

     * be assumed by each mechanism that examines nameStr.

     * It is not advisable to use the nametype NT_EXPORT_NAME with this

     * method.

     * @param mech Oid specifying the mechanism for which the name should be

     * canonicalized

     * @return a GSSName representing the indicated principal

     *

     * @see GSSName#canonicalize(Oid)

     * @see GSSName#NT_EXPORT_NAME

     *

     * @throws GSSException containing the following

     * major error codes:

     *    {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},

     *    {@link GSSException#BAD_NAME GSSException.BAD_NAME},

     *    {@link GSSException#BAD_MECH GSSException.BAD_MECH},

     *    {@link GSSException#FAILURE GSSException.FAILURE}

     */

    public abstract GSSName createName(String nameStr, Oid nameType,

                                       Oid mech) throws GSSException;

    /**

     *  Factory method to convert a byte array containing a

     * name from the specified namespace to a GSSName object and canonicalize

     * it at the same time for a mechanism. In other words, this method is a

     * utility that does the equivalent of two steps: the {@link

     * #createName(byte[], Oid) createName} and then also {@link

     * GSSName#canonicalize(Oid) GSSName.canonicalize}.

     *

     * @param name the byte array containing the name to create

     * @param nameType the Oid specifying the namespace of the name supplied

     * in the byte array. <code>null</code> can be used to specify that a

     * mechanism specific default syntax should be assumed by each mechanism

     * that examines the byte array.

     * @param mech Oid specifying the mechanism for which the name should be

     * canonicalized

     * @return a GSSName representing the indicated principal

     *

     * @see GSSName#canonicalize(Oid)

     * @see GSSName#NT_EXPORT_NAME

     *

     * @throws GSSException containing the following

     * major error codes:

     *    {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},

     *    {@link GSSException#BAD_NAME GSSException.BAD_NAME},

     *    {@link GSSException#BAD_MECH GSSException.BAD_MECH},

     *    {@link GSSException#FAILURE GSSException.FAILURE}

     */

    public abstract GSSName createName(byte name[], Oid nameType, Oid mech)

        throws GSSException;

    /**

     * Factory method for acquiring default credentials.  This will cause

     * the GSS-API to use system specific defaults for the set of mechanisms,

     * name, and lifetime.<p>

     *

     * GSS-API mechanism providers must impose a local access-control

     * policy on callers to prevent unauthorized callers from acquiring

     * credentials to which they are not entitled. The kinds of permissions

     * needed by different mechanism providers will be documented on a

     * per-mechanism basis. A failed permission check might cause a {@link

     * java.lang.SecurityException SecurityException} to be thrown from

     * this method.

     *

     * @param usage The intended usage for this credential object. The value

     * of this parameter must be one of:

     * {@link GSSCredential#INITIATE_AND_ACCEPT

     * GSSCredential.INITIATE_AND_ACCEPT},

     * {@link GSSCredential#ACCEPT_ONLY GSSCredential.ACCEPT_ONLY}, and

     * {@link GSSCredential#INITIATE_ONLY GSSCredential.INITIATE_ONLY}.

     * @return a GSSCredential of the requested type.

     *

     * @see GSSCredential

     *

     * @throws GSSException containing the following

     * major error codes:

     *    {@link GSSException#BAD_MECH GSSException.BAD_MECH},

     *    {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE},

     *    {@link GSSException#BAD_NAME GSSException.BAD_NAME},

     *    {@link GSSException#CREDENTIALS_EXPIRED

     *                                   GSSException.CREDENTIALS_EXPIRED},

     *    {@link GSSException#NO_CRED GSSException.NO_CRED},

     *    {@link GSSException#FAILURE GSSException.FAILURE}

     */

    public abstract GSSCredential createCredential (int usage)

        throws GSSException;

    /**

     * Factory method for acquiring a single mechanism credential.<p>

     *

     * GSS-API mechanism providers must impose a local access-control

     * policy on callers to prevent unauthorized callers from acquiring

     * credentials to which they are not entitled. The kinds of permissions

     * needed by different mechanism providers will be documented on a

     * per-mechanism basis. A failed permission check might cause a {@link

     * java.lang.SecurityException SecurityException} to be thrown from

     * this method. <p>

     *

     * Non-default values for lifetime cannot always be honored by the

     * underlying mechanisms, thus applications should be prepared to call

     * {@link GSSCredential#getRemainingLifetime() getRemainingLifetime}

     * on the returned credential.

     *

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

     *

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

     *

     * @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