Configuration


1   /*
2    * @(#)Configuration.java   1.57 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7    
8   package javax.security.auth.login;
9   
10  import javax.security.auth.AuthPermission  ;
11   
12  import java.io.*;
13  import java.util.*;
14  import java.net.URL  ;
15  import java.security.PrivilegedActionException  ;
16   
17  /**
18   * <p> This is an abstract class for representing the configuration of
19   * LoginModules under an application.  The <code>Configuration</code> specifies
20   * which LoginModules should be used for a particular application, and in what
21   * order the LoginModules should be invoked.
22   * This abstract class needs to be subclassed to provide an implementation
23   * which reads and loads the actual <code>Configuration</code>.
24   *
25   * <p> A login configuration contains the following information.
26   * Note that this example only represents the default syntax for the
27   * <code>Configuration</code>.  Subclass implementations of this class
28   * may implement alternative syntaxes and may retrieve the
29   * <code>Configuration</code> from any source such as files, databases,
30   * or servers.
31   *
32   * <pre>
33   *      Name {
34   *        ModuleClass  Flag    ModuleOptions;
35   *        ModuleClass  Flag    ModuleOptions;
36   *        ModuleClass  Flag    ModuleOptions;
37   *      };
38   *      Name {
39   *        ModuleClass  Flag    ModuleOptions;
40   *        ModuleClass  Flag    ModuleOptions;
41   *      };
42   *      other {
43   *        ModuleClass  Flag    ModuleOptions;
44   *        ModuleClass  Flag    ModuleOptions;
45   *      };
46   * </pre>
47   *
48   * <p> Each entry in the <code>Configuration</code> is indexed via an
49   * application name, <i>Name</i>, and contains a list of
50   * LoginModules configured for that application.  Each <code>LoginModule</code>
51   * is specified via its fully qualified class name.
52   * Authentication proceeds down the module list in the exact order specified.
53   * If an application does not have specific entry,
54   * it defaults to the specific entry for "<i>other</i>".
55   *
56   * <p> The <i>Flag</i> value controls the overall behavior as authentication
57   * proceeds down the stack.  The following represents a description of the
58   * valid values for <i>Flag</i> and their respective semantics:
59   *
60   * <pre>
61   *      1) Required     - The <code>LoginModule</code> is required to succeed.
62   *          If it succeeds or fails, authentication still continues
63   *          to proceed down the <code>LoginModule</code> list.
64   *
65   *      2) Requisite    - The <code>LoginModule</code> is required to succeed.
66   *          If it succeeds, authentication continues down the
67   *          <code>LoginModule</code> list.  If it fails,
68   *          control immediately returns to the application
69   *          (authentication does not proceed down the
70   *          <code>LoginModule</code> list).
71   *
72   *      3) Sufficient   - The <code>LoginModule</code> is not required to
73   *          succeed.  If it does succeed, control immediately
74   *          returns to the application (authentication does not
75   *          proceed down the <code>LoginModule</code> list).
76   *          If it fails, authentication continues down the
77   *          <code>LoginModule</code> list.
78   *
79   *      4) Optional     - The <code>LoginModule</code> is not required to
80   *          succeed.  If it succeeds or fails,
81   *          authentication still continues to proceed down the
82   *          <code>LoginModule</code> list.
83   * </pre>
84   *
85   * <p> The overall authentication succeeds only if all <i>Required</i> and
86   * <i>Requisite</i> LoginModules succeed.  If a <i>Sufficient</i>
87   * <code>LoginModule</code> is configured and succeeds,
88   * then only the <i>Required</i> and <i>Requisite</i> LoginModules prior to 
89   * that <i>Sufficient</i> <code>LoginModule</code> need to have succeeded for
90   * the overall authentication to succeed. If no <i>Required</i> or
91   * <i>Requisite</i> LoginModules are configured for an application,
92   * then at least one <i>Sufficient</i> or <i>Optional</i>
93   * <code>LoginModule</code> must succeed.
94   *
95   * <p> <i>ModuleOptions</i> is a space separated list of
96   * <code>LoginModule</code>-specific values which are passed directly to
97   * the underlying LoginModules.  Options are defined by the
98   * <code>LoginModule</code> itself, and control the behavior within it.
99   * For example, a <code>LoginModule</code> may define options to support
100  * debugging/testing capabilities.  The correct way to specify options in the
101  * <code>Configuration</code> is by using the following key-value pairing:
102  * <i>debug="true"</i>.  The key and value should be separated by an
103  * 'equals' symbol, and the value should be surrounded by double quotes.
104  * If a String in the form, ${system.property}, occurs in the value,
105  * it will be expanded to the value of the system property.
106  * Note that there is no limit to the number of
107  * options a <code>LoginModule</code> may define.
108  *
109  * <p> The following represents an example <code>Configuration</code> entry
110  * based on the syntax above:
111  *
112  * <pre>
113  * Login {
114  *   com.sun.security.auth.module.UnixLoginModule required;
115  *   com.sun.security.auth.module.Krb5LoginModule optional
116  *                   useTicketCache="true"
117  *                   ticketCache="${user.home}${/}tickets";
118  * };
119  * </pre>
120  *
121  * <p> This <code>Configuration</code> specifies that an application named,
122  * "Login", requires users to first authenticate to the
123  * <i>com.sun.security.auth.module.UnixLoginModule</i>, which is
124  * required to succeed.  Even if the <i>UnixLoginModule</i>
125  * authentication fails, the
126  * <i>com.sun.security.auth.module.Krb5LoginModule</i>
127  * still gets invoked.  This helps hide the source of failure.
128  * Since the <i>Krb5LoginModule</i> is <i>Optional</i>, the overall
129  * authentication succeeds only if the <i>UnixLoginModule</i>
130  * (<i>Required</i>) succeeds.
131  *
132  * <p> Also note that the LoginModule-specific options,
133  * <i>useTicketCache="true"</i> and
134  * <i>ticketCache=${user.home}${/}tickets"</i>,
135  * are passed to the <i>Krb5LoginModule</i>.
136  * These options instruct the <i>Krb5LoginModule</i> to
137  * use the ticket cache at the specified location.
138  * The system properties, <i>user.home</i> and <i>/</i>
139  * (file.separator), are expanded to their respective values.
140  *
141  * <p> The default Configuration implementation can be changed by setting the
142  * value of the "login.configuration.provider" security property (in the Java
143  * security properties file) to the fully qualified name of
144  * the desired Configuration implementation class.
145  * The Java security properties file is located in the file named
146  * &lt;JAVA_HOME&gt;/lib/security/java.security, where &lt;JAVA_HOME&gt;
147  * refers to the directory where the JDK was installed.
148  *
149  * @version 1.57, 12/19/03
150  * @see javax.security.auth.login.LoginContext
151  */
152 public abstract class Configuration {
153 
154     private static Configuration   configuration;
155     private static ClassLoader   contextClassLoader;
156 
157     static {
158     contextClassLoader =
159         (ClassLoader  )java.security.AccessController.doPrivileged
160         (new java.security.PrivilegedAction  () {
161         public Object   run() {
162             return Thread.currentThread().getContextClassLoader();  
163         }
164     });
165     };
166 
167     /**
168      * Sole constructor.  (For invocation by subclass constructors, typically
169      * implicit.)
170      */
171     protected Configuration() { }
172 
173     /**
174      * Get the Login Configuration.
175      *
176      * <p>
177      *
178      * @return the login Configuration.  If a Configuration object was set
179      *      via the <code>Configuration.setConfiguration</code> method,
180      *      then that object is returned.  Otherwise, a default
181      *      Configuration object is returned.
182      *
183      * @exception SecurityException if the caller does not have permission
184      *              to retrieve the Configuration.
185      *
186      * @see #setConfiguration
187      */
188     public static synchronized Configuration   getConfiguration() {
189 
190     SecurityManager   sm = System.getSecurityManager();
191     if (sm != null)
192         sm.checkPermission(new AuthPermission  ("getLoginConfiguration"));
193 
194     if (configuration == null) {
195         String   config_class = null;
196         config_class = (String  )
197         java.security.AccessController.doPrivileged
198         (new java.security.PrivilegedAction  () {
199         public Object   run() {
200             return java.security.Security.getProperty
201                 ("login.configuration.provider");
202         }
203         });
204         if (config_class == null) {
205         config_class = "com.sun.security.auth.login.ConfigFile";
206         }
207  
208         try {
209         final String   finalClass = config_class;
210         configuration = (Configuration  )
211             java.security.AccessController.doPrivileged
212             (new java.security.PrivilegedExceptionAction  () {
213             public Object   run() throws ClassNotFoundException  ,
214                     InstantiationException  ,
215                     IllegalAccessException   {
216             return Class.forName
217                 (finalClass,
218                 true,
219                 contextClassLoader).newInstance();
220             }
221         });
222         } catch (PrivilegedActionException   e) {
223         Exception   ee = e.getException();
224         if (ee instanceof InstantiationException  ) {
225             throw (SecurityException  ) new
226             SecurityException  
227                 ("Configuration error:" +
228                  ee.getCause().getMessage() + 
229                  "\n").initCause(ee.getCause());
230         } else {
231             throw (SecurityException  ) new
232             SecurityException  
233                 ("Configuration error: " +
234                  ee.toString() + 
235                  "\n").initCause(ee);
236         }
237         }
238     }
239     return configuration;
240     }
241     
242     /**
243      * Set the Login <code>Configuration</code>.
244      *
245      * <p>
246      *
247      * @param configuration the new <code>Configuration</code>
248      *
249      * @exception SecurityException if the current thread does not have
250      *          Permission to set the <code>Configuration</code>.
251      *
252      * @see #getConfiguration
253      */
254     public static void setConfiguration(Configuration   configuration) {
255     SecurityManager   sm = System.getSecurityManager();
256     if (sm != null)
257         sm.checkPermission(new AuthPermission  ("setLoginConfiguration"));
258     Configuration.configuration = configuration;
259     }
260 
261     /**
262      * Retrieve the AppConfigurationEntries for the specified <i>name</i>
263      * from this Configuration.
264      *
265      * <p>
266      *
267      * @param name the name used to index the Configuration.
268      * 
269      * @return an array of AppConfigurationEntries for the specified <i>name</i>
270      *      from this Configuration, or null if there are no entries
271      *      for the specified <i>name</i>
272      */
273     public abstract AppConfigurationEntry  [] getAppConfigurationEntry
274                             (String   name);
275 
276     /**
277      * Refresh and reload the Configuration.
278      *
279      * <p> This method causes this Configuration object to refresh/reload its
280      * contents in an implementation-dependent manner.
281      * For example, if this Configuration object stores its entries in a file,
282      * calling <code>refresh</code> may cause the file to be re-read.
283      *
284      * <p>
285      *
286      * @exception SecurityException if the caller does not have permission
287      *              to refresh its Configuration.
288      */
289     public abstract void refresh();
290 }
291
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags