diff options
Diffstat (limited to 'libjava/org/ietf/jgss/GSSManager.java')
-rw-r--r-- | libjava/org/ietf/jgss/GSSManager.java | 501 |
1 files changed, 0 insertions, 501 deletions
diff --git a/libjava/org/ietf/jgss/GSSManager.java b/libjava/org/ietf/jgss/GSSManager.java deleted file mode 100644 index 9f591e73eed..00000000000 --- a/libjava/org/ietf/jgss/GSSManager.java +++ /dev/null @@ -1,501 +0,0 @@ -/* GSSManager.java -- manager class for the GSS-API. - Copyright (C) 2004 Free Software Foundation, Inc. - -This file is part of GNU Classpath. - -GNU Classpath is free software; you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation; either version 2, or (at your option) -any later version. - -GNU Classpath 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 for more details. - -You should have received a copy of the GNU General Public License -along with GNU Classpath; see the file COPYING. If not, write to the -Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA -02110-1301 USA. - -Linking this library statically or dynamically with other modules is -making a combined work based on this library. Thus, the terms and -conditions of the GNU General Public License cover the whole -combination. - -As a special exception, the copyright holders of this library give you -permission to link this library with independent modules to produce an -executable, regardless of the license terms of these independent -modules, and to copy and distribute the resulting executable under -terms of your choice, provided that you also meet, for each linked -independent module, the terms and conditions of the license of that -module. An independent module is a module which is not derived from -or based on this library. If you modify this library, you may extend -this exception to your version of the library, but you are not -obligated to do so. If you do not wish to do so, delete this -exception statement from your version. */ - -/* The documentation comments of this class are derived from the text - of RFC 2853: Generic Security Service API Version 2: Java Bindings. - That document is covered under the following license notice: - -Copyright (C) The Internet Society (2000). All Rights Reserved. - -This document and translations of it may be copied and furnished to -others, and derivative works that comment on or otherwise explain it -or assist in its implementation may be prepared, copied, published and -distributed, in whole or in part, without restriction of any kind, -provided that the above copyright notice and this paragraph are -included on all such copies and derivative works. However, this -document itself may not be modified in any way, such as by removing -the copyright notice or references to the Internet Society or other -Internet organizations, except as needed for the purpose of developing -Internet standards in which case the procedures for copyrights defined -in the Internet Standards process must be followed, or as required to -translate it into languages other than English. - -The limited permissions granted above are perpetual and will not be -revoked by the Internet Society or its successors or assigns. - -This document and the information contained herein is provided on an -"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING -TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT -NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN -WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF -MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. */ - - -package org.ietf.jgss; - -import java.security.Provider; -import java.security.Security; - -/** - * <p>The GSSManager class is an abstract class that serves as a factory - * for three GSS interfaces: {@link GSSName}, {@link GSSCredential}, and - * {@link GSSContext}. It also provides methods for applications to determine - * what mechanisms are available from the GSS implementation and what - * nametypes these mechanisms support. An instance of the default GSSManager - * subclass may be obtained through the static method {@link #getInstance()}, - * but applications are free to instantiate other subclasses of GSSManager.</p> - * - * <p>All but one method in this class are declared abstract. This means - * that subclasses have to provide the complete implementation for those - * methods. The only exception to this is the static method {@link - * #getInstance()} which will have platform specific code to return an - * instance of the default subclass.</p> - * - * <p>Platform providers of GSS are required not to add any constructors to - * this class, private, public, or protected. This will ensure that all - * subclasses invoke only the default constructor provided to the base - * class by the compiler.</p> - * - * <p>A subclass extending the GSSManager abstract class may be implemented - * as a modular provider based layer that utilizes some well known - * service provider specification. The GSSManager API provides the - * application with methods to set provider preferences on such an - * implementation. These methods also allow the implementation to throw - * a well-defined exception in case provider based configuration is not - * supported. Applications that expect to be portable should be aware of - * this and recover cleanly by catching the exception.</p> - * - * <p>It is envisioned that there will be three most common ways in which - * providers will be used:</p> - * - * <ol> - * <li>The application does not care about what provider is used (the - * default case).</li> - * - * <li>The application wants a particular provider to be used - * preferentially, either for a particular mechanism or all the - * time, irrespective of mechanism.</li> - * - * <li>The application wants to use the locally configured providers - * as far as possible but if support is missing for one or more - * mechanisms then it wants to fall back on its own provider.</li> - * </ol> - * - * <p>The GSSManager class has two methods that enable these modes of - * usage: {@link #addProviderAtFront(java.security.Provider,org.ietf.jgss.Oid)} - * and {@link #addProviderAtEnd(java.security.Provider,org.ietf.jgss.Oid)}. - * These methods have the effect of creating an ordered list of - * (<i>provider</i>, <i>oid</i>) pairs where each pair indicates a preference - * of provider for a given oid.</p> - * - * <p>The use of these methods does not require any knowledge of whatever - * service provider specification the GSSManager subclass follows. It is - * hoped that these methods will serve the needs of most applications. - * Additional methods may be added to an extended GSSManager that could - * be part of a service provider specification that is standardized - * later.</p> - * - * <h3>Example Code</h3> - * - * <pre> -GSSManager mgr = GSSManager.getInstance(); - -// What mechs are available to us? -Oid[] supportedMechs = mgr.getMechs(); - -// Set a preference for the provider to be used when support is needed -// for the mechanisms "1.2.840.113554.1.2.2" and "1.3.6.1.5.5.1.1". - -Oid krb = new Oid("1.2.840.113554.1.2.2"); -Oid spkm1 = new Oid("1.3.6.1.5.5.1.1"); - -Provider p = (Provider) (new com.foo.security.Provider()); - -mgr.addProviderAtFront(p, krb); -mgr.addProviderAtFront(p, spkm1); - -// What name types does this spkm implementation support? -Oid[] nameTypes = mgr.getNamesForMech(spkm1); -</pre> - */ -public abstract class GSSManager -{ - - // Constructor. - // ------------------------------------------------------------------------- - - public GSSManager() - { - } - - // Class method. - // ------------------------------------------------------------------------- - - /** - * Returns the default GSSManager implementation. - * - * @return The default GSSManager implementation. - */ - public static synchronized GSSManager getInstance() - { - String impl = Security.getProperty("org.ietf.jgss.GSSManager"); - if (impl == null) - impl = "gnu.crypto.gssapi.GSSManagerImpl"; - try - { - ClassLoader loader = GSSManager.class.getClassLoader(); - if (loader == null) - loader = ClassLoader.getSystemClassLoader(); - Class c = loader.loadClass(impl); - return (GSSManager) c.newInstance(); - } - catch (Exception x) - { - throw new RuntimeException(x.toString()); - } - } - - // Abstract methods. - // ------------------------------------------------------------------------- - - /** - * <p>This method is used to indicate to the GSSManager that the - * application would like a particular provider to be used if no other - * provider can be found that supports the given mechanism. When a value - * of null is used instead of an Oid for the mechanism, the GSSManager - * must use the indicated provider for any mechanism.</p> - * - * <p>Calling this method repeatedly preserves the older settings but - * raises them above newer ones in preference thus forming an ordered - * list of providers and Oid pairs that grows at the bottom. Thus the - * older provider settings will be utilized first before this one is.</p> - * - * <p>If there are any previously existing preferences that conflict with - * the preference being set here, then the GSSManager should ignore this - * request.</p> - * - * <p>If the GSSManager implementation does not support an SPI with a - * pluggable provider architecture it should throw a GSSException with - * the status code {@link GSSException#UNAVAILABLE} to indicate that the - * operation is unavailable.</p> - * - * @param p The provider instance that should be used whenever - * support is needed for <i>mech</i>. - * @param mech The mechanism for which the provider is being set. - * @throws GSSException If this service is unavailable. - */ - public abstract void addProviderAtEnd(Provider p, Oid mech) - throws GSSException; - - /** - * <p>This method is used to indicate to the GSSManager that the - * application would like a particular provider to be used ahead of all - * others when support is desired for the given mechanism. When a value - * of null is used instead of an Oid for the mechanism, the GSSManager - * must use the indicated provider ahead of all others no matter what - * the mechanism is. Only when the indicated provider does not support - * the needed mechanism should the GSSManager move on to a different - * provider.</p> - * - * <p>Calling this method repeatedly preserves the older settings but - * lowers them in preference thus forming an ordered list of provider - * and Oid pairs that grows at the top.</p> - * - * <p>Calling addProviderAtFront with a null Oid will remove all previous - * preferences that were set for this provider in the GSSManager - * instance. Calling addProviderAtFront with a non-null Oid will remove - * any previous preference that was set using this mechanism and this - * provider together.</p> - * - * <p>If the GSSManager implementation does not support an SPI with a - * pluggable provider architecture it should throw a GSSException with - * the status code {@link GSSException#UNAVAILABLE} to indicate that the - * operation is unavailable.</p> - * - * @param p The provider instance that should be used whenever - * support is needed for <i>mech</i>. - * @param mech The mechanism for which the provider is being set. - * @throws GSSException If this service is unavailable. - */ - public abstract void addProviderAtFront(Provider p, Oid mech) - throws GSSException; - - /** - * Factory method for creating a previously exported context. The - * context properties will be determined from the input token and can't - * be modified through the set methods. - * - * @param interProcessToken The token previously emitted from the - * export method. - * @return The context. - * @throws GSSException If this operation fails. - */ - public abstract GSSContext createContext(byte[] interProcessToken) - throws GSSException; - - /** - * Factory method for creating a context on the acceptor' side. The - * context's properties will be determined from the input token supplied - * to the accept method. - * - * @param myCred Credentials for the acceptor. Use <code>null</code> to - * act as a default acceptor principal. - * @return The context. - * @throws GSSException If this operation fails. - */ - public abstract GSSContext createContext(GSSCredential myCred) - throws GSSException; - - /** - * Factory method for creating a context on the initiator's side. - * Context flags may be modified through the mutator methods prior to - * calling {@link - * GSSContext#initSecContext(java.io.InputStream,java.io.OutputStream)}. - * - * @param peer Name of the target peer. - * @param mech Oid of the desired mechanism. Use <code>null</code> - * to request default mechanism. - * @param myCred Credentials of the initiator. Use <code>null</code> - * default initiator principal. - * @param lifetime The request lifetime, in seconds, for the context. - * Use {@link GSSContext#INDEFINITE_LIFETIME} and - * {@link GSSContext#DEFAULT_LIFETIME} to request - * indefinite or default context lifetime. - * @return The context. - * @throws GSSException If this operation fails. - */ - public abstract GSSContext createContext(GSSName peer, Oid mech, - GSSCredential myCred, int lifetime) - throws GSSException; - - /** - * Factory method for acquiring default credentials. This will cause - * the GSS-API to use system specific defaults for the set of - * mechanisms, name, and a DEFAULT lifetime. - * - * @param usage The intended usage for this credential object. The - * value of this parameter must be one of: - * {@link GSSCredential#ACCEPT_AND_INITIATE}, - * {@link GSSCredential#ACCEPT_ONLY}, - * {@link GSSCredential#INITIATE_ONLY}. - * @return The credential. - * @throws GSSException If this operation fails. - */ - public abstract GSSCredential createCredential(int usage) throws GSSException; - - /** - * Factory method for acquiring a single mechanism credential. - * - * @param aName Name of the principal for whom this credential is to - * be acquired. Use <code>null</code> to specify the - * default principal. - * @param lifetime The number of seconds that credentials should remain - * valid. Use {@link GSSCredential#INDEFINITE_LIFETIME} - * to request that the credentials have the maximum - * permitted lifetime. Use {@link - * GSSCredential#DEFAULT_LIFETIME} to request default - * credential lifetime. - * @param mech The oid of the desired mechanism. Use <code>null</code> - * to request the default mechanism(s). - * @param usage The intended usage for this credential object. The - * value of this parameter must be one of: - * {@link GSSCredential#ACCEPT_AND_INITIATE}, - * {@link GSSCredential#ACCEPT_ONLY}, - * {@link GSSCredential#INITIATE_ONLY}. - * @return The credential. - * @throws GSSException If this operation fails. - */ - public abstract GSSCredential createCredential(GSSName aName, int lifetime, - Oid mech, int usage) - throws GSSException; - - /** - * Factory method for acquiring credentials over a set of mechanisms. - * Acquires credentials for each of the mechanisms specified in the - * array called mechs. To determine the list of mechanisms' for which - * the acquisition of credentials succeeded, the caller should use the - * {@link GSSCredential#getMechs()} method. - * - * @param aName Name of the principal for whom this credential is to - * be acquired. Use <code>null</code> to specify the - * default principal. - * @param lifetime The number of seconds that credentials should remain - * valid. Use {@link GSSCredential#INDEFINITE_LIFETIME} - * to request that the credentials have the maximum - * permitted lifetime. Use {@link - * GSSCredential#DEFAULT_LIFETIME} to request default - * credential lifetime. - * @param mechs The array of mechanisms over which the credential is - * to be acquired. Use <code>null</code> for requesting - * a system specific default set of mechanisms. - * @param usage The intended usage for this credential object. The - * value of this parameter must be one of: - * {@link GSSCredential#ACCEPT_AND_INITIATE}, - * {@link GSSCredential#ACCEPT_ONLY}, - * {@link GSSCredential#INITIATE_ONLY}. - * @return The credential. - * @throws GSSException If this operation fails. - */ - public abstract GSSCredential createCredential(GSSName aName, int lifetime, - Oid[] mechs, int usage) - throws GSSException; - - /** - * Factory method to convert a contiguous byte array containing a name - * from the specified namespace to a {@link GSSName} object. In general, - * the {@link GSSName} object created will not be an MN; two examples that - * are exceptions to this are when the namespace type parameter indicates - * {@link GSSName#NT_EXPORT_NAME} or when the GSS-API implementation is not - * multi-mechanism. - * - * @param name The byte array containing the name to create. - * @param nameType The Oid specifying the namespace of the name supplied - * in the byte array. Note that nameType serves to - * describe and qualify the interpretation of the input - * name byte array, it does not necessarily imply a type - * for the output GSSName implementation. "null" value - * can be used to specify that a mechanism specific - * default syntax should be assumed by each mechanism - * that examines the byte array. - * @return The name. - * @throws GSSException If this operation fails. - */ - public abstract GSSName createName(byte[] name, Oid nameType) - throws GSSException; - - /** - * Factory method to convert a contiguous byte array containing a name - * from the specified namespace to a GSSName object that is an MN. In - * other words, this method is a utility that does the equivalent of two - * steps: {@link #createName(byte[],org.ietf.jgss.Oid)} and then also - * {@link GSSName#canonicalize(org.ietf.jgss.Oid)}. - * - * @param name The byte array representing the name to create. - * @param nameType The Oid specifying the namespace of the name supplied - * in the byte array. Note that nameType serves to - * describe and qualify the interpretation of the input - * name byte array, it does not necessarily imply a type - * for the output GSSName implementation. "null" value - * can be used to specify that a mechanism specific - * default syntax should be assumed by each mechanism - * that examines the byte array. - * @param mech Oid specifying the mechanism for which this name - * should be created. - * @return The name. - * @throws GSSException If this operation fails. - */ - public abstract GSSName createName(byte[] name, Oid nameType, Oid mech) - throws GSSException; - - /** - * Factory method to convert a contiguous string name from the specified - * namespace to a {@link GSSName} object. In general, the {@link GSSName} - * object created will not be an MN; two examples that are exceptions to - * this are when the namespace type parameter indicates {@link - * GSSName#NT_EXPORT_NAME} or when the GSS-API implementation is not - * multi-mechanism. - * - * @param nameStr The string representing a printable form of the name - * to create. - * @param nameType The Oid specifying the namespace of the printable name - * supplied. Note that nameType serves to describe and - * qualify the interpretation of the input nameStr, it - * does not necessarily imply a type for the output - * GSSName implementation. "null" value can be used to - * specify that a mechanism specific default printable - * syntax should be assumed by each mechanism that - * examines nameStr. - * @return The name. - * @throws GSSException If this operation fails. - */ - public abstract GSSName createName(String nameStr, Oid nameType) - throws GSSException; - - /** - * Factory method to convert a contiguous string name from the specified - * namespace to an GSSName object that is a mechanism name (MN). In - * other words, this method is a utility that does the equivalent of two - * steps: the {@link #createName(java.lang.String,org.ietf.jgss.Oid)} - * and then also {@link GSSName#canonicalize(org.ietf.jgss.Oid)}. - * - * @param nameStr The string representing a printable form of the name - * to create. - * @param nameType The Oid specifying the namespace of the printable name - * supplied. Note that nameType serves to describe and - * qualify the interpretation of the input nameStr, it - * does not necessarily imply a type for the output - * GSSName implementation. "null" value can be used to - * specify that a mechanism specific default printable - * syntax should be assumed when the mechanism examines - * nameStr. - * @param mech Oid specifying the mechanism for which this name - * should be created. - * @return The name. - * @throws GSSException If this operation fails. - */ - public abstract GSSName createName(String nameStr, Oid nameType, Oid mech) - throws GSSException; - - /** - * Returns an array of {@link Oid} objects indicating mechanisms available - * to GSS-API callers. A <code>null</code> value is returned when no - * mechanism are available (an example of this would be when mechanism are - * dynamically configured, and currently no mechanisms are installed). - * - * @return The array of available mechanisms, or <code>null</code>. - */ - public abstract Oid[] getMechs(); - - /** - * Returns an array of {@link Oid} objects corresponding to the mechanisms - * that support the specific name type. <code>null</code> is returned when - * no mechanisms are found to support the specified name type. - * - * @param name The Oid object for the name type. - * @return The array of mechanisms, or <code>null</code>. - */ - public abstract Oid[] getMechsForName(Oid name); - - /** - * Returns name type Oid's supported by the specified mechanism. - * - * @param mechanism The Oid object for the mechanism to query. - * @return The name type Oid's supported by the mechanism. - * @throws GSSException If this operation fails. - */ - public abstract Oid[] getNamesForMech(Oid mechanism) throws GSSException; -} |