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