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}