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. “All wikis” 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> implies <code>view</code></li> 051 * <li><code>delete</code> implies <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><groupmember></code> that means “all groups that a user is a 058 * member of.” 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 "jspwiki", 063 * principal org.apache.wiki.auth.authorize.Role "Authenticated" { 064 * permission org.apache.wiki.auth.permissions.GroupPermission "*:<groupmember>", "edit"; 065 * </pre> 066 * 067 * means, “allow Authenticated users to edit any groups they are members of.” 068 * The wildcard target (*) does <em>not</em> imply <code><groupmember></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: “view”, “edit”, or “delete”. 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’s wiki is equal to, or a subset of, that 253 * of this permission. This permission’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’s target is equal to, or a subset of, the 257 * target specified by this permission. This permission’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’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 “implied mask” 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}