1 /* 2 * Copyright (c) 1996, 2013, 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.acl; 27 28 import java.util.Enumeration; 29 import java.security.Principal; 30 31 /** 32 * Interface representing an Access Control List (ACL). An Access 33 * Control List is a data structure used to guard access to 34 * resources.<p> 35 * 36 * An ACL can be thought of as a data structure with multiple ACL 37 * entries. Each ACL entry, of interface type AclEntry, contains a 38 * set of permissions associated with a particular principal. (A 39 * principal represents an entity such as an individual user or a 40 * group). Additionally, each ACL entry is specified as being either 41 * positive or negative. If positive, the permissions are to be 42 * granted to the associated principal. If negative, the permissions 43 * are to be denied.<p> 44 * 45 * The ACL Entries in each ACL observe the following rules: 46 * 47 * <ul> <li>Each principal can have at most one positive ACL entry and 48 * one negative entry; that is, multiple positive or negative ACL 49 * entries are not allowed for any principal. Each entry specifies 50 * the set of permissions that are to be granted (if positive) or 51 * denied (if negative). 52 * 53 * <li>If there is no entry for a particular principal, then the 54 * principal is considered to have a null (empty) permission set. 55 * 56 * <li>If there is a positive entry that grants a principal a 57 * particular permission, and a negative entry that denies the 58 * principal the same permission, the result is as though the 59 * permission was never granted or denied. 60 * 61 * <li>Individual permissions always override permissions of the 62 * group(s) to which the individual belongs. That is, individual 63 * negative permissions (specific denial of permissions) override the 64 * groups' positive permissions. And individual positive permissions 65 * override the groups' negative permissions. 66 * 67 * </ul> 68 * 69 * The {@code java.security.acl } package provides the 70 * interfaces to the ACL and related data structures (ACL entries, 71 * groups, permissions, etc.), and the {@code sun.security.acl } 72 * classes provide a default implementation of the interfaces. For 73 * example, {@code java.security.acl.Acl } provides the 74 * interface to an ACL and the {@code sun.security.acl.AclImpl } 75 * class provides the default implementation of the interface.<p> 76 * 77 * The {@code java.security.acl.Acl } interface extends the 78 * {@code java.security.acl.Owner } interface. The Owner 79 * interface is used to maintain a list of owners for each ACL. Only 80 * owners are allowed to modify an ACL. For example, only an owner can 81 * call the ACL's {@code addEntry} method to add a new ACL entry 82 * to the ACL. 83 * 84 * @see java.security.acl.AclEntry 85 * @see java.security.acl.Owner 86 * @see java.security.acl.Acl#getPermissions 87 * 88 * @author Satish Dharmaraj 89 */ 90 91 public interface Acl extends Owner { 92 93 /** 94 * Sets the name of this ACL. 95 * 96 * @param caller the principal invoking this method. It must be an 97 * owner of this ACL. 98 * 99 * @param name the name to be given to this ACL. 100 * 101 * @exception NotOwnerException if the caller principal 102 * is not an owner of this ACL. 103 * 104 * @see #getName 105 */ 106 public void setName(Principal caller, String name) 107 throws NotOwnerException; 108 109 /** 110 * Returns the name of this ACL. 111 * 112 * @return the name of this ACL. 113 * 114 * @see #setName 115 */ 116 public String getName(); 117 118 /** 119 * Adds an ACL entry to this ACL. An entry associates a principal 120 * (e.g., an individual or a group) with a set of 121 * permissions. Each principal can have at most one positive ACL 122 * entry (specifying permissions to be granted to the principal) 123 * and one negative ACL entry (specifying permissions to be 124 * denied). If there is already an ACL entry of the same type 125 * (negative or positive) already in the ACL, false is returned. 126 * 127 * @param caller the principal invoking this method. It must be an 128 * owner of this ACL. 129 * 130 * @param entry the ACL entry to be added to this ACL. 131 * 132 * @return true on success, false if an entry of the same type 133 * (positive or negative) for the same principal is already 134 * present in this ACL. 135 * 136 * @exception NotOwnerException if the caller principal 137 * is not an owner of this ACL. 138 */ 139 public boolean addEntry(Principal caller, AclEntry entry) 140 throws NotOwnerException; 141 142 /** 143 * Removes an ACL entry from this ACL. 144 * 145 * @param caller the principal invoking this method. It must be an 146 * owner of this ACL. 147 * 148 * @param entry the ACL entry to be removed from this ACL. 149 * 150 * @return true on success, false if the entry is not part of this ACL. 151 * 152 * @exception NotOwnerException if the caller principal is not 153 * an owner of this Acl. 154 */ 155 public boolean removeEntry(Principal caller, AclEntry entry) 156 throws NotOwnerException; 157 158 /** 159 * Returns an enumeration for the set of allowed permissions for the 160 * specified principal (representing an entity such as an individual or 161 * a group). This set of allowed permissions is calculated as 162 * follows: 163 * 164 * <ul> 165 * 166 * <li>If there is no entry in this Access Control List for the 167 * specified principal, an empty permission set is returned. 168 * 169 * <li>Otherwise, the principal's group permission sets are determined. 170 * (A principal can belong to one or more groups, where a group is a 171 * group of principals, represented by the Group interface.) 172 * The group positive permission set is the union of all 173 * the positive permissions of each group that the principal belongs to. 174 * The group negative permission set is the union of all 175 * the negative permissions of each group that the principal belongs to. 176 * If there is a specific permission that occurs in both 177 * the positive permission set and the negative permission set, 178 * it is removed from both.<p> 179 * 180 * The individual positive and negative permission sets are also 181 * determined. The positive permission set contains the permissions 182 * specified in the positive ACL entry (if any) for the principal. 183 * Similarly, the negative permission set contains the permissions 184 * specified in the negative ACL entry (if any) for the principal. 185 * The individual positive (or negative) permission set is considered 186 * to be null if there is not a positive (negative) ACL entry for the 187 * principal in this ACL.<p> 188 * 189 * The set of permissions granted to the principal is then calculated 190 * using the simple rule that individual permissions always override 191 * the group permissions. That is, the principal's individual negative 192 * permission set (specific denial of permissions) overrides the group 193 * positive permission set, and the principal's individual positive 194 * permission set overrides the group negative permission set. 195 * 196 * </ul> 197 * 198 * @param user the principal whose permission set is to be returned. 199 * 200 * @return the permission set specifying the permissions the principal 201 * is allowed. 202 */ 203 public Enumeration<Permission> getPermissions(Principal user); 204 205 /** 206 * Returns an enumeration of the entries in this ACL. Each element in 207 * the enumeration is of type AclEntry. 208 * 209 * @return an enumeration of the entries in this ACL. 210 */ 211 public Enumeration<AclEntry> entries(); 212 213 /** 214 * Checks whether or not the specified principal has the specified 215 * permission. If it does, true is returned, otherwise false is returned. 216 * 217 * More specifically, this method checks whether the passed permission 218 * is a member of the allowed permission set of the specified principal. 219 * The allowed permission set is determined by the same algorithm as is 220 * used by the {@code getPermissions} method. 221 * 222 * @param principal the principal, assumed to be a valid authenticated 223 * Principal. 224 * 225 * @param permission the permission to be checked for. 226 * 227 * @return true if the principal has the specified permission, false 228 * otherwise. 229 * 230 * @see #getPermissions 231 */ 232 public boolean checkPermission(Principal principal, Permission permission); 233 234 /** 235 * Returns a string representation of the 236 * ACL contents. 237 * 238 * @return a string representation of the ACL contents. 239 */ 240 public String toString(); 241 } 242
