Policy


1   /*
2    * @(#)Policy.java  1.50 04/05/18
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;
9   
10  /**
11   * <p> This is an abstract class for representing the system policy for
12   * Subject-based authorization.  A subclass implementation
13   * of this class provides a means to specify a Subject-based
14   * access control <code>Policy</code>.
15   *
16   * <p> A <code>Policy</code> object can be queried for the set of
17   * Permissions granted to code running as a 
18   * <code>Principal</code> in the following manner:
19   *
20   * <pre>
21   *  policy = Policy.getPolicy();
22   *  PermissionCollection perms = policy.getPermissions(subject,
23   *                          codeSource);
24   * </pre>
25   *
26   * The <code>Policy</code> object consults the local policy and returns
27   * and appropriate <code>Permissions</code> object with the
28   * Permissions granted to the Principals associated with the
29   * provided <i>subject</i>, and granted to the code specified
30   * by the provided <i>codeSource</i>.
31   *
32   * <p> A <code>Policy</code> contains the following information.
33   * Note that this example only represents the syntax for the default
34   * <code>Policy</code> implementation. Subclass implementations of this class
35   * may implement alternative syntaxes and may retrieve the
36   * <code>Policy</code> from any source such as files, databases,
37   * or servers.
38   *
39   * <p> Each entry in the <code>Policy</code> is represented as
40   * a <b><i>grant</i></b> entry.  Each <b><i>grant</i></b> entry
41   * specifies a codebase, code signers, and Principals triplet,
42   * as well as the Permissions granted to that triplet.
43   *
44   * <pre>
45   *  grant CodeBase ["URL"], Signedby ["signers"],
46   *        Principal [Principal_Class] "Principal_Name" {
47   *      Permission Permission_Class ["Target_Name"]
48   *                  [, "Permission_Actions"]
49   *                  [, signedBy "SignerName"];
50   *  };
51   * </pre>
52   *
53   * The CodeBase and Signedby components of the triplet name/value pairs
54   * are optional.  If they are not present, then any any codebase will match,
55   * and any signer (including unsigned code) will match.
56   * For Example,
57   *
58   * <pre>
59   *  grant CodeBase "foo.com", Signedby "foo",
60   *        Principal com.sun.security.auth.SolarisPrincipal "duke" {
61   *      permission java.io.FilePermission "/home/duke", "read, write";
62   *  };
63   * </pre>
64   *
65   * This <b><i>grant</i></b> entry specifies that code from "foo.com",
66   * signed by "foo', and running as a <code>SolarisPrincipal</code> with the
67   * name, duke, has one <code>Permission</code>.  This <code>Permission</code>
68   * permits the executing code to read and write files in the directory,
69   * "/home/duke".
70   *
71   * <p> To "run" as a particular <code>Principal</code>,
72   * code invokes the <code>Subject.doAs(subject, ...)</code> method.
73   * After invoking that method, the code runs as all the Principals
74   * associated with the specified <code>Subject</code>.
75   * Note that this <code>Policy</code> (and the Permissions
76   * granted in this <code>Policy</code>) only become effective
77   * after the call to <code>Subject.doAs</code> has occurred.
78   *
79   * <p> Multiple Principals may be listed within one <b><i>grant</i></b> entry.
80   * All the Principals in the grant entry must be associated with
81   * the <code>Subject</code> provided to <code>Subject.doAs</code>
82   * for that <code>Subject</code> to be granted the specified Permissions.
83   *
84   * <pre>
85   *  grant Principal com.sun.security.auth.SolarisPrincipal "duke",
86   *        Principal com.sun.security.auth.SolarisNumericUserPrincipal "0" {
87   *      permission java.io.FilePermission "/home/duke", "read, write";
88   *      permission java.net.SocketPermission "duke.com", "connect";
89   *  };
90   * </pre>
91   *
92   * This entry grants any code running as both "duke" and "0"
93   * permission to read and write files in duke's home directory,
94   * as well as permission to make socket connections to "duke.com".
95   * 
96   * <p> Note that non Principal-based grant entries are not permitted
97   * in this <code>Policy</code>.  Therefore, grant entries such as:
98   *
99   * <pre>
100  *  grant CodeBase "foo.com", Signedby "foo" {
101  *      permission java.io.FilePermission "/tmp/scratch", "read, write";
102  *  };
103  * </pre>
104  *
105  * are rejected.  Such permission must be listed in the
106  * <code>java.security.Policy</code>.
107  *
108  * <p> The default <code>Policy</code> implementation can be changed by
109  * setting the value of the "auth.policy.provider" security property
110  * (in the Java security properties file) to the fully qualified name of
111  * the desired <code>Policy</code> implementation class.
112  * The Java security properties file is located in the file named
113  * &lt;JAVA_HOME&gt;/lib/security/java.security, where &lt;JAVA_HOME&gt;
114  * refers to the directory where the JDK was installed.
115  *
116  * @deprecated  as of JDK version 1.4 -- Replaced by java.security.Policy.
117  *      java.security.Policy has a method:
118  * <pre>
119  *  public PermissionCollection getPermissions
120  *          (java.security.ProtectionDomain pd)
121  * 
122  * </pre>
123  * and ProtectionDomain has a constructor:
124  * <pre>
125  *  public ProtectionDomain
126  *      (CodeSource cs,
127  *       PermissionCollection permissions,
128  *       ClassLoader loader,
129  *       Principal[] principals)
130  * </pre>
131  *
132  * These two APIs provide callers the means to query the
133  * Policy for Principal-based Permission entries.
134  *
135  *
136  * @version 1.50, 05/18/04
137  */
138 @Deprecated  
139 public abstract class Policy {
140 
141     private static Policy   policy;
142     private static ClassLoader   contextClassLoader;
143 
144     static {
145     contextClassLoader =
146         (ClassLoader  )java.security.AccessController.doPrivileged
147                 (new java.security.PrivilegedAction  () {
148                 public Object   run() {
149                     return Thread.currentThread().getContextClassLoader();
150                 }
151         });
152     };
153 
154     /**
155      * Sole constructor.  (For invocation by subclass constructors, typically
156      * implicit.)
157      */
158     protected Policy() { }
159 
160     /**
161      * Returns the installed Policy object.
162      * This method first calls
163      * <code>SecurityManager.checkPermission</code> with the
164      * <code>AuthPermission("getPolicy")</code> permission
165      * to ensure the caller has permission to get the Policy object.
166      *
167      * <p>
168      *
169      * @return the installed Policy.  The return value cannot be
170      *      <code>null</code>.
171      *
172      * @exception java.lang.SecurityException if the current thread does not
173      *      have permission to get the Policy object.
174      *
175      * @see #setPolicy
176      */
177     public static Policy   getPolicy() {
178     java.lang.SecurityManager   sm = System.getSecurityManager();
179     if (sm != null) sm.checkPermission(new AuthPermission  ("getPolicy"));
180     return getPolicyNoCheck();
181     }
182 
183     /**
184      * Returns the installed Policy object, skipping the security check.
185      *
186      * @return the installed Policy.
187      *
188      */
189     static Policy   getPolicyNoCheck() {
190     if (policy == null) {
191  
192         synchronized(Policy  .class) {
193  
194         if (policy == null) {
195             String   policy_class = null;
196             policy_class = (String  )
197             java.security.AccessController.doPrivileged
198             (new java.security.PrivilegedAction  () {
199             public Object   run() {
200                 return java.security.Security.getProperty
201                 ("auth.policy.provider");
202             }
203             });
204             if (policy_class == null) {
205             policy_class = "com.sun.security.auth.PolicyFile";
206             }
207  
208             try {
209             final String   finalClass = policy_class;
210             policy = (Policy  )
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 (Exception   e) {
223             throw new SecurityException  
224                 (sun.security.util.ResourcesMgr.getString
225                 ("unable to instantiate Subject-based policy"));
226             }
227         }
228         }
229     }
230     return policy;
231     }
232 
233 
234     /**
235      * Sets the system-wide Policy object. This method first calls
236      * <code>SecurityManager.checkPermission</code> with the
237      * <code>AuthPermission("setPolicy")</code>
238      * permission to ensure the caller has permission to set the Policy.
239      *
240      * <p>
241      *
242      * @param policy the new system Policy object.
243      *
244      * @exception java.lang.SecurityException if the current thread does not
245      *      have permission to set the Policy.
246      *
247      * @see #getPolicy
248      */
249     public static void setPolicy(Policy   policy) {
250     java.lang.SecurityManager   sm = System.getSecurityManager();
251     if (sm != null) sm.checkPermission(new AuthPermission  ("setPolicy"));
252     Policy.policy = policy;
253     }
254 
255     /**
256      * Retrieve the Permissions granted to the Principals associated with
257      * the specified <code>CodeSource</code>.
258      *
259      * <p>
260      *
261      * @param subject the <code>Subject</code>
262      *          whose associated Principals,
263      *          in conjunction with the provided
264      *          <code>CodeSource</code>, determines the Permissions
265      *          returned by this method.  This parameter
266      *          may be <code>null</code>. <p>
267      *
268      * @param cs the code specified by its <code>CodeSource</code>
269      *          that determines, in conjunction with the provided
270      *          <code>Subject</code>, the Permissions
271      *          returned by this method.  This parameter may be
272      *          <code>null</code>.
273      *
274      * @return the Collection of Permissions granted to all the
275      *          <code>Subject</code> and code specified in
276      *          the provided <i>subject</i> and <i>cs</i>
277      *          parameters.
278      */
279     public abstract java.security.PermissionCollection   getPermissions
280                     (Subject   subject,
281                     java.security.CodeSource   cs);
282 
283     /**
284      * Refresh and reload the Policy.
285      *
286      * <p>This method causes this object to refresh/reload its current
287      * Policy. This is implementation-dependent.
288      * For example, if the Policy object is stored in
289      * a file, calling <code>refresh</code> will cause the file to be re-read.
290      *
291      * <p>
292      *
293      * @exception SecurityException if the caller does not have permission
294      *              to refresh the Policy.
295      */
296     public abstract void refresh();
297 }
298
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags