001/* 
002    Licensed to the Apache Software Foundation (ASF) under one
003    or more contributor license agreements.  See the NOTICE file
004    distributed with this work for additional information
005    regarding copyright ownership.  The ASF licenses this file
006    to you under the Apache License, Version 2.0 (the
007    "License"); you may not use this file except in compliance
008    with the License.  You may obtain a copy of the License at
009
010       http://www.apache.org/licenses/LICENSE-2.0
011
012    Unless required by applicable law or agreed to in writing,
013    software distributed under the License is distributed on an
014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015    KIND, either express or implied.  See the License for the
016    specific language governing permissions and limitations
017    under the License.  
018 */
019package org.apache.wiki.auth.permissions;
020
021import java.io.Serializable;
022import java.security.Permission;
023import java.util.Arrays;
024
025
026/**
027 * <p>
028 * Permission to perform an operation on a group in a given wiki. Permission
029 * actions include: <code>view</code>, <code>edit</code>, <code>delete</code>.
030 * </p>
031 * <p>
032 * The target of a permission is a single group or collection in a given wiki.
033 * The syntax for the target is the wiki name, followed by a colon (:) and the
034 * name of the group. &#8220;All wikis&#8221; can be specified using a wildcard (*). Group
035 * collections may also be specified using a wildcard. For groups, the wildcard
036 * may be a prefix, suffix, or all by itself. Examples of targets include:
037 * </p>
038 * <blockquote><code>*:*<br/>
039 * *:TestPlanners<br/>
040 * *:*Planners<br/>
041 * *:Test*<br/>
042 * mywiki:TestPlanners<br/>
043 * mywiki:*Planners<br/>
044 * mywiki:Test*</code>
045 * </blockquote>
046 * <p>
047 * For a given target, certain permissions imply others:
048 * </p>
049 * <ul>
050 * <li><code>edit</code>&nbsp;implies&nbsp;<code>view</code></li>
051 * <li><code>delete</code>&nbsp;implies&nbsp;<code>edit</code> and
052 * <code>view</code></li>
053 * </ul>
054 * <P>Targets that do not include a wiki prefix <em>never </em> imply others.</p>
055 * <p>
056 * GroupPermission accepts a special target called
057 * <code>&lt;groupmember&gt;</code> that means &#8220;all groups that a user is a
058 * member of.&#8221; When included in a policy file <code>grant</code> block, it
059 * functions like a wildcard. Thus, this block:
060 *
061 * <pre>
062 *  grant signedBy &quot;jspwiki&quot;,
063 *    principal org.apache.wiki.auth.authorize.Role &quot;Authenticated&quot; {
064 *      permission org.apache.wiki.auth.permissions.GroupPermission &quot;*:&lt;groupmember&gt;&quot;, &quot;edit&quot;;
065 * </pre>
066 *
067 * means, &#8220;allow Authenticated users to edit any groups they are members of.&#8221;
068 * The wildcard target (*) does <em>not</em> imply <code>&lt;groupmember&gt;</code>; it
069 * must be granted explicitly.
070 * </p>
071 * <p>
072 * A permission does not know who is asking, so it is up to the one who checks it to find out if the user is a member of the group:
073 * {@link #toMemberPermission()} gives the permission to look for in the policy then.
074 * @since 2.4.17
075 */
076public final class GroupPermission extends Permission implements Serializable
077{
078    /** Special target token that denotes all groups that a Subject's Principals are members of. */
079    public static final String         MEMBER_TOKEN     = "<groupmember>";
080
081    private static final long           serialVersionUID = 1L;
082
083    /** Action for deleting a group or collection of groups. */
084    public static final String          DELETE_ACTION    = "delete";
085
086    /** Action for editing a group or collection of groups. */
087    public static final String          EDIT_ACTION      = "edit";
088
089    /** Action for viewing a group or collection of groups. */
090    public static final String          VIEW_ACTION      = "view";
091
092    static final int          DELETE_MASK      = 0x4;
093
094    static final int          EDIT_MASK        = 0x2;
095
096    static final int          VIEW_MASK        = 0x1;
097
098    /** Convenience constant that denotes <code>GroupPermission( "*:*, "delete" )</code>. */
099    public static final GroupPermission DELETE           = new GroupPermission( DELETE_ACTION );
100
101    /** Convenience constant that denotes <code>GroupPermission( "*:*, "edit" )</code>. */
102    public static final GroupPermission EDIT             = new GroupPermission( EDIT_ACTION );
103
104    /** Convenience constant that denotes <code>GroupPermission( "*:*, "view" )</code>. */
105    public static final GroupPermission VIEW             = new GroupPermission( VIEW_ACTION );
106
107    private static final String         ACTION_SEPARATOR = ",";
108
109    private static final String         WILDCARD         = "*";
110
111    private static final String         WIKI_SEPARATOR   = ":";
112
113    private final String                m_actionString;
114
115    private final int                   m_mask;
116
117    private final String                m_group;
118
119    private final String                m_wiki;
120
121    /** For serialization purposes */
122    GroupPermission()
123    {
124        this("");
125    }
126    
127    /**
128     * Private convenience constructor that creates a new GroupPermission for
129     * all wikis and groups (*:*) and set of actions.
130     * @param actions
131     */
132    private GroupPermission(final String actions )
133    {
134        this( WILDCARD + WIKI_SEPARATOR + WILDCARD, actions );
135    }
136
137    /**
138     * Creates a new GroupPermission for a specified group and set of actions.
139     * Group should include a prepended wiki name followed by a colon (:). If
140     * the wiki name is not supplied or starts with a colon, the group refers to
141     * all wikis.
142     * @param group the wiki group
143     * @param actions the allowed actions for this group
144     */
145    public GroupPermission(final String group, final String actions )
146    {
147        super( group );
148
149        // Parse wiki and group (which may include wiki name and group)
150        // Strip out attachment separator; it is irrelevant.
151        final String[] pathParams = group.split( WIKI_SEPARATOR );
152        final String groupName;
153        if ( pathParams.length >= 2 )
154        {
155            m_wiki = !pathParams[0].isEmpty() ? pathParams[0] : null;
156            groupName = pathParams[1];
157        }
158        else
159        {
160            m_wiki = WILDCARD;
161            groupName = pathParams[0];
162        }
163        m_group = groupName;
164
165        // Parse actions
166        final String[] groupActions = actions.toLowerCase().split( ACTION_SEPARATOR );
167        Arrays.sort( groupActions, String.CASE_INSENSITIVE_ORDER );
168        m_mask = createMask( actions );
169        final StringBuilder buffer = new StringBuilder();
170        final int groupActionsLength = groupActions.length;
171        for( int i = 0; i < groupActionsLength; i++ )
172        {
173            buffer.append( groupActions[i] );
174            if ( i < ( groupActionsLength - 1 ) )
175            {
176                buffer.append( ACTION_SEPARATOR );
177            }
178        }
179        m_actionString = buffer.toString();
180    }
181
182    /**
183     * Two PagePermission objects are considered equal if their actions (after
184     * normalization), wiki and target are equal.
185     * @param obj the object to compare
186     * @return the result of the comparison
187     * @see java.lang.Object#equals(java.lang.Object)
188     */
189    public boolean equals(final Object obj )
190    {
191        if ( !( obj instanceof GroupPermission ) )
192        {
193            return false;
194        }
195        final GroupPermission p = (GroupPermission) obj;
196        return  p.m_mask == m_mask && p.m_group.equals( m_group ) && p.m_wiki != null && p.m_wiki.equals( m_wiki );
197    }
198
199    /**
200     * Returns the actions for this permission: &#8220;view&#8221;, &#8220;edit&#8221;, or &#8220;delete&#8221;. The
201     * actions will always be sorted in alphabetic order, and will always appear
202     * in lower case.
203     * @return the actions
204     * @see java.security.Permission#getActions()
205     */
206    @Override
207    public String getActions()
208    {
209        return m_actionString;
210    }
211
212    /**
213     * Returns the name of the wiki group represented by this permission.
214     * @return the page name
215     */
216    public String getGroup()
217    {
218        return m_group;
219    }
220
221    /**
222     * Returns the name of the wiki containing the group represented by this
223     * permission; may return the wildcard string.
224     * @return the wiki
225     */
226    public String getWiki()
227    {
228        return m_wiki;
229    }
230
231    /**
232     * Returns the hash code for this GroupPermission.
233     * @return the hash code
234     * @see java.lang.Object#hashCode()
235     */
236    public int hashCode()
237    {
238        // If the wiki has not been set, uses a dummy value for the hashcode
239        // calculation. This may occur if the page given does not refer
240        // to any particular wiki
241        final String wiki =  m_wiki != null ? m_wiki : "dummy_value";
242        return m_mask + ( ( 13 * m_actionString.hashCode() ) * 23 * wiki.hashCode() );
243    }
244
245    /**
246     * <p>
247     * GroupPermissions can only imply other GroupPermissions; no other
248     * permission types are implied. One GroupPermission implies another if its
249     * actions if three conditions are met:
250     * </p>
251     * <ol>
252     * <li>The other GroupPermission&#8217;s wiki is equal to, or a subset of, that
253     * of this permission. This permission&#8217;s wiki is considered a superset of
254     * the other if it contains a matching prefix plus a wildcard, or a wildcard
255     * followed by a matching suffix.</li>
256     * <li>The other GroupPermission&#8217;s target is equal to, or a subset of, the
257     * target specified by this permission. This permission&#8217;s target is
258     * considered a superset of the other if it contains a matching prefix plus
259     * a wildcard, or a wildcard followed by a matching suffix.</li>
260     * <li>All of other GroupPermission&#8217;s actions are equal to, or a subset of,
261     * those of this permission</li>
262     * </ol>
263     * @param permission the Permission to examine
264     * @return <code>true</code> if the GroupPermission implies the
265     * supplied Permission; <code>false</code> otherwise
266     * @see java.security.Permission#implies(java.security.Permission)
267     */
268    @Override
269    public boolean implies(final Permission permission )
270    {
271        // Permission must be a GroupPermission
272        if ( !( permission instanceof GroupPermission ) )
273        {
274            return false;
275        }
276
277        // Build up an "implied mask"
278        final GroupPermission p = (GroupPermission) permission;
279        final int impliedMask = impliedMask( m_mask );
280
281        // If actions aren't a proper subset, return false
282        if ( ( impliedMask & p.m_mask ) != p.m_mask )
283        {
284            return false;
285        }
286
287        // See if the tested permission's wiki is implied
288        final boolean impliedWiki = PagePermission.isSubset( m_wiki, p.m_wiki );
289
290        // If this page is "*", the tested permission's
291        // group is implied, unless implied permission has <groupmember> token
292        final boolean impliedGroup;
293        if ( MEMBER_TOKEN.equals( p.m_group ) )
294        {
295            impliedGroup = MEMBER_TOKEN.equals( m_group );
296        }
297        else
298        {
299            impliedGroup = PagePermission.isSubset( m_group, p.m_group );
300        }
301
302        return impliedWiki && impliedGroup;
303    }
304
305    /**
306     * Prints a human-readable representation of this permission.
307     * @return the string
308     * @see java.lang.Object#toString()
309     */
310    public String toString()
311    {
312        final String wiki = ( m_wiki == null ) ? "" : m_wiki;
313        return "(\"" + this.getClass().getName() + "\",\"" + wiki + WIKI_SEPARATOR + m_group + "\",\"" + getActions()
314                + "\")";
315    }
316
317    /**
318     * Creates an &#8220;implied mask&#8221; based on the actions originally assigned: for
319     * example, delete implies edit; edit implies view.
320     * @param mask binary mask for actions
321     * @return binary mask for implied actions
322     */
323    static int impliedMask( int mask )
324    {
325        if ( ( mask & DELETE_MASK ) > 0 )
326        {
327            mask |= EDIT_MASK;
328        }
329        if ( ( mask & EDIT_MASK ) > 0 )
330        {
331            mask |= VIEW_MASK;
332        }
333        return mask;
334    }
335
336    /**
337     * Protected method that creates a binary mask based on the actions specified.
338     * This is used by {@link #implies(Permission)}.
339     * @param actions the actions for this permission, separated by commas
340     * @return the binary actions mask
341     */
342    static int createMask( final String actions )
343    {
344        if ( actions == null || actions.isEmpty() )
345        {
346            throw new IllegalArgumentException( "Actions cannot be blank or null" );
347        }
348        int mask = 0;
349        final String[] actionList = actions.split( ACTION_SEPARATOR );
350        for( final String action : actionList )
351        {
352            if ( action.equalsIgnoreCase( VIEW_ACTION ) )
353            {
354                mask |= VIEW_MASK;
355            }
356            else if ( action.equalsIgnoreCase( EDIT_ACTION ) )
357            {
358                mask |= EDIT_MASK;
359            }
360            else if ( action.equalsIgnoreCase( DELETE_ACTION ) )
361            {
362                mask |= DELETE_MASK;
363            }
364            else
365            {
366                throw new IllegalArgumentException( "Unrecognized action: " + action );
367            }
368        }
369        return mask;
370    }
371
372    /**
373     * Returns the permission for the same wiki and actions whose group is the {@code <groupmember>} token, which is the one a policy
374     * grants to the members of a group. To find out if a Subject may do something to a group because it is a member of it, check
375     * that this permission, not the one of the group, is granted.
376     *
377     * @return the permission of the {@code <groupmember>} token
378     * @since 3.0.1
379     */
380    public GroupPermission toMemberPermission() {
381        return new GroupPermission( ( m_wiki == null ? "" : m_wiki ) + WIKI_SEPARATOR + MEMBER_TOKEN, m_actionString );
382    }
383
384}