1 /*
2  * Copyright (c) 1997, 2021, 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 java.security;
27 
28 /**
29  * Abstract class for representing access to a system resource.
30  * All permissions have a name (whose interpretation depends on the subclass),
31  * as well as abstract functions for defining the semantics of the
32  * particular Permission subclass.
33  *
34  * <p>Most Permission objects also include an "actions" list that tells the actions
35  * that are permitted for the object.  For example,
36  * for a {@code java.io.FilePermission} object, the permission name is
37  * the pathname of a file (or directory), and the actions list
38  * (such as "read, write") specifies which actions are granted for the
39  * specified file (or for files in the specified directory).
40  * The actions list is optional for Permission objects, such as
41  * {@code java.lang.RuntimePermission},
42  * that don't need such a list; you either have the named permission (such
43  * as "system.exit") or you don't.
44  *
45  * <p>An important method that must be implemented by each subclass is
46  * the {@code implies} method to compare Permissions. Basically,
47  * "permission p1 implies permission p2" means that
48  * if one is granted permission p1, one is naturally granted permission p2.
49  * Thus, this is not an equality test, but rather more of a
50  * subset test.
51  *
52  * <P> Permission objects are similar to String objects in that they
53  * are immutable once they have been created. Subclasses should not
54  * provide methods that can change the state of a permission
55  * once it has been created.
56  *
57  * @see Permissions
58  * @see PermissionCollection
59  *
60  *
61  * @author Marianne Mueller
62  * @author Roland Schemers
63  * @since 1.2
64  */
65 
66 public abstract class Permission implements Guard, java.io.Serializable {
67 
68     @java.io.Serial
69     private static final long serialVersionUID = -5636570222231596674L;
70 
71     /**
72      * The permission name.
73      */
74     private String name;
75 
76     /**
77      * Constructs a permission with the specified name.
78      *
79      * @param name name of the Permission object being created.
80      *
81      */
82 
Permission(String name)83     public Permission(String name) {
84         this.name = name;
85     }
86 
87     /**
88      * Implements the guard interface for a permission. The
89      * {@code SecurityManager.checkPermission} method is called,
90      * passing this permission object as the permission to check.
91      * Returns silently if access is granted. Otherwise, throws
92      * a SecurityException.
93      *
94      * @param object the object being guarded (currently ignored).
95      *
96      * @throws SecurityException
97      *        if a security manager exists and its
98      *        {@code checkPermission} method doesn't allow access.
99      *
100      * @see Guard
101      * @see GuardedObject
102      * @see SecurityManager#checkPermission
103      *
104      */
checkGuard(Object object)105     public void checkGuard(Object object) throws SecurityException {
106         @SuppressWarnings("removal")
107         SecurityManager sm = System.getSecurityManager();
108         if (sm != null) sm.checkPermission(this);
109     }
110 
111     /**
112      * Checks if the specified permission's actions are "implied by"
113      * this object's actions.
114      * <P>
115      * This must be implemented by subclasses of Permission, as they are the
116      * only ones that can impose semantics on a Permission object.
117      *
118      * <p>The {@code implies} method is used by the AccessController to determine
119      * whether or not a requested permission is implied by another permission that
120      * is known to be valid in the current execution context.
121      *
122      * @param permission the permission to check against.
123      *
124      * @return true if the specified permission is implied by this object,
125      * false if not.
126      */
127 
implies(Permission permission)128     public abstract boolean implies(Permission permission);
129 
130     /**
131      * Checks two Permission objects for equality.
132      * <P>
133      * Do not use the {@code equals} method for making access control
134      * decisions; use the {@code implies} method.
135      *
136      * @param obj the object we are testing for equality with this object.
137      *
138      * @return true if both Permission objects are equivalent.
139      */
140 
equals(Object obj)141     public abstract boolean equals(Object obj);
142 
143     /**
144      * Returns the hash code value for this Permission object.
145      * <P>
146      * The required {@code hashCode} behavior for Permission Objects is
147      * the following:
148      * <ul>
149      * <li>Whenever it is invoked on the same Permission object more than
150      *     once during an execution of a Java application, the
151      *     {@code hashCode} method
152      *     must consistently return the same integer. This integer need not
153      *     remain consistent from one execution of an application to another
154      *     execution of the same application.
155      * <li>If two Permission objects are equal according to the
156      *     {@code equals}
157      *     method, then calling the {@code hashCode} method on each of the
158      *     two Permission objects must produce the same integer result.
159      * </ul>
160      *
161      * @return a hash code value for this object.
162      */
163 
hashCode()164     public abstract int hashCode();
165 
166     /**
167      * Returns the name of this Permission.
168      * For example, in the case of a {@code java.io.FilePermission},
169      * the name will be a pathname.
170      *
171      * @return the name of this Permission.
172      *
173      */
174 
getName()175     public final String getName() {
176         return name;
177     }
178 
179     /**
180      * Returns the actions as a String. This is abstract
181      * so subclasses can defer creating a String representation until
182      * one is needed. Subclasses should always return actions in what they
183      * consider to be their
184      * canonical form. For example, two FilePermission objects created via
185      * the following:
186      *
187      * <pre>
188      *   perm1 = new FilePermission(p1,"read,write");
189      *   perm2 = new FilePermission(p2,"write,read");
190      * </pre>
191      *
192      * both return
193      * "read,write" when the {@code getActions} method is invoked.
194      *
195      * @return the actions of this Permission.
196      *
197      */
198 
getActions()199     public abstract String getActions();
200 
201     /**
202      * Returns an empty PermissionCollection for a given Permission object, or null if
203      * one is not defined. Subclasses of class Permission should
204      * override this if they need to store their permissions in a particular
205      * PermissionCollection object in order to provide the correct semantics
206      * when the {@code PermissionCollection.implies} method is called.
207      * If null is returned,
208      * then the caller of this method is free to store permissions of this
209      * type in any PermissionCollection they choose (one that uses a Hashtable,
210      * one that uses a Vector, etc).
211      *
212      * @return a new PermissionCollection object for this type of Permission, or
213      * null if one is not defined.
214      */
215 
newPermissionCollection()216     public PermissionCollection newPermissionCollection() {
217         return null;
218     }
219 
220     /**
221      * Returns a string describing this Permission.  The convention is to
222      * specify the class name, the permission name, and the actions in
223      * the following format: '("ClassName" "name" "actions")', or
224      * '("ClassName" "name")' if actions list is null or empty.
225      *
226      * @return information about this Permission.
227      */
toString()228     public String toString() {
229         String actions = getActions();
230         if (actions == null || actions.isEmpty()) { // OPTIONAL
231             return "(\"" + getClass().getName() + "\" \"" + name + "\")";
232         } else {
233             return "(\"" + getClass().getName() + "\" \"" + name +
234                  "\" \"" + actions + "\")";
235         }
236     }
237 }
238