001/* GSSManager.java -- manager class for the GSS-API.
002   Copyright (C) 2004 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception 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
042Copyright (C) The Internet Society (2000).  All Rights Reserved.
043
044This document and translations of it may be copied and furnished to
045others, and derivative works that comment on or otherwise explain it
046or assist in its implementation may be prepared, copied, published and
047distributed, in whole or in part, without restriction of any kind,
048provided that the above copyright notice and this paragraph are
049included on all such copies and derivative works.  However, this
050document itself may not be modified in any way, such as by removing
051the copyright notice or references to the Internet Society or other
052Internet organizations, except as needed for the purpose of developing
053Internet standards in which case the procedures for copyrights defined
054in the Internet Standards process must be followed, or as required to
055translate it into languages other than English.
056
057The limited permissions granted above are perpetual and will not be
058revoked by the Internet Society or its successors or assigns.
059
060This document and the information contained herein is provided on an
061"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
062TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT
063NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN
064WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
065MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. */
066
067
068package org.ietf.jgss;
069
070import java.security.Provider;
071import 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>
135GSSManager mgr = GSSManager.getInstance();
136
137// What mechs are available to us?
138Oid[] 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
143Oid krb = new Oid("1.2.840.113554.1.2.2");
144Oid spkm1 = new Oid("1.3.6.1.5.5.1.1");
145
146Provider p = (Provider) (new com.foo.security.Provider());
147
148mgr.addProviderAtFront(p, krb);
149mgr.addProviderAtFront(p, spkm1);
150
151// What name types does this spkm implementation support?
152Oid[] nameTypes = mgr.getNamesForMech(spkm1);
153</pre>
154 */
155public 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}