1 /*
2 * Copyright (c) 1998, 2015, Oracle and/or its affiliates. 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. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.security.auth;
27
28 /**
29 * This class is for authentication permissions. An {@code AuthPermission}
30 * contains a name (also referred to as a "target name") but no actions
31 * list; you either have the named permission or you don't.
32 *
33 * <p> The target name is the name of a security configuration parameter
34 * (see below). Currently the {@code AuthPermission} object is used to
35 * guard access to the {@link Policy}, {@link Subject},
36 * {@link javax.security.auth.login.LoginContext}, and
37 * {@link javax.security.auth.login.Configuration} objects.
38 *
39 * <p> The standard target names for an Authentication Permission are:
40 *
41 * <pre>
42 * doAs - allow the caller to invoke the
43 * {@code Subject.doAs} methods.
44 *
45 * doAsPrivileged - allow the caller to invoke the
46 * {@code Subject.doAsPrivileged} methods.
47 *
48 * getSubject - allow for the retrieval of the
49 * Subject(s) associated with the
50 * current Thread.
51 *
52 * getSubjectFromDomainCombiner - allow for the retrieval of the
53 * Subject associated with the
54 * a {@code SubjectDomainCombiner}.
55 *
56 * setReadOnly - allow the caller to set a Subject
57 * to be read-only.
58 *
59 * modifyPrincipals - allow the caller to modify the {@code Set}
60 * of Principals associated with a
61 * {@code Subject}
62 *
63 * modifyPublicCredentials - allow the caller to modify the
64 * {@code Set} of public credentials
65 * associated with a {@code Subject}
66 *
67 * modifyPrivateCredentials - allow the caller to modify the
68 * {@code Set} of private credentials
69 * associated with a {@code Subject}
70 *
71 * refreshCredential - allow code to invoke the {@code refresh}
72 * method on a credential which implements
73 * the {@code Refreshable} interface.
74 *
75 * destroyCredential - allow code to invoke the {@code destroy}
76 * method on a credential {@code object}
77 * which implements the {@code Destroyable}
78 * interface.
79 *
80 * createLoginContext.{name} - allow code to instantiate a
81 * {@code LoginContext} with the
82 * specified {@code name}. {@code name}
83 * is used as the index into the installed login
84 * {@code Configuration}
85 * (that returned by
86 * {@code Configuration.getConfiguration()}).
87 * <i>name</i> can be wildcarded (set to '*')
88 * to allow for any name.
89 *
90 * getLoginConfiguration - allow for the retrieval of the system-wide
91 * login Configuration.
92 *
93 * createLoginConfiguration.{type} - allow code to obtain a Configuration
94 * object via
95 * {@code Configuration.getInstance}.
96 *
97 * setLoginConfiguration - allow for the setting of the system-wide
98 * login Configuration.
99 *
100 * refreshLoginConfiguration - allow for the refreshing of the system-wide
101 * login Configuration.
102 * </pre>
103 *
104 * <p>Please note that granting this permission with the "modifyPrincipals",
105 * "modifyPublicCredentials" or "modifyPrivateCredentials" target allows
106 * a JAAS login module to populate principal or credential objects into
107 * the Subject. Although reading information inside the private credentials
108 * set requires a {@link PrivateCredentialPermission} of the credential type to
109 * be granted, reading information inside the principals set and the public
110 * credentials set requires no additional permission. These objects can contain
111 * potentially sensitive information. For example, login modules that read
112 * local user information or perform a Kerberos login are able to add
113 * potentially sensitive information such as user ids, groups and domain names
114 * to the principals set.
115 *
116 * <p> The following target name has been deprecated in favor of
117 * {@code createLoginContext.{name}}.
118 *
119 * <pre>
120 * createLoginContext - allow code to instantiate a
121 * {@code LoginContext}.
122 * </pre>
123 *
124 * <p> {@code javax.security.auth.Policy} has been
125 * deprecated in favor of {@code java.security.Policy}.
126 * Therefore, the following target names have also been deprecated:
127 *
128 * <pre>
129 * getPolicy - allow the caller to retrieve the system-wide
130 * Subject-based access control policy.
131 *
132 * setPolicy - allow the caller to set the system-wide
133 * Subject-based access control policy.
134 *
135 * refreshPolicy - allow the caller to refresh the system-wide
136 * Subject-based access control policy.
137 * </pre>
138 *
139 * @implNote
140 * Implementations may define additional target names, but should use naming
141 * conventions such as reverse domain name notation to avoid name clashes.
142 * @since 1.4
143 */
144 public final class AuthPermission extends
145 java.security.BasicPermission {
146
147 private static final long serialVersionUID = 5806031445061587174L;
148
149 /**
150 * Creates a new AuthPermission with the specified name.
151 * The name is the symbolic name of the AuthPermission.
152 *
153 * @param name the name of the AuthPermission
154 *
155 * @throws NullPointerException if {@code name} is {@code null}.
156 * @throws IllegalArgumentException if {@code name} is empty.
157 */
158 public AuthPermission(String name) {
159 // for backwards compatibility --
160 // createLoginContext is deprecated in favor of createLoginContext.*
161 super("createLoginContext".equals(name) ?
162 "createLoginContext.*" : name);
163 }
164
165 /**
166 * Creates a new AuthPermission object with the specified name.
167 * The name is the symbolic name of the AuthPermission, and the
168 * actions String is currently unused and should be null.
169 *
170 * @param name the name of the AuthPermission
171 *
172 * @param actions should be null.
173 *
174 * @throws NullPointerException if {@code name} is {@code null}.
175 * @throws IllegalArgumentException if {@code name} is empty.
176 */
177 public AuthPermission(String name, String actions) {
178 // for backwards compatibility --
179 // createLoginContext is deprecated in favor of createLoginContext.*
180 super("createLoginContext".equals(name) ?
181 "createLoginContext.*" : name, actions);
182 }
183 }