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