https://openjdk.java.net/ 
/*
 * 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.


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

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

    
Returns the provider that this factory came from.

Returns:the provider
/**
     * 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.

See Also:
Returns:an array of the Oid's corresponding to the different GSS-API
nametypes supported
/**
     * 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.

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.

Params:
  • 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.
  • 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.
  • 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.
  • usage – One of the values GSSCredential.INIATE_ONLY,
GSSCredential.ACCEPT_ONLY, and GSSCredential.INITIATE_AND_ACCEPT.
Throws:
  • GSSException – if one of the error situations described in RFC
2743 with the GSS_Acquire_Cred or GSS_Add_Cred calls occurs.
See Also:
/**
     * 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.

Params:
  • nameStr – a string containing the characters describing this
entity to the mechanism
  • 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.
/**
     * 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.)


An exported name will generally be passed in using this method.

Params:
  • name – the bytes describing this entity to the mechanism
  • 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.
/**
     * 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 name 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.

Params:
  • peer – the name element from this mechanism that represents the
peer
  • 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.
  • 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.
/**
     * 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.

Params:
  • 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.
/**
     * 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.

Params:
  • 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.
/**
     * 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;

}