Source for org.ietf.jgss.GSSManager

   1: /* GSSManager.java -- manager class for the GSS-API.
   2:    Copyright (C) 2004 Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version.
  37: 
  38:    The documentation comments of this class are derived from the text
  39:    of RFC 2853:  Generic Security Service API Version 2: Java Bindings.
  40:    That document is covered under the following license notice:
  41: 
  42: Copyright (C) The Internet Society (2000).  All Rights Reserved.
  43: 
  44: This document and translations of it may be copied and furnished to
  45: others, and derivative works that comment on or otherwise explain it
  46: or assist in its implementation may be prepared, copied, published and
  47: distributed, in whole or in part, without restriction of any kind,
  48: provided that the above copyright notice and this paragraph are
  49: included on all such copies and derivative works.  However, this
  50: document itself may not be modified in any way, such as by removing
  51: the copyright notice or references to the Internet Society or other
  52: Internet organizations, except as needed for the purpose of developing
  53: Internet standards in which case the procedures for copyrights defined
  54: in the Internet Standards process must be followed, or as required to
  55: translate it into languages other than English.
  56: 
  57: The limited permissions granted above are perpetual and will not be
  58: revoked by the Internet Society or its successors or assigns.
  59: 
  60: This document and the information contained herein is provided on an
  61: "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
  62: TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT
  63: NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN
  64: WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
  65: MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. */
  66: 
  67: 
  68: package org.ietf.jgss;
  69: 
  70: import java.security.Provider;
  71: import java.security.Security;
  72: 
  73: /**
  74:  * <p>The GSSManager class is an abstract class that serves as a factory
  75:  * for three GSS interfaces: {@link GSSName}, {@link GSSCredential}, and
  76:  * {@link GSSContext}. It also provides methods for applications to determine
  77:  * what mechanisms are available from the GSS implementation and what
  78:  * nametypes these mechanisms support. An instance of the default GSSManager
  79:  * subclass may be obtained through the static method {@link #getInstance()},
  80:  * but applications are free to instantiate other subclasses of GSSManager.</p>
  81:  *
  82:  * <p>All but one method in this class are declared abstract. This means
  83:  * that subclasses have to provide the complete implementation for those
  84:  * methods. The only exception to this is the static method {@link
  85:  * #getInstance()} which will have platform specific code to return an
  86:  * instance of the default subclass.</p>
  87:  *
  88:  * <p>Platform providers of GSS are required not to add any constructors to
  89:  * this class, private, public, or protected. This will ensure that all
  90:  * subclasses invoke only the default constructor provided to the base
  91:  * class by the compiler.</p>
  92:  *
  93:  * <p>A subclass extending the GSSManager abstract class may be implemented
  94:  * as a modular provider based layer that utilizes some well known
  95:  * service provider specification. The GSSManager API provides the
  96:  * application with methods to set provider preferences on such an
  97:  * implementation. These methods also allow the implementation to throw
  98:  * a well-defined exception in case provider based configuration is not
  99:  * 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: }