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