001/*
002 * (C) Copyright 2006-2019 Nuxeo (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 *     Anahide Tchertchian
018 *     Florent Guillaume
019 */
020
021package org.nuxeo.ecm.core.security;
022
023import org.nuxeo.ecm.core.api.NuxeoPrincipal;
024import org.nuxeo.ecm.core.api.security.ACP;
025import org.nuxeo.ecm.core.api.security.Access;
026import org.nuxeo.ecm.core.model.Document;
027import org.nuxeo.ecm.core.query.sql.model.SQLQuery.Transformer;
028
029/**
030 * Interface for pluggable core security policy.
031 *
032 * @author Anahide Tchertchian
033 * @author Florent Guillaume
034 */
035public interface SecurityPolicy {
036
037    /**
038     * Checks given permission for doc and principal.
039     * <p>
040     * Note that for the {@code Browse} permission, which is also implemented in SQL using {@link #getQueryTransformer},
041     * a security policy must never bypass standard ACL access, it must only return DENY or UNKNOWN. Failing to do this
042     * would make direct access and queries behave differently.
043     *
044     * @param doc the document to check
045     * @param mergedAcp merged ACP resolved for this document
046     * @param principal principal to check
047     * @param permission permission to check
048     * @param resolvedPermissions permissions or groups of permissions containing permission
049     * @return access: GRANT, DENY, or UNKNOWN. When UNKNOWN is returned, following policies or default core security
050     *         are applied.
051     */
052    Access checkPermission(Document doc, ACP mergedAcp, NuxeoPrincipal principal, String permission,
053            String[] resolvedPermissions, String[] additionalPrincipals);
054
055    /**
056     * Checks if this policy is restricting the given permission.
057     * <p>
058     * Queries check the BROWSE permission.
059     *
060     * @param permission the permission to check for
061     * @return {@code true} if the policy restricts the permission
062     */
063    boolean isRestrictingPermission(String permission);
064
065    /**
066     * Checks if this policy can be expressed in a query for given repository.
067     * <p>
068     * If not, then any query made will have to be post-filtered.
069     *
070     * @param repositoryName the target repository name.
071     * @return {@code true} if the policy can be expressed in a query
072     */
073    boolean isExpressibleInQuery(String repositoryName);
074
075    /**
076     * Checks if this policy can be expressed in a string-based query for given repository.
077     * <p>
078     * If not, then any query made will have to be post-filtered, if possible, otherwise denied.
079     *
080     * @param repositoryName the target repository name.
081     * @return {@code true} if the policy can be expressed in a string-based query
082     * @since 5.7.2
083     */
084    boolean isExpressibleInQuery(String repositoryName, String queryLanguage);
085
086    /**
087     * Get the transformer to use to apply this policy to a query.
088     * <p>
089     * Called only when {@link #isExpressibleInQuery(String)} returned {@code true}
090     *
091     * @param repositoryName the target repository name.
092     * @return the transformer
093     */
094    Transformer getQueryTransformer(String repositoryName);
095
096    /**
097     * Get the string-based transformer to use to apply this policy to a query.
098     * <p>
099     * Called only when {@link #isExpressibleInQuery(String, String)} returned {@code true}
100     *
101     * @param repositoryName the target repository name.
102     * @return the transformer
103     * @since 5.7.2
104     */
105    QueryTransformer getQueryTransformer(String repositoryName, String queryLanguage);
106
107    /**
108     * Interface for a class that can transform a string-based query into another. Not used for NXQL.
109     *
110     * @since 5.7.2
111     */
112    interface QueryTransformer {
113
114        /**
115         * Query transformer that does nothing.
116         */
117        QueryTransformer IDENTITY = new IdentityQueryTransformer();
118
119        /**
120         * Transforms a query into another query that has the security policy applied.
121         *
122         * @param principal the principal making the query
123         * @param query the query
124         * @return the query with security policy applied
125         * @since 5.7.2
126         */
127        String transform(NuxeoPrincipal principal, String query);
128    }
129
130    /**
131     * Query transformer that does nothing. Use {@link QueryTransformer#IDENTITY} instead of instantiating this class.
132     *
133     * @since 5.7.2
134     */
135    class IdentityQueryTransformer implements QueryTransformer {
136        @Override
137        public String transform(NuxeoPrincipal principal, String query) {
138            return query;
139        }
140    }
141
142}