1/* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18package java.security.acl; 19 20import java.security.Principal; 21import java.util.Enumeration; 22 23/** 24 * The <i>Access Control List</i> (<b>ACL</b>) interface definition. 25 * <p> 26 * An ACL is a set of {@link AclEntry} objects. 27 * <p> 28 * An {@code AclEntry} is a list of {@link Permission}s that are granted 29 * (<i>positive</i>) or denied 30 * (<i>negative</i>) to a {@link Principal}. 31 * <p> 32 * An {@code Acl} has a list of owners ({@link Owner}) which are principals as 33 * well {@code Principal}. Only those principals which are the {@code Acl}'s 34 * owners are allowed to modify the {@code 35 * Acl}. 36 * <p> 37 * The <i>ACL</i> has to conform to the following rules: 38 * <ul> 39 * <li>For each {@code Principal} there can be only one <i>positive</i> and one 40 * <i>negative</i> {@code AclEntry}.</li> 41 * <li>If the two {@code AclEntry}'s (<i>positive</i> and <i>negative</i>) for a 42 * specific {@code Principal} grant and deny the same {@code Permission} to that 43 * {@code Principal}, then that {@code Permission} is treated as 44 * neither granted nor denied to that {@code Principal}.</li> 45 * <li>Permissions associated with an individual {@code Principal} always 46 * override permissions of the group(s) to which the individual belongs.</li> 47 * <li>If there is no {@code AclEntry} associated with a specific {@code 48 * Principal}, then it is interpreted as an empty list of permissions.</li> 49 * </ul> 50 */ 51public interface Acl extends Owner { 52 53 /** 54 * Sets the name of this <i>ACL</i> instance. 55 * 56 * @param caller 57 * the invoking {@code Principal}. 58 * @param name 59 * the name to be set. 60 * @throws NotOwnerException 61 * if the invoking {@code Principal} is not an owner of this 62 * <i>ACL</i>. 63 */ 64 void setName(Principal caller, String name) throws NotOwnerException; 65 66 /** 67 * Returns the name of this <i>ACL</i> instance. 68 * 69 * @return the name of this <i>ACL</i> instance. 70 */ 71 String getName(); 72 73 /** 74 * Adds an {@code AclEntry} to this <i>ACL</i> instance. 75 * <p> 76 * If the <i>ACL</i> already has an {@code AclEntry} of the same type (<i> 77 * positive</i> or <i>negative</i>) and principal, then the new entry is not added. 78 * 79 * @param caller 80 * the invoking {@code Principal}. 81 * @param entry 82 * the ACL entry to add. 83 * @return {@code true} if the entry is added, {@code false} if there is 84 * already an entry of the same type for the same principal 85 * @throws NotOwnerException 86 * if the invoking {@code Principal} is not an owner of this 87 * <i>ACL</i>. 88 */ 89 boolean addEntry(Principal caller, AclEntry entry) throws NotOwnerException; 90 91 /** 92 * Removes an {@code AclEntry} from this <i>ACL</i> instance. 93 * 94 * @param caller 95 * the invoking {@code Principal}. 96 * @param entry 97 * the ACL entry to remove. 98 * @return {@code true} if the entry is removed, {@code false} if the entry 99 * is not in this <i>ACL</i>. 100 * @throws NotOwnerException 101 * if the invoking {@code Principal} is not an owner of this 102 * <i>ACL</i>. 103 */ 104 boolean removeEntry(Principal caller, AclEntry entry) 105 throws NotOwnerException; 106 107 /** 108 * Returns the set of allowed permissions for the specified {@code 109 * Principal}. 110 * <p> 111 * If the specified principal has no entry in this ACL, an empty set is 112 * returned. 113 * <p> 114 * The allowed permissions are collected according to the following rules: 115 * <ul> 116 * <li>The two permission lists (<i>positive</i> and <i>negative</i>) of the 117 * principal's groups ({@link Group}) are collected. The positive (granted) 118 * permissions are the union of all group's positive permissions that the 119 * principal belongs to, the negative (denied) permissions are the union of 120 * all group's negative permissions that the principal belongs to. If a 121 * specific permission is in both the positive and the negative list, it is 122 * removed from both lists.</li> 123 * <li>The individual permissions (<i>positive</i> and <i>negative</i>) of 124 * the principal override the group permissions. The positive individual 125 * permissions override the group's negative permissions and the negative 126 * individual permissions override the grpup's positive permissions.</li> 127 * </ul> 128 * 129 * @param user 130 * the principal to get the allowed permissions for. 131 * @return the set of allowed permissions for the specified principal. 132 */ 133 Enumeration<Permission> getPermissions(Principal user); 134 135 /** 136 * Returns an {@code Enumeration} of the {@code AclEntry} of this 137 * <i>ACL</i>. 138 * 139 * @return an {@code Enumeration} of the {@code AclEntry} of this 140 * <i>ACL</i>. 141 */ 142 Enumeration<AclEntry> entries(); 143 144 /** 145 * Checks whether the specified principal is granted the specified 146 * permission. 147 * <p> 148 * The list of granted permissions is determined according to the rules 149 * specified by {@code getPermissions}. 150 * 151 * @param principal 152 * the principal the check the permissions for. 153 * @param permission 154 * the permission to check for the principal. 155 * @return {@code true} if the principal is granted the permission, 156 * otherwise {@code false}. 157 * @see #getPermissions(Principal) 158 */ 159 boolean checkPermission(Principal principal, Permission permission); 160 161 /** 162 * Returns the string representation of this ACL. 163 * 164 * @return the string representation of this ACL. 165 */ 166 String toString(); 167} 168