1 /*
2 * Copyright 1998-2006 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package javax.security.auth;
27
28 /**
29 * <p> This is an abstract class for representing the system policy for
30 * Subject-based authorization. A subclass implementation
31 * of this class provides a means to specify a Subject-based
32 * access control <code>Policy</code>.
33 *
34 * <p> A <code>Policy</code> object can be queried for the set of
35 * Permissions granted to code running as a
36 * <code>Principal</code> in the following manner:
37 *
38 * <pre>
39 * policy = Policy.getPolicy();
40 * PermissionCollection perms = policy.getPermissions(subject,
41 * codeSource);
42 * </pre>
43 *
44 * The <code>Policy</code> object consults the local policy and returns
45 * and appropriate <code>Permissions</code> object with the
46 * Permissions granted to the Principals associated with the
47 * provided <i>subject</i>, and granted to the code specified
48 * by the provided <i>codeSource</i>.
49 *
50 * <p> A <code>Policy</code> contains the following information.
51 * Note that this example only represents the syntax for the default
52 * <code>Policy</code> implementation. Subclass implementations of this class
53 * may implement alternative syntaxes and may retrieve the
54 * <code>Policy</code> from any source such as files, databases,
55 * or servers.
56 *
57 * <p> Each entry in the <code>Policy</code> is represented as
58 * a <b><i>grant</i></b> entry. Each <b><i>grant</i></b> entry
59 * specifies a codebase, code signers, and Principals triplet,
60 * as well as the Permissions granted to that triplet.
61 *
62 * <pre>
63 * grant CodeBase ["URL"], Signedby ["signers"],
64 * Principal [Principal_Class] "Principal_Name" {
65 * Permission Permission_Class ["Target_Name"]
66 * [, "Permission_Actions"]
67 * [, signedBy "SignerName"];
68 * };
69 * </pre>
70 *
71 * The CodeBase and Signedby components of the triplet name/value pairs
72 * are optional. If they are not present, then any any codebase will match,
73 * and any signer (including unsigned code) will match.
74 * For Example,
75 *
76 * <pre>
77 * grant CodeBase "foo.com", Signedby "foo",
78 * Principal com.sun.security.auth.SolarisPrincipal "duke" {
79 * permission java.io.FilePermission "/home/duke", "read, write";
80 * };
81 * </pre>
82 *
83 * This <b><i>grant</i></b> entry specifies that code from "foo.com",
84 * signed by "foo', and running as a <code>SolarisPrincipal</code> with the
85 * name, duke, has one <code>Permission</code>. This <code>Permission</code>
86 * permits the executing code to read and write files in the directory,
87 * "/home/duke".
88 *
89 * <p> To "run" as a particular <code>Principal</code>,
90 * code invokes the <code>Subject.doAs(subject, ...)</code> method.
91 * After invoking that method, the code runs as all the Principals
92 * associated with the specified <code>Subject</code>.
93 * Note that this <code>Policy</code> (and the Permissions
94 * granted in this <code>Policy</code>) only become effective
95 * after the call to <code>Subject.doAs</code> has occurred.
96 *
97 * <p> Multiple Principals may be listed within one <b><i>grant</i></b> entry.
98 * All the Principals in the grant entry must be associated with
99 * the <code>Subject</code> provided to <code>Subject.doAs</code>
100 * for that <code>Subject</code> to be granted the specified Permissions.
101 *
102 * <pre>
103 * grant Principal com.sun.security.auth.SolarisPrincipal "duke",
104 * Principal com.sun.security.auth.SolarisNumericUserPrincipal "0" {
105 * permission java.io.FilePermission "/home/duke", "read, write";
106 * permission java.net.SocketPermission "duke.com", "connect";
107 * };
108 * </pre>
109 *
110 * This entry grants any code running as both "duke" and "0"
111 * permission to read and write files in duke's home directory,
112 * as well as permission to make socket connections to "duke.com".
113 *
114 * <p> Note that non Principal-based grant entries are not permitted
115 * in this <code>Policy</code>. Therefore, grant entries such as:
116 *
117 * <pre>
118 * grant CodeBase "foo.com", Signedby "foo" {
119 * permission java.io.FilePermission "/tmp/scratch", "read, write";
120 * };
121 * </pre>
122 *
123 * are rejected. Such permission must be listed in the
124 * <code>java.security.Policy</code>.
125 *
126 * <p> The default <code>Policy</code> implementation can be changed by
127 * setting the value of the "auth.policy.provider" security property
128 * (in the Java security properties file) to the fully qualified name of
129 * the desired <code>Policy</code> implementation class.
130 * The Java security properties file is located in the file named
131 * <JAVA_HOME>/lib/security/java.security.
132 * <JAVA_HOME> refers to the value of the java.home system property,
133 * and specifies the directory where the JRE is installed.
134 *
135 * @deprecated as of JDK version 1.4 -- Replaced by java.security.Policy.
136 * java.security.Policy has a method:
137 * <pre>
138 * public PermissionCollection getPermissions
139 * (java.security.ProtectionDomain pd)
140 *
141 * </pre>
142 * and ProtectionDomain has a constructor:
143 * <pre>
144 * public ProtectionDomain
145 * (CodeSource cs,
146 * PermissionCollection permissions,
147 * ClassLoader loader,
148 * Principal[] principals)
149 * </pre>
150 *
151 * These two APIs provide callers the means to query the
152 * Policy for Principal-based Permission entries.
153 *
154 *
155 */
156 @Deprecated
157 public abstract class Policy {
158
159 private static Policy policy;
160 private static ClassLoader contextClassLoader;
161
162 static {
163 contextClassLoader = java.security.AccessController.doPrivileged
164 (new java.security.PrivilegedAction<ClassLoader>() {
165 public ClassLoader run() {
166 return Thread.currentThread().getContextClassLoader();
167 }
168 });
169 };
170
171 /**
172 * Sole constructor. (For invocation by subclass constructors, typically
173 * implicit.)
174 */
175 protected Policy() { }
176
177 /**
178 * Returns the installed Policy object.
179 * This method first calls
180 * <code>SecurityManager.checkPermission</code> with the
181 * <code>AuthPermission("getPolicy")</code> permission
182 * to ensure the caller has permission to get the Policy object.
183 *
184 * <p>
185 *
186 * @return the installed Policy. The return value cannot be
187 * <code>null</code>.
188 *
189 * @exception java.lang.SecurityException if the current thread does not
190 * have permission to get the Policy object.
191 *
192 * @see #setPolicy
193 */
194 public static Policy getPolicy() {
195 java.lang.SecurityManager sm = System.getSecurityManager();
196 if (sm != null) sm.checkPermission(new AuthPermission("getPolicy"));
197 return getPolicyNoCheck();
198 }
199
200 /**
201 * Returns the installed Policy object, skipping the security check.
202 *
203 * @return the installed Policy.
204 *
205 */
206 static Policy getPolicyNoCheck() {
207 if (policy == null) {
208
209 synchronized(Policy.class) {
210
211 if (policy == null) {
212 String policy_class = null;
213 policy_class = java.security.AccessController.doPrivileged
214 (new java.security.PrivilegedAction<String>() {
215 public String run() {
216 return java.security.Security.getProperty
217 ("auth.policy.provider");
218 }
219 });
220 if (policy_class == null) {
221 policy_class = "com.sun.security.auth.PolicyFile";
222 }
223
224 try {
225 final String finalClass = policy_class;
226 policy = java.security.AccessController.doPrivileged
227 (new java.security.PrivilegedExceptionAction<Policy>() {
228 public Policy run() throws ClassNotFoundException,
229 InstantiationException,
230 IllegalAccessException {
231 return (Policy) Class.forName
232 (finalClass,
233 true,
234 contextClassLoader).newInstance();
235 }
236 });
237 } catch (Exception e) {
238 throw new SecurityException
239 (sun.security.util.ResourcesMgr.getString
240 ("unable to instantiate Subject-based policy"));
241 }
242 }
243 }
244 }
245 return policy;
246 }
247
248
249 /**
250 * Sets the system-wide Policy object. This method first calls
251 * <code>SecurityManager.checkPermission</code> with the
252 * <code>AuthPermission("setPolicy")</code>
253 * permission to ensure the caller has permission to set the Policy.
254 *
255 * <p>
256 *
257 * @param policy the new system Policy object.
258 *
259 * @exception java.lang.SecurityException if the current thread does not
260 * have permission to set the Policy.
261 *
262 * @see #getPolicy
263 */
264 public static void setPolicy(Policy policy) {
265 java.lang.SecurityManager sm = System.getSecurityManager();
266 if (sm != null) sm.checkPermission(new AuthPermission("setPolicy"));
267 Policy.policy = policy;
268 }
269
270 /**
271 * Retrieve the Permissions granted to the Principals associated with
272 * the specified <code>CodeSource</code>.
273 *
274 * <p>
275 *
276 * @param subject the <code>Subject</code>
277 * whose associated Principals,
278 * in conjunction with the provided
279 * <code>CodeSource</code>, determines the Permissions
280 * returned by this method. This parameter
281 * may be <code>null</code>. <p>
282 *
283 * @param cs the code specified by its <code>CodeSource</code>
284 * that determines, in conjunction with the provided
285 * <code>Subject</code>, the Permissions
286 * returned by this method. This parameter may be
287 * <code>null</code>.
288 *
289 * @return the Collection of Permissions granted to all the
290 * <code>Subject</code> and code specified in
291 * the provided <i>subject</i> and <i>cs</i>
292 * parameters.
293 */
294 public abstract java.security.PermissionCollection getPermissions
295 (Subject subject,
296 java.security.CodeSource cs);
297
298 /**
299 * Refresh and reload the Policy.
300 *
301 * <p>This method causes this object to refresh/reload its current
302 * Policy. This is implementation-dependent.
303 * For example, if the Policy object is stored in
304 * a file, calling <code>refresh</code> will cause the file to be re-read.
305 *
306 * <p>
307 *
308 * @exception SecurityException if the caller does not have permission
309 * to refresh the Policy.
310 */
311 public abstract void refresh();
312 }
Save This Page