/*
 * Copyright 2002 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */
 
package javax.security.auth.login;

import javax.security.auth.AuthPermission;
 
import java.io.*;
import java.util.*;
import java.net.URL;

/**
 * <p> This is an abstract class for representing the configuration of
 * LoginModules under an application.  The <code>Configuration</code> specifies
 * which LoginModules should be used for a particular application, and in what
 * order the LoginModules should be invoked.
 * This abstract class needs to be subclassed to provide an implementation
 * which reads and loads the actual <code>Configuration</code>.
 *
 * <p> When the <code>LoginContext</code> needs to read the Configuration
 * to determine which LoginModules are configured for a particular
 * application, <i>appName</i>, it makes the following calls:
 * <pre>
 *	config = Configuration.getConfiguration();
 *	entries = config.getAppConfigurationEntry(appName);
 * </pre>
 *
 * <p> A login configuration contains the following information.
 * Note that this example only represents the default syntax for the
 * <code>Configuration</code>.  Subclass implementations of this class
 * may implement alternative syntaxes and may retrieve the
 * <code>Configuration</code> from any source such as files, databases,
 * or servers.
 *
 * <pre>
 *      Application {
 *	      Module  Flag    ModuleOptions;
 *	      Module  Flag    ModuleOptions;
 *	      Module  Flag    ModuleOptions;
 *      };
 *      Application {
 *	      Module  Flag    ModuleOptions;
 *	      Module  Flag    ModuleOptions;
 *      };
 *      other {
 *	      Module  Flag    ModuleOptions;
 *	      Module  Flag    ModuleOptions;
 *      };
 * </pre>
 *
 * <p> Each entry in the <code>Configuration</code> is indexed via an
 * application name, <i>Application</i>, and contains a list of
 * LoginModules configured for that application.  Authentication proceeds
 * down the list in the exact order specified.  If an application
 * does not have specific entry, it defaults to the specific entry
 * for "<i>other</i>".
 *
 * <p> The <i>Flag</i> value controls the overall behavior as authentication
 * proceeds down the stack.  The following represents a description of the
 * valid values for <i>Flag</i> and their respective semantics:
 *
 * <pre>
 *      1) Required     - The <code>LoginModule</code> is required to succeed.
 *			If it succeeds or fails, authentication still continues
 *			to proceed down the <code>LoginModule</code> list.
 *
 *      2) Requisite    - The <code>LoginModule</code> is required to succeed.
 *			If it succeeds, authentication continues down the
 *			<code>LoginModule</code> list.  If it fails,
 *			control immediately returns to the application
 *			(authentication does not proceed down the
 *			<code>LoginModule</code> list).
 *
 *      3) Sufficient   - The <code>LoginModule</code> is not required to
 *			succeed.  If it does succeed, control immediately
 *			returns to the application (authentication does not
 *			proceed down the <code>LoginModule</code> list).
 *			If it fails, authentication continues down the
 *			<code>LoginModule</code> list.
 *
 *      4) Optional     - The <code>LoginModule</code> is not required to
 *			succeed.  If it succeeds or fails,
 *			authentication still continues to proceed down the
 *			<code>LoginModule</code> list.
 * </pre>
 *
 * <p> The overall authentication succeeds only if all <i>Required</i> and
 * <i>Requisite</i> LoginModules succeed.  If a <i>Sufficient</i>
 * <code>LoginModule</code> is configured and succeeds,
 * then only the <i>Required</i> and <i>Requisite</i> LoginModules prior to 
 * that <i>Sufficient</i> <code>LoginModule</code> need to have succeeded for
 * the overall authentication to succeed. If no <i>Required</i> or
 * <i>Requisite</i> LoginModules are configured for an application,
 * then at least one <i>Sufficient</i> or <i>Optional</i>
 * <code>LoginModule</code> must succeed.
 *
 * <p> <i>ModuleOptions</i> is a space separated list of
 * <code>LoginModule</code>-specific values which are passed directly to
 * the underlying LoginModules.  Options are defined by the
 * <code>LoginModule</code> itself, and control the behavior within it.
 * For example, a <code>LoginModule</code> may define options to support
 * debugging/testing capabilities.  The correct way to specify options in the
 * <code>Configuration</code> is by using the following key-value pairing:
 * <i>debug=true</i>.  The key and value should be separated by an
 * 'equals' symbol.  Note that there is no limit to the number of
 * options a <code>LoginModule</code> may define.
 *
 * <p> The following represents an example <code>Configuration</code> entry
 * based on the syntax above:
 *
 * <pre>
 *      Login {
 *	      sun.modules.SmartCard   required;
 *	      sun.modules.Kerberos    optional	debug=true;
 *      };
 * </pre>
 *
 * <p> This <code>Configuration</code> specifies that an application named,
 * "Login", requires users to first authenticate to the
 * <i>sun.modules.SmartCard</i> <code>LoginModule</code>, which is
 * required to succeed.  Even if the <i>sun.modules.SmartCard</i>
 * authentication fails (an incorrect pin was entered), the
 * <i>sun.modules.Kerberos</i> <code>LoginModule</code> still gets invoked.
 * This helps hide the source of failure.  Since the <i>sun.modules.Kerberos</i>
 * <code>LoginModule</code> is <i>Optional</i>, the overall
 * authentication succeeds only if the <i>sun.modules.SmartCard</i>
 * <code>LoginModule</code> (<i>Required</i>) succeeds.
 *
 * <p> Also note that the LoginModule-specific option, <i>debug=true</i>,
 * is passed to the <i>sun.modules.Kerberos</i> LoginModule.  This turns on
 * a debugging flag, which outputs helpful debugging information to a file.
 *
 * <p> The default Configuration implementation can be changed by setting the
 * value of the "login.configuration.provider" security property (in the Java
 * security properties file) to the fully qualified name of
 * the desired Configuration implementation class.
 * The Java security properties file is located in the file named
 * <JAVA_HOME>/lib/security/java.security, where <JAVA_HOME>
 * refers to the directory where the JDK was installed.
 *
 * @version 1.43, 01/14/00
 * @see javax.security.auth.login.LoginContext
 */
public abstract class Configuration {

    private static final java.util.ResourceBundle rb =
	java.util.ResourceBundle.getBundle("com.sun.security.auth.Resources");

    private static Configuration configuration;
    private static ClassLoader sysClassLoader;

    static {
	sysClassLoader =
		(ClassLoader)java.security.AccessController.doPrivileged
		(new java.security.PrivilegedAction() {
		public Object run() {
		    return ClassLoader.getSystemClassLoader();
		}
	});
    };

    /**
     * Sole constructor.  (For invocation by subclass constructors, typically
     * implicit.)
     */
    protected Configuration() { }

    /**
     * Get the current Login Configuration.
     *
     * <p>
     *
     * @return the current Login Configuration.
     *
     * @exception SecurityException if the caller does not have permission
     *				to retrieve the Configuration.
     */
    public static Configuration getConfiguration() {

	SecurityManager sm = System.getSecurityManager();
	if (sm != null)
	    sm.checkPermission(new AuthPermission("getLoginConfiguration"));

	if (configuration == null) {
 
	    synchronized(Configuration.class) {
 
		if (configuration == null) {
		    String config_class = null;
		    config_class = (String)
			java.security.AccessController.doPrivileged
			(new java.security.PrivilegedAction() {
			public Object run() {
			    return java.security.Security.getProperty
					("login.configuration.provider");
			}
		    });
		    if (config_class == null) {
			config_class = "com.sun.security.auth.login.ConfigFile";
		    }
 
		    try {
			configuration = (Configuration)Class.forName
						(config_class,
						true,
						sysClassLoader).newInstance();
		    } catch (Exception e) {
			throw new SecurityException(rb.getString
				("unable to instantiate Login Configuration"));
		    }
		}
	    }
	}
 
	return configuration;
    }

    /**
     * Set the current Login <code>Configuration</code>
     *
     * <p>
     *
     * @param configuration the new <code>Configuration</code>
     *
     * @exception SecurityException if the current thread does not have
     *			Permission to set the <code>Configuration</code>.
     */
    public static void setConfiguration(Configuration configuration) {
	SecurityManager sm = System.getSecurityManager();
	if (sm != null)
	    sm.checkPermission(new AuthPermission("setLoginConfiguration"));
	Configuration.configuration = configuration;
    }

    /**
     * Retrieve an array of AppConfigurationEntries which corresponds to
     *		the configuration of LoginModules for this application.
     *
     * <p>
     *
     * @param applicationName the name used to index the Configuration.
     * 
     * @return an array of AppConfigurationEntries which corresponds to
     *		the configuration of LoginModules for this
     *		application, or null if this application has no configured
     *		LoginModules.
     */
    public abstract AppConfigurationEntry[] getAppConfigurationEntry
    (String applicationName);

    /**
     * Refresh and reload the Configuration.
     *
     * <p> This method causes this object to refresh/reload its current
     * Configuration. This is implementation-dependent.
     * For example, if the Configuration object is stored
     * a file, calling <code>refresh</code> will cause the file to be re-read.
     *
     * <p>
     *
     * @exception SecurityException if the caller does not have permission
     *				to refresh the Configuration.
     */
    public abstract void refresh();
}