View Javadoc
1 package org.apache.turbine.services.security; 2 3 /* ==================================================================== 4 * The Apache Software License, Version 1.1 5 * 6 * Copyright (c) 2001 The Apache Software Foundation. All rights 7 * reserved. 8 * 9 * Redistribution and use in source and binary forms, with or without 10 * modification, are permitted provided that the following conditions 11 * are met: 12 * 13 * 1. Redistributions of source code must retain the above copyright 14 * notice, this list of conditions and the following disclaimer. 15 * 16 * 2. Redistributions in binary form must reproduce the above copyright 17 * notice, this list of conditions and the following disclaimer in 18 * the documentation and/or other materials provided with the 19 * distribution. 20 * 21 * 3. The end-user documentation included with the redistribution, 22 * if any, must include the following acknowledgment: 23 * "This product includes software developed by the 24 * Apache Software Foundation (http://www.apache.org/)." 25 * Alternately, this acknowledgment may appear in the software itself, 26 * if and wherever such third-party acknowledgments normally appear. 27 * 28 * 4. The names "Apache" and "Apache Software Foundation" and 29 * "Apache Turbine" must not be used to endorse or promote products 30 * derived from this software without prior written permission. For 31 * written permission, please contact apache@apache.org. 32 * 33 * 5. Products derived from this software may not be called "Apache", 34 * "Apache Turbine", nor may "Apache" appear in their name, without 35 * prior written permission of the Apache Software Foundation. 36 * 37 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED 38 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 39 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 40 * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR 41 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 42 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 43 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF 44 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 45 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 46 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 47 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 48 * SUCH DAMAGE. 49 * ==================================================================== 50 * 51 * This software consists of voluntary contributions made by many 52 * individuals on behalf of the Apache Software Foundation. For more 53 * information on the Apache Software Foundation, please see 54 * <http://www.apache.org/>;. 55 */ 56 57 import org.apache.torque.util.Criteria; 58 import org.apache.turbine.om.security.Group; 59 import org.apache.turbine.om.security.Permission; 60 import org.apache.turbine.om.security.Role; 61 import org.apache.turbine.om.security.User; 62 import org.apache.turbine.services.Service; 63 import org.apache.turbine.util.security.AccessControlList; 64 import org.apache.turbine.util.security.DataBackendException; 65 import org.apache.turbine.util.security.EntityExistsException; 66 import org.apache.turbine.util.security.GroupSet; 67 import org.apache.turbine.util.security.PasswordMismatchException; 68 import org.apache.turbine.util.security.PermissionSet; 69 import org.apache.turbine.util.security.RoleSet; 70 import org.apache.turbine.util.security.UnknownEntityException; 71 72 /*** 73 * The Security Service manages Users, Groups Roles and Permissions in the 74 * system. 75 * 76 * The task performed by the security service include creation and removal of 77 * accounts, groups, roles, and permissions; assigning users roles in groups; 78 * assigning roles specific permissions and construction of objects 79 * representing these logical entities. 80 * 81 * <p> Because of pluggable nature of the Services, it is possible to create 82 * multiple implementations of SecurityService, for example employing database 83 * and directory server as the data backend.<br> 84 * 85 * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a> 86 * @version $Id: SecurityService.java,v 1.3 2002/07/11 16:53:24 mpoeschl Exp $ 87 */ 88 public interface SecurityService 89 extends Service 90 { 91 /*** The name of the service */ 92 public static final String SERVICE_NAME = "SecurityService"; 93 94 /*** the key within services's properties for user implementation classname (user.class) */ 95 public static final String USER_CLASS_KEY = "user.class"; 96 97 /*** the default implementation of User interface (org.apache.turbine.om.security.DBUser) */ 98 public static final String USER_CLASS_DEFAULT = "org.apache.turbine.om.security.TurbineUser"; 99 100 /*** the key within services's properties for user implementation classname (user.manager) */ 101 public static final String USER_MANAGER_KEY = "user.manager"; 102 103 /*** the default implementation of UserManager interface (org.apache.turbine.services.security.DBUserManager) */ 104 public static final String USER_MANAGER_DEFAULT = "org.apache.turbine.services.security.DBUserManager"; 105 106 /*** the key within services's properties for secure passwords flag (secure.passwords) */ 107 public static final String SECURE_PASSWORDS_KEY = "secure.passwords"; 108 109 /*** the value of secure passwords flag (false) */ 110 public static final String SECURE_PASSWORDS_DEFAULT = "false"; 111 112 /*** the key within services's properties for secure passwords algorithm (secure.passwords.algorithm) */ 113 public static final String SECURE_PASSWORDS_ALGORITHM_KEY = "secure.passwords.algorithm"; 114 115 /*** the default algorithm for password encryption (SHA) */ 116 public static final String SECURE_PASSWORDS_ALGORITHM_DEFAULT = "SHA"; 117 118 /*----------------------------------------------------------------------- 119 Management of User objects 120 -----------------------------------------------------------------------*/ 121 122 /*** 123 * Returns the Class object for the implementation of User interface 124 * used by the system. 125 * 126 * @return the implementation of User interface used by the system. 127 * @throws UnknownEntityException if the system's implementation of User 128 * interface could not be determined. 129 */ 130 public Class getUserClass() 131 throws UnknownEntityException; 132 133 /*** 134 * Construct a blank User object. 135 * 136 * This method calls getUserClass, and then creates a new object using 137 * the default constructor. 138 * 139 * @return an object implementing User interface. 140 * @throws UnknownEntityException if the object could not be instantiated. 141 */ 142 public User getUserInstance() 143 throws UnknownEntityException; 144 145 /*** 146 * Check whether a specified user's account exists. 147 * 148 * The login name is used for looking up the account. 149 * 150 * @param username The user to be checked. 151 * @return true if the specified account exists 152 * @throws DataBackendException if there was an error accessing the data backend. 153 */ 154 public boolean accountExists(String username) 155 throws DataBackendException; 156 157 /*** 158 * Check whether a specified user's account exists. 159 * 160 * The login name is used for looking up the account. 161 * 162 * @param user The name of the user to be checked. 163 * @return true if the specified account exists 164 * @throws DataBackendException if there was an error accessing the data backend. 165 */ 166 public boolean accountExists(User user) 167 throws DataBackendException; 168 169 /*** 170 * Authenticates an user, and constructs an User object to represent him/her. 171 * 172 * @param username The user name. 173 * @param password The user password. 174 * @return An authenticated Turbine User. 175 * @throws DataBackendException if there was an error accessing the data backend. 176 * @throws UnknownEntityException if user account is not present. 177 * @throws PasswordMismatchException if the supplied password was incorrect. 178 */ 179 public User getAuthenticatedUser(String username, String password) 180 throws DataBackendException, UnknownEntityException, PasswordMismatchException; 181 182 /*** 183 * Constructs an User object to represent a registered user of the application. 184 * 185 * @param username The user name. 186 * @return A Turbine User. 187 * @throws DataBackendException if there was an error accessing the data backend. 188 * @throws UnknownEntityException if user account is not present. 189 */ 190 public User getUser( String username ) 191 throws DataBackendException, UnknownEntityException; 192 193 /*** 194 * Retrieve a set of users that meet the specified criteria. 195 * 196 * As the keys for the criteria, you should use the constants that 197 * are defined in {@link User} interface, plus the names 198 * of the custom attributes you added to your user representation 199 * in the data storage. Use verbatim names of the attributes - 200 * without table name prefix in case of DB implementation. 201 * 202 * @param criteria The criteria of selection. 203 * @return a List of users meeting the criteria. 204 * @throws DataBackendException if there is a problem accessing the 205 * storage. 206 */ 207 public User[] getUsers( Criteria criteria ) 208 throws DataBackendException; 209 210 /*** 211 * Constructs an User object to represent an anonymous user of the application. 212 * 213 * @return An anonymous Turbine User. 214 * @throws UnknownEntityException if the anonymous User object couldn't be 215 * constructed. 216 */ 217 public User getAnonymousUser() 218 throws UnknownEntityException; 219 220 /*** 221 * Saves User's data in the permanent storage. The user account is required 222 * to exist in the storage. 223 * 224 * @exception UnknownEntityException if the user's account does not 225 * exist in the database. 226 * @exception DataBackendException if there is a problem accessing the 227 * storage. 228 */ 229 public void saveUser( User user ) 230 throws UnknownEntityException, DataBackendException; 231 232 /*----------------------------------------------------------------------- 233 Account management 234 -----------------------------------------------------------------------*/ 235 236 /*** 237 * Creates new user account with specified attributes. 238 * 239 * @param user the object describing account to be created. 240 * @throws DataBackendException if there was an error accessing the data backend. 241 * @throws EntityExistsException if the user account already exists. 242 */ 243 public void addUser( User user, String password ) 244 throws DataBackendException, EntityExistsException; 245 246 /*** 247 * Removes an user account from the system. 248 * 249 * @param user the object describing the account to be removed. 250 * @throws DataBackendException if there was an error accessing the data backend. 251 * @throws UnknownEntityException if the user account is not present. 252 */ 253 public void removeUser( User user ) 254 throws DataBackendException, UnknownEntityException; 255 256 /*----------------------------------------------------------------------- 257 Management of passwords 258 -----------------------------------------------------------------------*/ 259 260 /*** 261 * This method provides client-side encryption mechanism for passwords. 262 * 263 * This is an utility method that is used by other classes to maintain 264 * a consistent approach to encrypting password. The behavior of the 265 * method can be configured in service's properties. 266 * 267 * @param password the password to process 268 * @return processed password 269 */ 270 public String encryptPassword( String password ); 271 272 /*** 273 * Change the password for an User. 274 * 275 * @param user an User to change password for. 276 * @param oldPassword the current password supplied by the user. 277 * @param newPassword the current password requested by the user. 278 * @exception PasswordMismatchException if the supplied password was 279 * incorrect. 280 * @exception UnknownEntityException if the user's record does not 281 * exist in the database. 282 * @exception DataBackendException if there is a problem accessing the 283 * storage. 284 */ 285 public void changePassword( User user, String oldPassword, String newPassword ) 286 throws PasswordMismatchException, UnknownEntityException, 287 DataBackendException; 288 289 /*** 290 * Forcibly sets new password for an User. 291 * 292 * This is supposed by the administrator to change the forgotten or 293 * compromised passwords. Certain implementatations of this feature 294 * would require administrative level access to the authenticating 295 * server / program. 296 * 297 * @param user an User to change password for. 298 * @param password the new password. 299 * @exception UnknownEntityException if the user's record does not 300 * exist in the database. 301 * @exception DataBackendException if there is a problem accessing the 302 * storage. 303 */ 304 public void forcePassword( User user, String password ) 305 throws UnknownEntityException, DataBackendException; 306 307 /*----------------------------------------------------------------------- 308 Retrieval of security information 309 -----------------------------------------------------------------------*/ 310 311 /*** 312 * Constructs an AccessControlList for a specific user. 313 * 314 * @param user the user for whom the AccessControlList are to be retrieved 315 * @throws DataBackendException if there was an error accessing the data backend. 316 * @throws UnknownEntityException if user account is not present. 317 */ 318 public AccessControlList getACL( User user ) 319 throws DataBackendException, UnknownEntityException; 320 321 /*** 322 * Retrieves all permissions associated with a role. 323 * 324 * @param role the role name, for which the permissions are to be retrieved. 325 * @throws DataBackendException if there was an error accessing the data backend. 326 * @throws UnknownEntityException if the role is not present. 327 */ 328 public PermissionSet getPermissions( Role role ) 329 throws DataBackendException, UnknownEntityException; 330 331 /*----------------------------------------------------------------------- 332 Manipulation of security information 333 -----------------------------------------------------------------------*/ 334 335 /*** 336 * Grant an User a Role in a Group. 337 * 338 * @param user the user. 339 * @param group the group. 340 * @param role the role. 341 * @throws DataBackendException if there was an error accessing the data backend. 342 * @throws UnknownEntityException if user account, group or role is not present. 343 */ 344 public void grant(User user, Group group, Role role) 345 throws DataBackendException, UnknownEntityException; 346 347 /*** 348 * Revoke a Role in a Group from an User. 349 * 350 * @param user the user. 351 * @param group the group. 352 * @param role the role. 353 * @throws DataBackendException if there was an error accessing the data backend. 354 * @throws UnknownEntityException if user account, group or role is not present. 355 */ 356 public void revoke(User user, Group group, Role role) 357 throws DataBackendException, UnknownEntityException; 358 359 /*** 360 * Revokes all roles from an User. 361 * 362 * This method is used when deleting an account. 363 * 364 * @param user the User. 365 * @throws DataBackendException if there was an error accessing the data backend. 366 * @throws UnknownEntityException if the account is not present. 367 */ 368 public void revokeAll( User user ) 369 throws DataBackendException, UnknownEntityException; 370 371 /*** 372 * Grants a Role a Permission 373 * 374 * @param role the Role. 375 * @param permission the Permission. 376 * @throws DataBackendException if there was an error accessing the data backend. 377 * @throws UnknownEntityException if role or permission is not present. 378 */ 379 public void grant( Role role, Permission permission ) 380 throws DataBackendException, UnknownEntityException; 381 382 /*** 383 * Revokes a Permission from a Role. 384 * 385 * @param role the Role. 386 * @param permission the Permission. 387 * @throws DataBackendException if there was an error accessing the data backend. 388 * @throws UnknownEntityException if role or permission is not present. 389 */ 390 public void revoke( Role role, Permission permission ) 391 throws DataBackendException, UnknownEntityException; 392 393 /*** 394 * Revokes all permissions from a Role. 395 * 396 * This method is user when deleting a Role. 397 * 398 * @param role the Role 399 * @throws DataBackendException if there was an error accessing the data backend. 400 * @throws UnknownEntityException if the Role is not present. 401 */ 402 public void revokeAll( Role role ) 403 throws DataBackendException, UnknownEntityException; 404 405 /*----------------------------------------------------------------------- 406 Retrieval & storage of SecurityObjects 407 -----------------------------------------------------------------------*/ 408 409 /*** 410 * Provides a reference to the Group object that represents the 411 * <a href="#global">global group</a>. 412 * 413 * @return a Group object that represents the global group. 414 */ 415 public Group getGlobalGroup(); 416 417 /*** 418 * Retrieves a new Group. It creates 419 * a new Group based on the Services Group implementation. It does not 420 * create a new Group in the system though. Use addGroup for that. 421 * 422 * @param groupName The name of the Group to be retrieved. 423 */ 424 public Group getNewGroup( String groupName ); 425 426 /*** 427 * Retrieves a new Role. It creates 428 * a new Group based on the Services Role implementation. It does not 429 * create a new Role in the system though. Use addRole for that. 430 * 431 * @param roleName The name of the Role to be retrieved. 432 */ 433 public Role getNewRole( String roleName ); 434 435 /*** 436 * Retrieves a new Permission. It creates 437 * a new Permission based on the Services Permission implementation. It does not 438 * create a new Permission in the system though. Use addPermission for that. 439 * 440 * @param permissionName The name of the Permission to be retrieved. 441 */ 442 public Permission getNewPermission( String permissionName ); 443 444 /*** 445 * Retrieve a Group object with specified name. 446 * 447 * @param name the name of the Group. 448 * @return an object representing the Group with specified name. 449 */ 450 public Group getGroup( String name ) 451 throws DataBackendException, UnknownEntityException; 452 453 /*** 454 * Retrieve a Role object with specified name. 455 * 456 * @param name the name of the Role. 457 * @return an object representing the Role with specified name. 458 */ 459 public Role getRole( String name ) 460 throws DataBackendException, UnknownEntityException; 461 462 /*** 463 * Retrieve a Permission object with specified name. 464 * 465 * @param name the name of the Permission. 466 * @return an object representing the Permission with specified name. 467 */ 468 public Permission getPermission( String name ) 469 throws DataBackendException, UnknownEntityException; 470 471 /*** 472 * Retrieve a set of Groups that meet the specified Criteria. 473 * 474 * @param criteria of Group selection. 475 * @return a set of Groups that meet the specified Criteria. 476 */ 477 public GroupSet getGroups(Criteria criteria) 478 throws DataBackendException; 479 480 /*** 481 * Retrieve a set of Roles that meet the specified Criteria. 482 * 483 * @param criteria of Roles selection. 484 * @return a set of Roles that meet the specified Criteria. 485 */ 486 public RoleSet getRoles(Criteria criteria) 487 throws DataBackendException; 488 489 /*** 490 * Retrieve a set of Permissions that meet the specified Criteria. 491 * 492 * @param criteria of Permissions selection. 493 * @return a set of Permissions that meet the specified Criteria. 494 */ 495 public PermissionSet getPermissions(Criteria criteria) 496 throws DataBackendException; 497 498 /*** 499 * Retrieves all groups defined in the system. 500 * 501 * @return the names of all groups defined in the system. 502 * @throws DataBackendException if there was an error accessing the data backend. 503 */ 504 public GroupSet getAllGroups() 505 throws DataBackendException; 506 507 /*** 508 * Retrieves all roles defined in the system. 509 * 510 * @return the names of all roles defined in the system. 511 * @throws DataBackendException if there was an error accessing the data backend. 512 */ 513 public RoleSet getAllRoles() 514 throws DataBackendException; 515 516 /*** 517 * Retrieves all permissions defined in the system. 518 * 519 * @return the names of all roles defined in the system. 520 * @throws DataBackendException if there was an error accessing the data backend. 521 */ 522 public PermissionSet getAllPermissions() 523 throws DataBackendException; 524 /*** 525 * Stores Group's attributes. The Groups is required to exist in the system. 526 * 527 * @param group The Group to be stored. 528 * @throws DataBackendException if there was an error accessing the data backend. 529 * @throws UnknownEntityException if the group does not exist. 530 */ 531 public void saveGroup(Group group) 532 throws DataBackendException, UnknownEntityException; 533 534 /*** 535 * Stores Role's attributes. The Roles is required to exist in the system. 536 * 537 * @param role The Role to be stored. 538 * @throws DataBackendException if there was an error accessing the data backend. 539 * @throws UnknownEntityException if the role does not exist. 540 */ 541 public void saveRole(Role role) 542 throws DataBackendException, UnknownEntityException; 543 544 /*** 545 * Stores Permission's attributes. The Permissions is required to exist in the system. 546 * 547 * @param permission The Permission to be stored. 548 * @throws DataBackendException if there was an error accessing the data backend. 549 * @throws UnknownEntityException if the permission does not exist. 550 */ 551 public void savePermission(Permission permission) 552 throws DataBackendException, UnknownEntityException; 553 554 /*----------------------------------------------------------------------- 555 Group/Role/Permission management 556 -----------------------------------------------------------------------*/ 557 558 /*** 559 * Creates a new group with specified attributes. 560 * 561 * @param group the object describing the group to be created. 562 * @return the new Group object. 563 * @throws DataBackendException if there was an error accessing the data backend. 564 * @throws EntityExistsException if the group already exists. 565 */ 566 public Group addGroup(Group group) 567 throws DataBackendException, EntityExistsException; 568 569 /*** 570 * Creates a new role with specified attributes. 571 * 572 * @param role the objects describing the group to be created. 573 * @return the new Role object. 574 * @throws DataBackendException if there was an error accessing the data backend. 575 * @throws EntityExistsException if the role already exists. 576 */ 577 public Role addRole(Role role) 578 throws DataBackendException, EntityExistsException; 579 580 /*** 581 * Creates a new permission with specified attributes. 582 * 583 * @param permission the objects describing the group to be created. 584 * @return the new Permission object. 585 * @throws DataBackendException if there was an error accessing the data backend. 586 * @throws EntityExistsException if the permission already exists. 587 */ 588 public Permission addPermission(Permission permission) 589 throws DataBackendException, EntityExistsException; 590 591 /*** 592 * Removes a Group from the system. 593 * 594 * @param group the object describing group to be removed. 595 * @throws DataBackendException if there was an error accessing the data backend. 596 * @throws UnknownEntityException if the group does not exist. 597 */ 598 public void removeGroup(Group group) 599 throws DataBackendException, UnknownEntityException; 600 601 /*** 602 * Removes a Role from the system. 603 * 604 * @param role the object describing role to be removed. 605 * @throws DataBackendException if there was an error accessing the data backend. 606 * @throws UnknownEntityException if the role does not exist. 607 */ 608 public void removeRole(Role role) 609 throws DataBackendException, UnknownEntityException; 610 611 /*** 612 * Removes a Permission from the system. 613 * 614 * @param permission the object describing permission to be removed. 615 * @throws DataBackendException if there was an error accessing the data backend. 616 * @throws UnknownEntityException if the permission does not exist. 617 */ 618 public void removePermission(Permission permission) 619 throws DataBackendException, UnknownEntityException; 620 621 /*** 622 * Renames an existing Group. 623 * 624 * @param group the object describing the group to be renamed. 625 * @param name the new name for the group. 626 * @throws DataBackendException if there was an error accessing the data backend. 627 * @throws UnknownEntityException if the group does not exist. 628 */ 629 public void renameGroup(Group group, String name) 630 throws DataBackendException, UnknownEntityException; 631 632 /*** 633 * Renames an existing Role. 634 * 635 * @param role the object describing the role to be renamed. 636 * @param name the new name for the role. 637 * @throws DataBackendException if there was an error accessing the data backend. 638 * @throws UnknownEntityException if the role does not exist. 639 */ 640 public void renameRole(Role role, String name) 641 throws DataBackendException, UnknownEntityException; 642 643 /*** 644 * Renames an existing Permission. 645 * 646 * @param permission the object describing the permission to be renamed. 647 * @param name the new name for the permission. 648 * @throws DataBackendException if there was an error accessing the data backend. 649 * @throws UnknownEntityException if the permission does not exist. 650 */ 651 public void renamePermission(Permission permission, String name) 652 throws DataBackendException, UnknownEntityException; 653 }

This page was automatically generated by Maven