001: /*
002: * Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package sun.security.jgss.spi;
027:
028: import org.ietf.jgss.*;
029: import java.security.Provider;
030:
031: /**
032: * This interface is implemented by the factory class for every
033: * plugin mechanism. The GSSManager locates an implementation of this
034: * interface by querying the security providers installed on the
035: * system. For a provider to support a mechanism defined by Oid x.y.z,
036: * the provider master file would have to contain a mapping from the
037: * property "GssApiMechanism.x.y.z" to an implementation class that serves
038: * as the factory for that mechanism.
039: * <p>
040: * e.g., If a provider master file contained the a mapping from the
041: * property "GssApiMechanism.1.2.840.113554.1.2.2" to the class name
042: * "com.foo.krb5.Krb5GssFactory", then the GSS-API framework would assume
043: * that com.foo.krb5.Krb5GssFactory implements the MechanismFactory
044: * interface and that it can be used to obtain elements required by for
045: * supporting this mechanism.
046: *
047: * @author Mayank Upadhyay
048: * @version 1.13, 05/05/07
049: */
050:
051: public interface MechanismFactory {
052:
053: /**
054: * Returns the Oid of the mechanism that this factory supports.
055: * @return the Oid
056: */
057: public Oid getMechanismOid();
058:
059: /**
060: * Returns the provider that this factory came from.
061: * @return the provider
062: */
063: public Provider getProvider();
064:
065: /**
066: * Returns the GSS-API nametypes that this mechanism can
067: * support. Having this method helps the GSS-Framework decide quickly
068: * if a certain mechanism can be skipped when importing a name.
069: * @return an array of the Oid's corresponding to the different GSS-API
070: * nametypes supported
071: * @see org.ietf.jgss.GSSName
072: */
073: public Oid[] getNameTypes() throws GSSException;
074:
075: /**
076: * Creates a credential element for this mechanism to be included as
077: * part of a GSSCredential implementation. A GSSCredential is
078: * conceptually a container class of several credential elements from
079: * different mechanisms. A GSS-API credential can be used either for
080: * initiating GSS security contexts or for accepting them. This method
081: * also accepts parameters that indicate what usage is expected and how
082: * long the life of the credential should be. It is not necessary that
083: * the mechanism honor the request for lifetime. An application will
084: * always query an acquired GSSCredential to determine what lifetime it
085: * got back.<p>
086: *
087: * <b>Not all mechanisms support the concept of one credential element
088: * that can be used for both initiating and accepting a context. In the
089: * event that an application requests usage INITIATE_AND_ACCEPT for a
090: * credential from such a mechanism, the GSS framework will need to
091: * obtain two different credential elements from the mechanism, one
092: * that will have usage INITIATE_ONLY and another that will have usage
093: * ACCEPT_ONLY. The mechanism will help the GSS-API realize this by
094: * returning a credential element with usage INITIATE_ONLY or
095: * ACCEPT_ONLY prompting it to make another call to
096: * getCredentialElement, this time with the other usage mode. The
097: * mechanism indicates the missing mode by returning a 0 lifetime for
098: * it.</b>
099: *
100: * @param name the mechanism level name element for the entity whose
101: * credential is desired. A null value indicates that a mechanism
102: * dependent default choice is to be made.
103: * @param initLifetime indicates the lifetime (in seconds) that is
104: * requested for this credential to be used at the context initiator's
105: * end. This value should be ignored if the usage is
106: * ACCEPT_ONLY. Predefined contants are available in the
107: * org.ietf.jgss.GSSCredential interface.
108: * @param acceptLifetime indicates the lifetime (in seconds) that is
109: * requested for this credential to be used at the context acceptor's
110: * end. This value should be ignored if the usage is
111: * INITIATE_ONLY. Predefined contants are available in the
112: * org.ietf.jgss.GSSCredential interface.
113: * @param usage One of the values GSSCredential.INIATE_ONLY,
114: * GSSCredential.ACCEPT_ONLY, and GSSCredential.INITIATE_AND_ACCEPT.
115: * @see org.ietf.jgss.GSSCredential
116: * @throws GSSException if one of the error situations described in RFC
117: * 2743 with the GSS_Acquire_Cred or GSS_Add_Cred calls occurs.
118: */
119: public GSSCredentialSpi getCredentialElement(GSSNameSpi name,
120: int initLifetime, int acceptLifetime, int usage)
121: throws GSSException;
122:
123: /**
124: * Creates a name element for this mechanism to be included as part of
125: * a GSSName implementation. A GSSName is conceptually a container
126: * class of several name elements from different mechanisms. A GSSName
127: * can be created either with a String or with a sequence of
128: * bytes. This factory method accepts the name in a String. Such a name
129: * can generally be assumed to be printable and may be returned from
130: * the name element's toString() method.
131: *
132: * @param nameStr a string containing the characters describing this
133: * entity to the mechanism
134: * @param nameType an Oid serving as a clue as to how the mechanism should
135: * interpret the nameStr
136: * @throws GSSException if any of the errors described in RFC 2743 for
137: * the GSS_Import_Name or GSS_Canonicalize_Name calls occur.
138: */
139: public GSSNameSpi getNameElement(String nameStr, Oid nameType)
140: throws GSSException;
141:
142: /**
143: * This is a variation of the factory method that accepts a String for
144: * the characters that make up the name. Usually the String characters
145: * are assumed to be printable. The bytes passed in to this method have
146: * to be converted to characters using some encoding of the mechanism's
147: * choice. It is recommended that UTF-8 be used. (Note that UTF-8
148: * preserves the encoding for 7-bit ASCII characters.)
149: * <p>
150: * An exported name will generally be passed in using this method.
151: *
152: * @param nameBytes the bytes describing this entity to the mechanism
153: * @param nameType an Oid serving as a clue as to how the mechanism should
154: * interpret the nameStr
155: * @throws GSSException if any of the errors described in RFC 2743 for
156: * the GSS_Import_Name or GSS_Canonicalize_Name calls occur.
157: */
158: public GSSNameSpi getNameElement(byte[] name, Oid nameType)
159: throws GSSException;
160:
161: /**
162: * Creates a security context for this mechanism so that it can be used
163: * on the context initiator's side.
164: *
165: * @param peer the name element from this mechanism that represents the
166: * peer
167: * @param myInitiatorCred a credential element for the context
168: * initiator obtained previously from this mechanism. The identity of
169: * the context initiator can be obtained from this credential. Passing
170: * a value of null here indicates that a default entity of the
171: * mechanism's choice should be assumed to be the context initiator and
172: * that default credentials should be applied.
173: * @param lifetime the requested lifetime (in seconds) for the security
174: * context. Predefined contants are available in the
175: * org.ietf.jgss.GSSContext interface.
176: * @throws GSSException if any of the errors described in RFC 2743 in
177: * the GSS_Init_Sec_Context call occur.
178: */
179: public GSSContextSpi getMechanismContext(GSSNameSpi peer,
180: GSSCredentialSpi myInitiatorCred, int lifetime)
181: throws GSSException;
182:
183: /**
184: * Creates a security context for this mechanism so thatit can be used
185: * on the context acceptor's side.
186: *
187: * @param myAcceptorCred a credential element for the context acceptor
188: * obtained previously from this mechanism. The identity of the context
189: * acceptor cna be obtained from this credential. Passing a value of
190: * null here indicates that tha default entity of the mechanism's
191: * choice should be assumed to be the context acceptor and default
192: * credentials should be applied.
193: *
194: * @throws GSSException if any of the errors described in RFC 2743 in
195: * the GSS_Accept_Sec_Context call occur.
196: */
197: public GSSContextSpi getMechanismContext(
198: GSSCredentialSpi myAcceptorCred) throws GSSException;
199:
200: /**
201: * Creates a security context from a previously exported (serialized)
202: * security context. Note that this is different from Java
203: * serialization and is defined at a mechanism level to interoperate
204: * over the wire with non-Java implementations. Either the initiator or
205: * the acceptor can export and then import a security context.
206: * Implementations of mechanism contexts are not required to implement
207: * exporting and importing.
208: *
209: * @param exportedContext the bytes representing this security context
210: * @throws GSSException is any of the errors described in RFC 2743 in
211: * the GSS_Import_Sec_Context call occur.
212: */
213: public GSSContextSpi getMechanismContext(byte[] exportedContext)
214: throws GSSException;
215:
216: }
|