001 /*
002 * Copyright 1998-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.security.auth;
027
028 /**
029 * <p> This is an abstract class for representing the system policy for
030 * Subject-based authorization. A subclass implementation
031 * of this class provides a means to specify a Subject-based
032 * access control <code>Policy</code>.
033 *
034 * <p> A <code>Policy</code> object can be queried for the set of
035 * Permissions granted to code running as a
036 * <code>Principal</code> in the following manner:
037 *
038 * <pre>
039 * policy = Policy.getPolicy();
040 * PermissionCollection perms = policy.getPermissions(subject,
041 * codeSource);
042 * </pre>
043 *
044 * The <code>Policy</code> object consults the local policy and returns
045 * and appropriate <code>Permissions</code> object with the
046 * Permissions granted to the Principals associated with the
047 * provided <i>subject</i>, and granted to the code specified
048 * by the provided <i>codeSource</i>.
049 *
050 * <p> A <code>Policy</code> contains the following information.
051 * Note that this example only represents the syntax for the default
052 * <code>Policy</code> implementation. Subclass implementations of this class
053 * may implement alternative syntaxes and may retrieve the
054 * <code>Policy</code> from any source such as files, databases,
055 * or servers.
056 *
057 * <p> Each entry in the <code>Policy</code> is represented as
058 * a <b><i>grant</i></b> entry. Each <b><i>grant</i></b> entry
059 * specifies a codebase, code signers, and Principals triplet,
060 * as well as the Permissions granted to that triplet.
061 *
062 * <pre>
063 * grant CodeBase ["URL"], Signedby ["signers"],
064 * Principal [Principal_Class] "Principal_Name" {
065 * Permission Permission_Class ["Target_Name"]
066 * [, "Permission_Actions"]
067 * [, signedBy "SignerName"];
068 * };
069 * </pre>
070 *
071 * The CodeBase and Signedby components of the triplet name/value pairs
072 * are optional. If they are not present, then any any codebase will match,
073 * and any signer (including unsigned code) will match.
074 * For Example,
075 *
076 * <pre>
077 * grant CodeBase "foo.com", Signedby "foo",
078 * Principal com.sun.security.auth.SolarisPrincipal "duke" {
079 * permission java.io.FilePermission "/home/duke", "read, write";
080 * };
081 * </pre>
082 *
083 * This <b><i>grant</i></b> entry specifies that code from "foo.com",
084 * signed by "foo', and running as a <code>SolarisPrincipal</code> with the
085 * name, duke, has one <code>Permission</code>. This <code>Permission</code>
086 * permits the executing code to read and write files in the directory,
087 * "/home/duke".
088 *
089 * <p> To "run" as a particular <code>Principal</code>,
090 * code invokes the <code>Subject.doAs(subject, ...)</code> method.
091 * After invoking that method, the code runs as all the Principals
092 * associated with the specified <code>Subject</code>.
093 * Note that this <code>Policy</code> (and the Permissions
094 * granted in this <code>Policy</code>) only become effective
095 * after the call to <code>Subject.doAs</code> has occurred.
096 *
097 * <p> Multiple Principals may be listed within one <b><i>grant</i></b> entry.
098 * All the Principals in the grant entry must be associated with
099 * 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 * @version 1.59, 05/05/07
156 */
157 @Deprecated
158 public abstract class Policy {
159
160 private static Policy policy;
161 private static ClassLoader contextClassLoader;
162
163 static {
164 contextClassLoader = java.security.AccessController
165 .doPrivileged(new java.security.PrivilegedAction<ClassLoader>() {
166 public ClassLoader run() {
167 return Thread.currentThread()
168 .getContextClassLoader();
169 }
170 });
171 };
172
173 /**
174 * Sole constructor. (For invocation by subclass constructors, typically
175 * implicit.)
176 */
177 protected Policy() {
178 }
179
180 /**
181 * Returns the installed Policy object.
182 * This method first calls
183 * <code>SecurityManager.checkPermission</code> with the
184 * <code>AuthPermission("getPolicy")</code> permission
185 * to ensure the caller has permission to get the Policy object.
186 *
187 * <p>
188 *
189 * @return the installed Policy. The return value cannot be
190 * <code>null</code>.
191 *
192 * @exception java.lang.SecurityException if the current thread does not
193 * have permission to get the Policy object.
194 *
195 * @see #setPolicy
196 */
197 public static Policy getPolicy() {
198 java.lang.SecurityManager sm = System.getSecurityManager();
199 if (sm != null)
200 sm.checkPermission(new AuthPermission("getPolicy"));
201 return getPolicyNoCheck();
202 }
203
204 /**
205 * Returns the installed Policy object, skipping the security check.
206 *
207 * @return the installed Policy.
208 *
209 */
210 static Policy getPolicyNoCheck() {
211 if (policy == null) {
212
213 synchronized (Policy.class) {
214
215 if (policy == null) {
216 String policy_class = null;
217 policy_class = java.security.AccessController
218 .doPrivileged(new java.security.PrivilegedAction<String>() {
219 public String run() {
220 return java.security.Security
221 .getProperty("auth.policy.provider");
222 }
223 });
224 if (policy_class == null) {
225 policy_class = "com.sun.security.auth.PolicyFile";
226 }
227
228 try {
229 final String finalClass = policy_class;
230 policy = java.security.AccessController
231 .doPrivileged(new java.security.PrivilegedExceptionAction<Policy>() {
232 public Policy run()
233 throws ClassNotFoundException,
234 InstantiationException,
235 IllegalAccessException {
236 return (Policy) Class.forName(
237 finalClass, true,
238 contextClassLoader)
239 .newInstance();
240 }
241 });
242 } catch (Exception e) {
243 throw new SecurityException(
244 sun.security.util.ResourcesMgr
245 .getString("unable to instantiate Subject-based policy"));
246 }
247 }
248 }
249 }
250 return policy;
251 }
252
253 /**
254 * Sets the system-wide Policy object. This method first calls
255 * <code>SecurityManager.checkPermission</code> with the
256 * <code>AuthPermission("setPolicy")</code>
257 * permission to ensure the caller has permission to set the Policy.
258 *
259 * <p>
260 *
261 * @param policy the new system Policy object.
262 *
263 * @exception java.lang.SecurityException if the current thread does not
264 * have permission to set the Policy.
265 *
266 * @see #getPolicy
267 */
268 public static void setPolicy(Policy policy) {
269 java.lang.SecurityManager sm = System.getSecurityManager();
270 if (sm != null)
271 sm.checkPermission(new AuthPermission("setPolicy"));
272 Policy.policy = policy;
273 }
274
275 /**
276 * Retrieve the Permissions granted to the Principals associated with
277 * the specified <code>CodeSource</code>.
278 *
279 * <p>
280 *
281 * @param subject the <code>Subject</code>
282 * whose associated Principals,
283 * in conjunction with the provided
284 * <code>CodeSource</code>, determines the Permissions
285 * returned by this method. This parameter
286 * may be <code>null</code>. <p>
287 *
288 * @param cs the code specified by its <code>CodeSource</code>
289 * that determines, in conjunction with the provided
290 * <code>Subject</code>, the Permissions
291 * returned by this method. This parameter may be
292 * <code>null</code>.
293 *
294 * @return the Collection of Permissions granted to all the
295 * <code>Subject</code> and code specified in
296 * the provided <i>subject</i> and <i>cs</i>
297 * parameters.
298 */
299 public abstract java.security.PermissionCollection getPermissions(
300 Subject subject, java.security.CodeSource cs);
301
302 /**
303 * Refresh and reload the Policy.
304 *
305 * <p>This method causes this object to refresh/reload its current
306 * Policy. This is implementation-dependent.
307 * For example, if the Policy object is stored in
308 * a file, calling <code>refresh</code> will cause the file to be re-read.
309 *
310 * <p>
311 *
312 * @exception SecurityException if the caller does not have permission
313 * to refresh the Policy.
314 */
315 public abstract void refresh();
316 }
|