001 /* GSSManager.java -- manager class for the GSS-API.
002 Copyright (C) 2004 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version.
037
038 The documentation comments of this class are derived from the text
039 of RFC 2853: Generic Security Service API Version 2: Java Bindings.
040 That document is covered under the following license notice:
041
042 Copyright (C) The Internet Society (2000). All Rights Reserved.
043
044 This document and translations of it may be copied and furnished to
045 others, and derivative works that comment on or otherwise explain it
046 or assist in its implementation may be prepared, copied, published and
047 distributed, in whole or in part, without restriction of any kind,
048 provided that the above copyright notice and this paragraph are
049 included on all such copies and derivative works. However, this
050 document itself may not be modified in any way, such as by removing
051 the copyright notice or references to the Internet Society or other
052 Internet organizations, except as needed for the purpose of developing
053 Internet standards in which case the procedures for copyrights defined
054 in the Internet Standards process must be followed, or as required to
055 translate it into languages other than English.
056
057 The limited permissions granted above are perpetual and will not be
058 revoked by the Internet Society or its successors or assigns.
059
060 This document and the information contained herein is provided on an
061 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
062 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT
063 NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN
064 WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
065 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. */
066
067
068 package org.ietf.jgss;
069
070 import java.security.Provider;
071 import java.security.Security;
072
073 /**
074 * <p>The GSSManager class is an abstract class that serves as a factory
075 * for three GSS interfaces: {@link GSSName}, {@link GSSCredential}, and
076 * {@link GSSContext}. It also provides methods for applications to determine
077 * what mechanisms are available from the GSS implementation and what
078 * nametypes these mechanisms support. An instance of the default GSSManager
079 * subclass may be obtained through the static method {@link #getInstance()},
080 * but applications are free to instantiate other subclasses of GSSManager.</p>
081 *
082 * <p>All but one method in this class are declared abstract. This means
083 * that subclasses have to provide the complete implementation for those
084 * methods. The only exception to this is the static method {@link
085 * #getInstance()} which will have platform specific code to return an
086 * instance of the default subclass.</p>
087 *
088 * <p>Platform providers of GSS are required not to add any constructors to
089 * this class, private, public, or protected. This will ensure that all
090 * subclasses invoke only the default constructor provided to the base
091 * class by the compiler.</p>
092 *
093 * <p>A subclass extending the GSSManager abstract class may be implemented
094 * as a modular provider based layer that utilizes some well known
095 * service provider specification. The GSSManager API provides the
096 * application with methods to set provider preferences on such an
097 * implementation. These methods also allow the implementation to throw
098 * a well-defined exception in case provider based configuration is not
099 * supported. Applications that expect to be portable should be aware of
100 * this and recover cleanly by catching the exception.</p>
101 *
102 * <p>It is envisioned that there will be three most common ways in which
103 * providers will be used:</p>
104 *
105 * <ol>
106 * <li>The application does not care about what provider is used (the
107 * default case).</li>
108 *
109 * <li>The application wants a particular provider to be used
110 * preferentially, either for a particular mechanism or all the
111 * time, irrespective of mechanism.</li>
112 *
113 * <li>The application wants to use the locally configured providers
114 * as far as possible but if support is missing for one or more
115 * mechanisms then it wants to fall back on its own provider.</li>
116 * </ol>
117 *
118 * <p>The GSSManager class has two methods that enable these modes of
119 * usage: {@link #addProviderAtFront(java.security.Provider,org.ietf.jgss.Oid)}
120 * and {@link #addProviderAtEnd(java.security.Provider,org.ietf.jgss.Oid)}.
121 * These methods have the effect of creating an ordered list of
122 * (<i>provider</i>, <i>oid</i>) pairs where each pair indicates a preference
123 * of provider for a given oid.</p>
124 *
125 * <p>The use of these methods does not require any knowledge of whatever
126 * service provider specification the GSSManager subclass follows. It is
127 * hoped that these methods will serve the needs of most applications.
128 * Additional methods may be added to an extended GSSManager that could
129 * be part of a service provider specification that is standardized
130 * later.</p>
131 *
132 * <h3>Example Code</h3>
133 *
134 * <pre>
135 GSSManager mgr = GSSManager.getInstance();
136
137 // What mechs are available to us?
138 Oid[] supportedMechs = mgr.getMechs();
139
140 // Set a preference for the provider to be used when support is needed
141 // for the mechanisms "1.2.840.113554.1.2.2" and "1.3.6.1.5.5.1.1".
142
143 Oid krb = new Oid("1.2.840.113554.1.2.2");
144 Oid spkm1 = new Oid("1.3.6.1.5.5.1.1");
145
146 Provider p = (Provider) (new com.foo.security.Provider());
147
148 mgr.addProviderAtFront(p, krb);
149 mgr.addProviderAtFront(p, spkm1);
150
151 // What name types does this spkm implementation support?
152 Oid[] nameTypes = mgr.getNamesForMech(spkm1);
153 </pre>
154 */
155 public abstract class GSSManager
156 {
157
158 // Constructor.
159 // -------------------------------------------------------------------------
160
161 public GSSManager()
162 {
163 }
164
165 // Class method.
166 // -------------------------------------------------------------------------
167
168 /**
169 * Returns the default GSSManager implementation.
170 *
171 * @return The default GSSManager implementation.
172 */
173 public static synchronized GSSManager getInstance()
174 {
175 String impl = Security.getProperty("org.ietf.jgss.GSSManager");
176 if (impl == null)
177 impl = "gnu.crypto.gssapi.GSSManagerImpl";
178 try
179 {
180 ClassLoader loader = GSSManager.class.getClassLoader();
181 if (loader == null)
182 loader = ClassLoader.getSystemClassLoader();
183 Class<?> c = loader.loadClass(impl);
184 return (GSSManager) c.newInstance();
185 }
186 catch (Exception x)
187 {
188 throw new RuntimeException(x.toString());
189 }
190 }
191
192 // Abstract methods.
193 // -------------------------------------------------------------------------
194
195 /**
196 * <p>This method is used to indicate to the GSSManager that the
197 * application would like a particular provider to be used if no other
198 * provider can be found that supports the given mechanism. When a value
199 * of null is used instead of an Oid for the mechanism, the GSSManager
200 * must use the indicated provider for any mechanism.</p>
201 *
202 * <p>Calling this method repeatedly preserves the older settings but
203 * raises them above newer ones in preference thus forming an ordered
204 * list of providers and Oid pairs that grows at the bottom. Thus the
205 * older provider settings will be utilized first before this one is.</p>
206 *
207 * <p>If there are any previously existing preferences that conflict with
208 * the preference being set here, then the GSSManager should ignore this
209 * request.</p>
210 *
211 * <p>If the GSSManager implementation does not support an SPI with a
212 * pluggable provider architecture it should throw a GSSException with
213 * the status code {@link GSSException#UNAVAILABLE} to indicate that the
214 * operation is unavailable.</p>
215 *
216 * @param p The provider instance that should be used whenever
217 * support is needed for <i>mech</i>.
218 * @param mech The mechanism for which the provider is being set.
219 * @throws GSSException If this service is unavailable.
220 */
221 public abstract void addProviderAtEnd(Provider p, Oid mech)
222 throws GSSException;
223
224 /**
225 * <p>This method is used to indicate to the GSSManager that the
226 * application would like a particular provider to be used ahead of all
227 * others when support is desired for the given mechanism. When a value
228 * of null is used instead of an Oid for the mechanism, the GSSManager
229 * must use the indicated provider ahead of all others no matter what
230 * the mechanism is. Only when the indicated provider does not support
231 * the needed mechanism should the GSSManager move on to a different
232 * provider.</p>
233 *
234 * <p>Calling this method repeatedly preserves the older settings but
235 * lowers them in preference thus forming an ordered list of provider
236 * and Oid pairs that grows at the top.</p>
237 *
238 * <p>Calling addProviderAtFront with a null Oid will remove all previous
239 * preferences that were set for this provider in the GSSManager
240 * instance. Calling addProviderAtFront with a non-null Oid will remove
241 * any previous preference that was set using this mechanism and this
242 * provider together.</p>
243 *
244 * <p>If the GSSManager implementation does not support an SPI with a
245 * pluggable provider architecture it should throw a GSSException with
246 * the status code {@link GSSException#UNAVAILABLE} to indicate that the
247 * operation is unavailable.</p>
248 *
249 * @param p The provider instance that should be used whenever
250 * support is needed for <i>mech</i>.
251 * @param mech The mechanism for which the provider is being set.
252 * @throws GSSException If this service is unavailable.
253 */
254 public abstract void addProviderAtFront(Provider p, Oid mech)
255 throws GSSException;
256
257 /**
258 * Factory method for creating a previously exported context. The
259 * context properties will be determined from the input token and can't
260 * be modified through the set methods.
261 *
262 * @param interProcessToken The token previously emitted from the
263 * export method.
264 * @return The context.
265 * @throws GSSException If this operation fails.
266 */
267 public abstract GSSContext createContext(byte[] interProcessToken)
268 throws GSSException;
269
270 /**
271 * Factory method for creating a context on the acceptor' side. The
272 * context's properties will be determined from the input token supplied
273 * to the accept method.
274 *
275 * @param myCred Credentials for the acceptor. Use <code>null</code> to
276 * act as a default acceptor principal.
277 * @return The context.
278 * @throws GSSException If this operation fails.
279 */
280 public abstract GSSContext createContext(GSSCredential myCred)
281 throws GSSException;
282
283 /**
284 * Factory method for creating a context on the initiator's side.
285 * Context flags may be modified through the mutator methods prior to
286 * calling {@link
287 * GSSContext#initSecContext(java.io.InputStream,java.io.OutputStream)}.
288 *
289 * @param peer Name of the target peer.
290 * @param mech Oid of the desired mechanism. Use <code>null</code>
291 * to request default mechanism.
292 * @param myCred Credentials of the initiator. Use <code>null</code>
293 * default initiator principal.
294 * @param lifetime The request lifetime, in seconds, for the context.
295 * Use {@link GSSContext#INDEFINITE_LIFETIME} and
296 * {@link GSSContext#DEFAULT_LIFETIME} to request
297 * indefinite or default context lifetime.
298 * @return The context.
299 * @throws GSSException If this operation fails.
300 */
301 public abstract GSSContext createContext(GSSName peer, Oid mech,
302 GSSCredential myCred, int lifetime)
303 throws GSSException;
304
305 /**
306 * Factory method for acquiring default credentials. This will cause
307 * the GSS-API to use system specific defaults for the set of
308 * mechanisms, name, and a DEFAULT lifetime.
309 *
310 * @param usage The intended usage for this credential object. The
311 * value of this parameter must be one of:
312 * {@link GSSCredential#ACCEPT_AND_INITIATE},
313 * {@link GSSCredential#ACCEPT_ONLY},
314 * {@link GSSCredential#INITIATE_ONLY}.
315 * @return The credential.
316 * @throws GSSException If this operation fails.
317 */
318 public abstract GSSCredential createCredential(int usage) throws GSSException;
319
320 /**
321 * Factory method for acquiring a single mechanism credential.
322 *
323 * @param aName Name of the principal for whom this credential is to
324 * be acquired. Use <code>null</code> to specify the
325 * default principal.
326 * @param lifetime The number of seconds that credentials should remain
327 * valid. Use {@link GSSCredential#INDEFINITE_LIFETIME}
328 * to request that the credentials have the maximum
329 * permitted lifetime. Use {@link
330 * GSSCredential#DEFAULT_LIFETIME} to request default
331 * credential lifetime.
332 * @param mech The oid of the desired mechanism. Use <code>null</code>
333 * to request the default mechanism(s).
334 * @param usage The intended usage for this credential object. The
335 * value of this parameter must be one of:
336 * {@link GSSCredential#ACCEPT_AND_INITIATE},
337 * {@link GSSCredential#ACCEPT_ONLY},
338 * {@link GSSCredential#INITIATE_ONLY}.
339 * @return The credential.
340 * @throws GSSException If this operation fails.
341 */
342 public abstract GSSCredential createCredential(GSSName aName, int lifetime,
343 Oid mech, int usage)
344 throws GSSException;
345
346 /**
347 * Factory method for acquiring credentials over a set of mechanisms.
348 * Acquires credentials for each of the mechanisms specified in the
349 * array called mechs. To determine the list of mechanisms' for which
350 * the acquisition of credentials succeeded, the caller should use the
351 * {@link GSSCredential#getMechs()} method.
352 *
353 * @param aName Name of the principal for whom this credential is to
354 * be acquired. Use <code>null</code> to specify the
355 * default principal.
356 * @param lifetime The number of seconds that credentials should remain
357 * valid. Use {@link GSSCredential#INDEFINITE_LIFETIME}
358 * to request that the credentials have the maximum
359 * permitted lifetime. Use {@link
360 * GSSCredential#DEFAULT_LIFETIME} to request default
361 * credential lifetime.
362 * @param mechs The array of mechanisms over which the credential is
363 * to be acquired. Use <code>null</code> for requesting
364 * a system specific default set of mechanisms.
365 * @param usage The intended usage for this credential object. The
366 * value of this parameter must be one of:
367 * {@link GSSCredential#ACCEPT_AND_INITIATE},
368 * {@link GSSCredential#ACCEPT_ONLY},
369 * {@link GSSCredential#INITIATE_ONLY}.
370 * @return The credential.
371 * @throws GSSException If this operation fails.
372 */
373 public abstract GSSCredential createCredential(GSSName aName, int lifetime,
374 Oid[] mechs, int usage)
375 throws GSSException;
376
377 /**
378 * Factory method to convert a contiguous byte array containing a name
379 * from the specified namespace to a {@link GSSName} object. In general,
380 * the {@link GSSName} object created will not be an MN; two examples that
381 * are exceptions to this are when the namespace type parameter indicates
382 * {@link GSSName#NT_EXPORT_NAME} or when the GSS-API implementation is not
383 * multi-mechanism.
384 *
385 * @param name The byte array containing the name to create.
386 * @param nameType The Oid specifying the namespace of the name supplied
387 * in the byte array. Note that nameType serves to
388 * describe and qualify the interpretation of the input
389 * name byte array, it does not necessarily imply a type
390 * for the output GSSName implementation. "null" value
391 * can be used to specify that a mechanism specific
392 * default syntax should be assumed by each mechanism
393 * that examines the byte array.
394 * @return The name.
395 * @throws GSSException If this operation fails.
396 */
397 public abstract GSSName createName(byte[] name, Oid nameType)
398 throws GSSException;
399
400 /**
401 * Factory method to convert a contiguous byte array containing a name
402 * from the specified namespace to a GSSName object that is an MN. In
403 * other words, this method is a utility that does the equivalent of two
404 * steps: {@link #createName(byte[],org.ietf.jgss.Oid)} and then also
405 * {@link GSSName#canonicalize(org.ietf.jgss.Oid)}.
406 *
407 * @param name The byte array representing the name to create.
408 * @param nameType The Oid specifying the namespace of the name supplied
409 * in the byte array. Note that nameType serves to
410 * describe and qualify the interpretation of the input
411 * name byte array, it does not necessarily imply a type
412 * for the output GSSName implementation. "null" value
413 * can be used to specify that a mechanism specific
414 * default syntax should be assumed by each mechanism
415 * that examines the byte array.
416 * @param mech Oid specifying the mechanism for which this name
417 * should be created.
418 * @return The name.
419 * @throws GSSException If this operation fails.
420 */
421 public abstract GSSName createName(byte[] name, Oid nameType, Oid mech)
422 throws GSSException;
423
424 /**
425 * Factory method to convert a contiguous string name from the specified
426 * namespace to a {@link GSSName} object. In general, the {@link GSSName}
427 * object created will not be an MN; two examples that are exceptions to
428 * this are when the namespace type parameter indicates {@link
429 * GSSName#NT_EXPORT_NAME} or when the GSS-API implementation is not
430 * multi-mechanism.
431 *
432 * @param nameStr The string representing a printable form of the name
433 * to create.
434 * @param nameType The Oid specifying the namespace of the printable name
435 * supplied. Note that nameType serves to describe and
436 * qualify the interpretation of the input nameStr, it
437 * does not necessarily imply a type for the output
438 * GSSName implementation. "null" value can be used to
439 * specify that a mechanism specific default printable
440 * syntax should be assumed by each mechanism that
441 * examines nameStr.
442 * @return The name.
443 * @throws GSSException If this operation fails.
444 */
445 public abstract GSSName createName(String nameStr, Oid nameType)
446 throws GSSException;
447
448 /**
449 * Factory method to convert a contiguous string name from the specified
450 * namespace to an GSSName object that is a mechanism name (MN). In
451 * other words, this method is a utility that does the equivalent of two
452 * steps: the {@link #createName(java.lang.String,org.ietf.jgss.Oid)}
453 * and then also {@link GSSName#canonicalize(org.ietf.jgss.Oid)}.
454 *
455 * @param nameStr The string representing a printable form of the name
456 * to create.
457 * @param nameType The Oid specifying the namespace of the printable name
458 * supplied. Note that nameType serves to describe and
459 * qualify the interpretation of the input nameStr, it
460 * does not necessarily imply a type for the output
461 * GSSName implementation. "null" value can be used to
462 * specify that a mechanism specific default printable
463 * syntax should be assumed when the mechanism examines
464 * nameStr.
465 * @param mech Oid specifying the mechanism for which this name
466 * should be created.
467 * @return The name.
468 * @throws GSSException If this operation fails.
469 */
470 public abstract GSSName createName(String nameStr, Oid nameType, Oid mech)
471 throws GSSException;
472
473 /**
474 * Returns an array of {@link Oid} objects indicating mechanisms available
475 * to GSS-API callers. A <code>null</code> value is returned when no
476 * mechanism are available (an example of this would be when mechanism are
477 * dynamically configured, and currently no mechanisms are installed).
478 *
479 * @return The array of available mechanisms, or <code>null</code>.
480 */
481 public abstract Oid[] getMechs();
482
483 /**
484 * Returns an array of {@link Oid} objects corresponding to the mechanisms
485 * that support the specific name type. <code>null</code> is returned when
486 * no mechanisms are found to support the specified name type.
487 *
488 * @param name The Oid object for the name type.
489 * @return The array of mechanisms, or <code>null</code>.
490 */
491 public abstract Oid[] getMechsForName(Oid name);
492
493 /**
494 * Returns name type Oid's supported by the specified mechanism.
495 *
496 * @param mechanism The Oid object for the mechanism to query.
497 * @return The name type Oid's supported by the mechanism.
498 * @throws GSSException If this operation fails.
499 */
500 public abstract Oid[] getNamesForMech(Oid mechanism) throws GSSException;
501 }