1 /* |
1 /* |
2 * Copyright (c) 1998, 2012, Oracle and/or its affiliates. All rights reserved. |
2 * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. |
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 * |
4 * |
5 * This code is free software; you can redistribute it and/or modify it |
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 |
6 * under the terms of the GNU General Public License version 2 only, as |
7 * published by the Free Software Foundation. Oracle designates this |
7 * published by the Free Software Foundation. Oracle designates this |
30 |
30 |
31 /** |
31 /** |
32 * <p> This is an abstract class for representing the system policy for |
32 * <p> This is an abstract class for representing the system policy for |
33 * Subject-based authorization. A subclass implementation |
33 * Subject-based authorization. A subclass implementation |
34 * of this class provides a means to specify a Subject-based |
34 * of this class provides a means to specify a Subject-based |
35 * access control <code>Policy</code>. |
35 * access control {@code Policy}. |
36 * |
36 * |
37 * <p> A <code>Policy</code> object can be queried for the set of |
37 * <p> A {@code Policy} object can be queried for the set of |
38 * Permissions granted to code running as a |
38 * Permissions granted to code running as a |
39 * <code>Principal</code> in the following manner: |
39 * {@code Principal} in the following manner: |
40 * |
40 * |
41 * <pre> |
41 * <pre> |
42 * policy = Policy.getPolicy(); |
42 * policy = Policy.getPolicy(); |
43 * PermissionCollection perms = policy.getPermissions(subject, |
43 * PermissionCollection perms = policy.getPermissions(subject, |
44 * codeSource); |
44 * codeSource); |
45 * </pre> |
45 * </pre> |
46 * |
46 * |
47 * The <code>Policy</code> object consults the local policy and returns |
47 * The {@code Policy} object consults the local policy and returns |
48 * and appropriate <code>Permissions</code> object with the |
48 * and appropriate {@code Permissions} object with the |
49 * Permissions granted to the Principals associated with the |
49 * Permissions granted to the Principals associated with the |
50 * provided <i>subject</i>, and granted to the code specified |
50 * provided <i>subject</i>, and granted to the code specified |
51 * by the provided <i>codeSource</i>. |
51 * by the provided <i>codeSource</i>. |
52 * |
52 * |
53 * <p> A <code>Policy</code> contains the following information. |
53 * <p> A {@code Policy} contains the following information. |
54 * Note that this example only represents the syntax for the default |
54 * Note that this example only represents the syntax for the default |
55 * <code>Policy</code> implementation. Subclass implementations of this class |
55 * {@code Policy} implementation. Subclass implementations of this class |
56 * may implement alternative syntaxes and may retrieve the |
56 * may implement alternative syntaxes and may retrieve the |
57 * <code>Policy</code> from any source such as files, databases, |
57 * {@code Policy} from any source such as files, databases, |
58 * or servers. |
58 * or servers. |
59 * |
59 * |
60 * <p> Each entry in the <code>Policy</code> is represented as |
60 * <p> Each entry in the {@code Policy} is represented as |
61 * a <b><i>grant</i></b> entry. Each <b><i>grant</i></b> entry |
61 * a <b><i>grant</i></b> entry. Each <b><i>grant</i></b> entry |
62 * specifies a codebase, code signers, and Principals triplet, |
62 * specifies a codebase, code signers, and Principals triplet, |
63 * as well as the Permissions granted to that triplet. |
63 * as well as the Permissions granted to that triplet. |
64 * |
64 * |
65 * <pre> |
65 * <pre> |
82 * permission java.io.FilePermission "/home/duke", "read, write"; |
82 * permission java.io.FilePermission "/home/duke", "read, write"; |
83 * }; |
83 * }; |
84 * </pre> |
84 * </pre> |
85 * |
85 * |
86 * This <b><i>grant</i></b> entry specifies that code from "foo.com", |
86 * This <b><i>grant</i></b> entry specifies that code from "foo.com", |
87 * signed by "foo', and running as a <code>SolarisPrincipal</code> with the |
87 * signed by "foo', and running as a {@code SolarisPrincipal} with the |
88 * name, duke, has one <code>Permission</code>. This <code>Permission</code> |
88 * name, duke, has one {@code Permission}. This {@code Permission} |
89 * permits the executing code to read and write files in the directory, |
89 * permits the executing code to read and write files in the directory, |
90 * "/home/duke". |
90 * "/home/duke". |
91 * |
91 * |
92 * <p> To "run" as a particular <code>Principal</code>, |
92 * <p> To "run" as a particular {@code Principal}, |
93 * code invokes the <code>Subject.doAs(subject, ...)</code> method. |
93 * code invokes the {@code Subject.doAs(subject, ...)} method. |
94 * After invoking that method, the code runs as all the Principals |
94 * After invoking that method, the code runs as all the Principals |
95 * associated with the specified <code>Subject</code>. |
95 * associated with the specified {@code Subject}. |
96 * Note that this <code>Policy</code> (and the Permissions |
96 * Note that this {@code Policy} (and the Permissions |
97 * granted in this <code>Policy</code>) only become effective |
97 * granted in this {@code Policy}) only become effective |
98 * after the call to <code>Subject.doAs</code> has occurred. |
98 * after the call to {@code Subject.doAs} has occurred. |
99 * |
99 * |
100 * <p> Multiple Principals may be listed within one <b><i>grant</i></b> entry. |
100 * <p> Multiple Principals may be listed within one <b><i>grant</i></b> entry. |
101 * All the Principals in the grant entry must be associated with |
101 * All the Principals in the grant entry must be associated with |
102 * the <code>Subject</code> provided to <code>Subject.doAs</code> |
102 * the {@code Subject} provided to {@code Subject.doAs} |
103 * for that <code>Subject</code> to be granted the specified Permissions. |
103 * for that {@code Subject} to be granted the specified Permissions. |
104 * |
104 * |
105 * <pre> |
105 * <pre> |
106 * grant Principal com.sun.security.auth.SolarisPrincipal "duke", |
106 * grant Principal com.sun.security.auth.SolarisPrincipal "duke", |
107 * Principal com.sun.security.auth.SolarisNumericUserPrincipal "0" { |
107 * Principal com.sun.security.auth.SolarisNumericUserPrincipal "0" { |
108 * permission java.io.FilePermission "/home/duke", "read, write"; |
108 * permission java.io.FilePermission "/home/duke", "read, write"; |
113 * This entry grants any code running as both "duke" and "0" |
113 * This entry grants any code running as both "duke" and "0" |
114 * permission to read and write files in duke's home directory, |
114 * permission to read and write files in duke's home directory, |
115 * as well as permission to make socket connections to "duke.com". |
115 * as well as permission to make socket connections to "duke.com". |
116 * |
116 * |
117 * <p> Note that non Principal-based grant entries are not permitted |
117 * <p> Note that non Principal-based grant entries are not permitted |
118 * in this <code>Policy</code>. Therefore, grant entries such as: |
118 * in this {@code Policy}. Therefore, grant entries such as: |
119 * |
119 * |
120 * <pre> |
120 * <pre> |
121 * grant CodeBase "foo.com", Signedby "foo" { |
121 * grant CodeBase "foo.com", Signedby "foo" { |
122 * permission java.io.FilePermission "/tmp/scratch", "read, write"; |
122 * permission java.io.FilePermission "/tmp/scratch", "read, write"; |
123 * }; |
123 * }; |
124 * </pre> |
124 * </pre> |
125 * |
125 * |
126 * are rejected. Such permission must be listed in the |
126 * are rejected. Such permission must be listed in the |
127 * <code>java.security.Policy</code>. |
127 * {@code java.security.Policy}. |
128 * |
128 * |
129 * <p> The default {@code Policy} implementation can be changed by |
129 * <p> The default {@code Policy} implementation can be changed by |
130 * setting the value of the {@code auth.policy.provider} security property to |
130 * setting the value of the {@code auth.policy.provider} security property to |
131 * the fully qualified name of the desired {@code Policy} implementation class. |
131 * the fully qualified name of the desired {@code Policy} implementation class. |
132 * |
132 * |
177 protected Policy() { } |
177 protected Policy() { } |
178 |
178 |
179 /** |
179 /** |
180 * Returns the installed Policy object. |
180 * Returns the installed Policy object. |
181 * This method first calls |
181 * This method first calls |
182 * <code>SecurityManager.checkPermission</code> with the |
182 * {@code SecurityManager.checkPermission} with the |
183 * <code>AuthPermission("getPolicy")</code> permission |
183 * {@code AuthPermission("getPolicy")} permission |
184 * to ensure the caller has permission to get the Policy object. |
184 * to ensure the caller has permission to get the Policy object. |
185 * |
185 * |
186 * <p> |
186 * <p> |
187 * |
187 * |
188 * @return the installed Policy. The return value cannot be |
188 * @return the installed Policy. The return value cannot be |
189 * <code>null</code>. |
189 * {@code null}. |
190 * |
190 * |
191 * @exception java.lang.SecurityException if the current thread does not |
191 * @exception java.lang.SecurityException if the current thread does not |
192 * have permission to get the Policy object. |
192 * have permission to get the Policy object. |
193 * |
193 * |
194 * @see #setPolicy |
194 * @see #setPolicy |
311 return false; |
311 return false; |
312 } |
312 } |
313 |
313 |
314 /** |
314 /** |
315 * Retrieve the Permissions granted to the Principals associated with |
315 * Retrieve the Permissions granted to the Principals associated with |
316 * the specified <code>CodeSource</code>. |
316 * the specified {@code CodeSource}. |
317 * |
317 * |
318 * <p> |
318 * <p> |
319 * |
319 * |
320 * @param subject the <code>Subject</code> |
320 * @param subject the {@code Subject} |
321 * whose associated Principals, |
321 * whose associated Principals, |
322 * in conjunction with the provided |
322 * in conjunction with the provided |
323 * <code>CodeSource</code>, determines the Permissions |
323 * {@code CodeSource}, determines the Permissions |
324 * returned by this method. This parameter |
324 * returned by this method. This parameter |
325 * may be <code>null</code>. <p> |
325 * may be {@code null}. <p> |
326 * |
326 * |
327 * @param cs the code specified by its <code>CodeSource</code> |
327 * @param cs the code specified by its {@code CodeSource} |
328 * that determines, in conjunction with the provided |
328 * that determines, in conjunction with the provided |
329 * <code>Subject</code>, the Permissions |
329 * {@code Subject}, the Permissions |
330 * returned by this method. This parameter may be |
330 * returned by this method. This parameter may be |
331 * <code>null</code>. |
331 * {@code null}. |
332 * |
332 * |
333 * @return the Collection of Permissions granted to all the |
333 * @return the Collection of Permissions granted to all the |
334 * <code>Subject</code> and code specified in |
334 * {@code Subject} and code specified in |
335 * the provided <i>subject</i> and <i>cs</i> |
335 * the provided <i>subject</i> and <i>cs</i> |
336 * parameters. |
336 * parameters. |
337 */ |
337 */ |
338 public abstract java.security.PermissionCollection getPermissions |
338 public abstract java.security.PermissionCollection getPermissions |
339 (Subject subject, |
339 (Subject subject, |
343 * Refresh and reload the Policy. |
343 * Refresh and reload the Policy. |
344 * |
344 * |
345 * <p>This method causes this object to refresh/reload its current |
345 * <p>This method causes this object to refresh/reload its current |
346 * Policy. This is implementation-dependent. |
346 * Policy. This is implementation-dependent. |
347 * For example, if the Policy object is stored in |
347 * For example, if the Policy object is stored in |
348 * a file, calling <code>refresh</code> will cause the file to be re-read. |
348 * a file, calling {@code refresh} will cause the file to be re-read. |
349 * |
349 * |
350 * <p> |
350 * <p> |
351 * |
351 * |
352 * @exception SecurityException if the caller does not have permission |
352 * @exception SecurityException if the caller does not have permission |
353 * to refresh the Policy. |
353 * to refresh the Policy. |