001/* 002 * Copyright (c) 2006-2011 Nuxeo SA (http://nuxeo.com/) and others. 003 * 004 * All rights reserved. This program and the accompanying materials 005 * are made available under the terms of the Eclipse Public License v1.0 006 * which accompanies this distribution, and is available at 007 * http://www.eclipse.org/legal/epl-v10.html 008 * 009 * Contributors: 010 * Nuxeo - initial API and implementation 011 * 012 * $Id$ 013 */ 014 015package org.nuxeo.ecm.core.api.security; 016 017import java.io.Serializable; 018import java.util.Set; 019 020/** 021 * Access control policy (ACP) control the permissions access on a resource. 022 * <p> 023 * An ACP may contains several ACLs (access control list) identified by names. 024 * <p> 025 * The list of ACLs is ordered so that when checking permissions the ACL are consulted in an ascending order. (The ACL 026 * on position 0 is consulted first). 027 * <p> 028 * Every ACP has at least one ACL having the reserved name "local". This is the only user editable list (through the 029 * security UI). 030 * <p> 031 * Other ACLs are used internally and are editable only through the API. 032 * <p> 033 * Also an ACP may have a list named "inherited" that represents the ACLs inherited from the resource parents if any. 034 * These ACLs are merged in a single list that is always read only even through the API. 035 * 036 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a> 037 * @author <a href="mailto:ja@nuxeo.com">Julien Anguenot</a> 038 */ 039public interface ACP extends Serializable, Cloneable { 040 041 /** 042 * Check whether this ACP grant the given permission on the given user, denies it or doesn't specify a rule. 043 * <p> 044 * This is checking only the ACLs on that ACP. Parents if any are not checked. 045 * 046 * @param principal the principal to check 047 * @param permission the permission to check 048 * @return Access.GRANT if granted, Access.DENY if denied or Access.UNKNOWN if no rule for that permission exists. 049 * Never returns null. 050 */ 051 Access getAccess(String principal, String permission); 052 053 /** 054 * Checks the access on the ACLs for each set of the given permissions and principals. 055 * <p> 056 * This differs for an iterative check using getAccess(String principal, String permission) in the order of checks - 057 * so that in this case each ACE is fully checked against the given users and permissions before passing to the next 058 * ACE. 059 * 060 * @param principals 061 * @param permissions 062 * @return 063 */ 064 Access getAccess(String[] principals, String[] permissions); 065 066 /** 067 * Replaces the modifiable user entries (associated with the currentDocument) related to the current ACP. 068 * <p> 069 * Considers that all the passed entries are modifiable and attempts to set them as local entries related to the 070 * current document. 071 * 072 * @param userEntries 073 */ 074 void setRules(UserEntry[] userEntries); 075 076 /** 077 * Replaces the modifiable user entries (associated with the currentDocument) related to the current ACP. 078 * <p> 079 * Considers that all the passed entries are modifiable and attempts to set them as local entries related to the 080 * current document. 081 * <p> 082 * The current behavior reset <strong>completely</strong> the current ACL. 083 * 084 * @param userEntries 085 * @param overwrite if true, will overwrite the whole current ACL 086 */ 087 void setRules(UserEntry[] userEntries, boolean overwrite); 088 089 /** 090 * Replaces the modifiable user entries (associated with the currentDocument) related to the ACP. 091 * <p> 092 * Considers that all the passed entries are modifiable and attempts to set them as entries related to the current 093 * document. 094 * 095 * @param aclName 096 * @param userEntries 097 */ 098 void setRules(String aclName, UserEntry[] userEntries); 099 100 /** 101 * Replaces the modifiable user entries (associated with the currentDocument) related to the ACP. 102 * <p> 103 * Considers that all the passed entries are modifiable and attempts to set them as entries related to the current 104 * document. 105 * 106 * @param aclName 107 * @param userEntries 108 * @param overwrite if true, will overwrite the whole ACL 109 */ 110 void setRules(String aclName, UserEntry[] userEntries, boolean overwrite); 111 112 /** 113 * 114 * @param acl 115 */ 116 void addACL(ACL acl); 117 118 void addACL(int pos, ACL acl); 119 120 /** 121 * @deprecated since 7.4. Always use {@link #addACL(ACL)} to have correctly ordered acls. To force by-passing the 122 * order, use {@link #addACL(int, ACL)}. 123 */ 124 @Deprecated 125 void addACL(String afterMe, ACL acl); 126 127 ACL removeACL(String name); 128 129 ACL getACL(String name); 130 131 ACL[] getACLs(); 132 133 ACL getMergedACLs(String name); 134 135 ACL getOrCreateACL(String name); 136 137 ACL getOrCreateACL(); 138 139 /** 140 * Returns the usernames granted to perform an operation based on a list of permissions. 141 * 142 * @deprecated Use the method from UserManager service getUsersForPermission instead 143 * @param perms the list of permissions. 144 * @return a list of usernames 145 */ 146 @Deprecated 147 String[] listUsernamesForAnyPermission(Set<String> perms); 148 149 /** 150 * Return a recursive copy of the ACP sharing no mutable substructure with the original 151 * 152 * @return a copy 153 */ 154 ACP clone(); 155 156 /** 157 * Block the inheritance on the given {@code aclName}. 158 * 159 * @param username the user blocking the inheritance 160 * @return true if the ACP was changed. 161 * @since 7.4 162 */ 163 boolean blockInheritance(String aclName, String username); 164 165 /** 166 * Unblock the inheritance on the given {@code aclName}. 167 * 168 * @return true if the ACP was changed. 169 * @since 7.4 170 */ 171 boolean unblockInheritance(String aclName); 172 173 /** 174 * Add an ACE to the given {@code aclName}. 175 * 176 * @return true if the ACP was changed. 177 * @since 7.4 178 */ 179 boolean addACE(String aclName, ACE ace); 180 181 /** 182 * Replace the {@code oldACE} with {@code newACE} on the given {@code aclName}, only if the {@code oldACE} exists. 183 * <p> 184 * The {@code newACE} keeps the same index as {@code oldACE}. 185 * 186 * @return true if the ACP was changed. 187 * @since 7.4 188 */ 189 boolean replaceACE(String aclName, ACE oldACE, ACE newACE); 190 191 /** 192 * Remove an ACE on the given {@code aclName}. 193 * 194 * @return true if the ACP was changed. 195 * @since 7.4 196 */ 197 boolean removeACE(String aclName, ACE ace); 198 199 /** 200 * Remove all ACEs for {@code username} on the given {@code aclName}. 201 * 202 * @return true if the ACP was changed. 203 * @since 7.4 204 */ 205 boolean removeACEsByUsername(String aclName, String username); 206 207 /** 208 * Remove all ACEs for {@code username} on the whole ACP. 209 * 210 * @return true if the ACP was changed. 211 * @since 7.4 212 */ 213 boolean removeACEsByUsername(String username); 214 215}