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