Java example source code file (MechanismFactory.java)

This example Java source code file (MechanismFactory.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

gsscontextspi, gsscredentialspi, gssexception, gssnamespi, mechanismfactory, oid, provider, security

The MechanismFactory.java Java example source code

/*
 * Copyright (c) 2000, 2006, 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 sun.security.jgss.spi;

import org.ietf.jgss.*;
import java.security.Provider;

/**
 * This interface is implemented by the factory class for every
 * plugin mechanism. The GSSManager locates an implementation of this
 * interface by querying the security providers installed on the
 * system. For a provider to support a mechanism defined by Oid x.y.z,
 * the provider master file would have to contain a mapping from the
 * property "GssApiMechanism.x.y.z" to an implementation class that serves
 * as the factory for that mechanism.
 * <p>
 * e.g., If a provider master file contained the a mapping from the
 * property "GssApiMechanism.1.2.840.113554.1.2.2" to the class name
 * "com.foo.krb5.Krb5GssFactory", then the GSS-API framework would assume
 * that com.foo.krb5.Krb5GssFactory implements the MechanismFactory
 * interface and that it can be used to obtain elements required by for
 * supporting this mechanism.
 *
 * @author Mayank Upadhyay
 */

public interface MechanismFactory {

    /**
     * Returns the Oid of the mechanism that this factory supports.
     * @return the Oid
     */
    public Oid getMechanismOid();

    /**
     * Returns the provider that this factory came from.
     * @return the provider
     */
    public Provider getProvider();

    /**
     * Returns the GSS-API nametypes that this mechanism can
     * support. Having this method helps the GSS-Framework decide quickly
     * if a certain mechanism can be skipped when importing a name.
     * @return an array of the Oid's corresponding to the different GSS-API
     * nametypes supported
     * @see org.ietf.jgss.GSSName
     */
    public Oid[] getNameTypes() throws GSSException;

    /**
     * Creates a credential element for this mechanism to be included as
     * part of a GSSCredential implementation. A GSSCredential is
     * conceptually a container class of several credential elements from
     * different mechanisms. A GSS-API credential can be used either for
     * initiating GSS security contexts or for accepting them. This method
     * also accepts parameters that indicate what usage is expected and how
     * long the life of the credential should be. It is not necessary that
     * the mechanism honor the request for lifetime. An application will
     * always query an acquired GSSCredential to determine what lifetime it
     * got back.<p>
     *
     * <b>Not all mechanisms support the concept of one credential element
     * that can be used for both initiating and accepting a context. In the
     * event that an application requests usage INITIATE_AND_ACCEPT for a
     * credential from such a mechanism, the GSS framework will need to
     * obtain two different credential elements from the mechanism, one
     * that will have usage INITIATE_ONLY and another that will have usage
     * ACCEPT_ONLY. The mechanism will help the GSS-API realize this by
     * returning a credential element with usage INITIATE_ONLY or
     * ACCEPT_ONLY prompting it to make another call to
     * getCredentialElement, this time with the other usage mode. The
     * mechanism indicates the missing mode by returning a 0 lifetime for
     * it.</b>
     *
     * @param name the mechanism level name element for the entity whose
     * credential is desired. A null value indicates that a mechanism
     * dependent default choice is to be made.
     * @param initLifetime indicates the lifetime (in seconds) that is
     * requested for this credential to be used at the context initiator's
     * end. This value should be ignored if the usage is
     * ACCEPT_ONLY. Predefined contants are available in the
     * org.ietf.jgss.GSSCredential interface.
     * @param acceptLifetime indicates the lifetime (in seconds) that is
     * requested for this credential to be used at the context acceptor's
     * end. This value should be ignored if the usage is
     * INITIATE_ONLY. Predefined contants are available in the
     * org.ietf.jgss.GSSCredential interface.
     * @param usage One of the values GSSCredential.INIATE_ONLY,
     * GSSCredential.ACCEPT_ONLY, and GSSCredential.INITIATE_AND_ACCEPT.
     * @see org.ietf.jgss.GSSCredential
     * @throws GSSException if one of the error situations described in RFC
     * 2743 with the GSS_Acquire_Cred or GSS_Add_Cred calls occurs.
     */
    public GSSCredentialSpi getCredentialElement(GSSNameSpi name,
      int initLifetime, int acceptLifetime, int usage) throws GSSException;

    /**
     * Creates a name element for this mechanism to be included as part of
     * a GSSName implementation. A GSSName is conceptually a container
     * class of several name elements from different mechanisms. A GSSName
     * can be created either with a String or with a sequence of
     * bytes. This factory method accepts the name in a String. Such a name
     * can generally be assumed to be printable and may be returned from
     * the name element's toString() method.
     *
     * @param nameStr a string containing the characters describing this
     * entity to the mechanism
     * @param nameType an Oid serving as a clue as to how the mechanism should
     * interpret the nameStr
     * @throws GSSException if any of the errors described in RFC 2743 for
     * the GSS_Import_Name or GSS_Canonicalize_Name calls occur.
     */
    public GSSNameSpi getNameElement(String nameStr, Oid nameType)
        throws GSSException;

    /**
     * This is a variation of the factory method that accepts a String for
     * the characters that make up the name. Usually the String characters
     * are assumed to be printable. The bytes passed in to this method have
     * to be converted to characters using some encoding of the mechanism's
     * choice. It is recommended that UTF-8 be used. (Note that UTF-8
     * preserves the encoding for 7-bit ASCII characters.)
     * <p>
     * An exported name will generally be passed in using this method.
     *
     * @param nameBytes the bytes describing this entity to the mechanism
     * @param nameType an Oid serving as a clue as to how the mechanism should
     * interpret the nameStr
     * @throws GSSException if any of the errors described in RFC 2743 for
     * the GSS_Import_Name or GSS_Canonicalize_Name calls occur.
     */
    public GSSNameSpi getNameElement(byte[] name, Oid nameType)
        throws GSSException;

    /**
     * Creates a security context for this mechanism so that it can be used
     * on the context initiator's side.
     *
     * @param peer the name element from this mechanism that represents the
     * peer
     * @param myInitiatorCred a credential element for the context
     * initiator obtained previously from this mechanism. The identity of
     * the context initiator can be obtained from this credential. Passing
     * a value of null here indicates that a default entity of the
     * mechanism's choice should be assumed to be the context initiator and
     * that default credentials should be applied.
     * @param lifetime the requested lifetime (in seconds) for the security
     * context. Predefined contants are available in the
     * org.ietf.jgss.GSSContext interface.
     * @throws GSSException if any of the errors described in RFC 2743 in
     * the GSS_Init_Sec_Context call occur.
     */
    public GSSContextSpi getMechanismContext(GSSNameSpi peer,
                                             GSSCredentialSpi myInitiatorCred,
                                             int lifetime) throws GSSException;

    /**
     * Creates a security context for this mechanism so thatit can be used
     * on the context acceptor's side.
     *
     * @param myAcceptorCred a credential element for the context acceptor
     * obtained previously from this mechanism. The identity of the context
     * acceptor cna be obtained from this credential. Passing a value of
     * null here indicates that tha default entity of the mechanism's
     * choice should be assumed to be the context acceptor and default
     * credentials should be applied.
     *
     * @throws GSSException if any of the errors described in RFC 2743 in
     * the GSS_Accept_Sec_Context call occur.
     */
    public GSSContextSpi getMechanismContext(GSSCredentialSpi myAcceptorCred)
        throws GSSException;

    /**
     * Creates a security context from a previously exported (serialized)
     * security context. Note that this is different from Java
     * serialization and is defined at a mechanism level to interoperate
     * over the wire with non-Java implementations. Either the initiator or
     * the acceptor can export and then import a security context.
     * Implementations of mechanism contexts are not required to implement
     * exporting and importing.
     *
     * @param exportedContext the bytes representing this security context
     * @throws GSSException is any of the errors described in RFC 2743 in
     * the GSS_Import_Sec_Context call occur.
     */
    public GSSContextSpi getMechanismContext(byte[] exportedContext)
        throws GSSException;

}