1. /*

  2.  * @(#)Acl.java	1.23 04/05/05

  3.  *

  4.  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package java.security.acl;

  9. 

  10. import java.util.Enumeration;

  11. import java.security.Principal;

  12. 

  13. /**

  14.  * Interface representing an Access Control List (ACL).  An Access

  15.  * Control List is a data structure used to guard access to

  16.  * resources.<p>

  17.  *

  18.  * An ACL can be thought of as a data structure with multiple ACL

  19.  * entries.  Each ACL entry, of interface type AclEntry, contains a

  20.  * set of permissions associated with a particular principal. (A

  21.  * principal represents an entity such as an individual user or a

  22.  * group). Additionally, each ACL entry is specified as being either

  23.  * positive or negative. If positive, the permissions are to be

  24.  * granted to the associated principal. If negative, the permissions

  25.  * are to be denied.<p>

  26.  *

  27.  * The ACL Entries in each ACL observe the following rules:<p>

  28.  *

  29.  * <ul> <li>Each principal can have at most one positive ACL entry and

  30.  * one negative entry; that is, multiple positive or negative ACL

  31.  * entries are not allowed for any principal.  Each entry specifies

  32.  * the set of permissions that are to be granted (if positive) or

  33.  * denied (if negative). <p>

  34.  * 

  35.  * <li>If there is no entry for a particular principal, then the

  36.  * principal is considered to have a null (empty) permission set.<p>

  37.  *

  38.  * <li>If there is a positive entry that grants a principal a

  39.  * particular permission, and a negative entry that denies the

  40.  * principal the same permission, the result is as though the

  41.  * permission was never granted or denied. <p>

  42.  *

  43.  * <li>Individual permissions always override permissions of the

  44.  * group(s) to which the individual belongs. That is, individual

  45.  * negative permissions (specific denial of permissions) override the

  46.  * groups' positive permissions. And individual positive permissions

  47.  * override the groups' negative permissions.<p>

  48.  *

  49.  * </ul>

  50.  *

  51.  * The <code> java.security.acl </code> package provides the

  52.  * interfaces to the ACL and related data structures (ACL entries,

  53.  * groups, permissions, etc.), and the <code> sun.security.acl </code>

  54.  * classes provide a default implementation of the interfaces. For

  55.  * example, <code> java.security.acl.Acl </code> provides the

  56.  * interface to an ACL and the <code> sun.security.acl.AclImpl </code>

  57.  * class provides the default implementation of the interface.<p>

  58.  * 

  59.  * The <code> java.security.acl.Acl </code> interface extends the

  60.  * <code> java.security.acl.Owner </code> interface. The Owner

  61.  * interface is used to maintain a list of owners for each ACL.  Only

  62.  * owners are allowed to modify an ACL. For example, only an owner can

  63.  * call the ACL's <code>addEntry</code> method to add a new ACL entry 

  64.  * to the ACL.

  65.  * 

  66.  * @see java.security.acl.AclEntry

  67.  * @see java.security.acl.Owner

  68.  * @see java.security.acl.Acl#getPermissions

  69.  * 

  70.  * @version 1.23, 04/05/05

  71.  * @author Satish Dharmaraj 

  72.  */

  73. 

  74. public interface Acl extends Owner {

  75. 

  76.     /**

  77.      * Sets the name of this ACL.

  78.      *

  79.      * @param caller the principal invoking this method. It must be an

  80.      * owner of this ACL.

  81.      *

  82.      * @param name the name to be given to this ACL.

  83.      *

  84.      * @exception NotOwnerException if the caller principal

  85.      * is not an owner of this ACL.  

  86.      *

  87.      * @see #getName

  88.      */

  89.     public void setName(Principal caller, String name)

  90.       throws NotOwnerException;

  91. 

  92.     /**

  93.      * Returns the name of this ACL. 

  94.      *

  95.      * @return the name of this ACL.

  96.      *

  97.      * @see #setName

  98.      */

  99.     public String getName();

  100. 

  101.     /**

  102.      * Adds an ACL entry to this ACL. An entry associates a principal

  103.      * (e.g., an individual or a group) with a set of

  104.      * permissions. Each principal can have at most one positive ACL

  105.      * entry (specifying permissions to be granted to the principal)

  106.      * and one negative ACL entry (specifying permissions to be

  107.      * denied). If there is already an ACL entry of the same type

  108.      * (negative or positive) already in the ACL, false is returned.

  109.      * 

  110.      * @param caller the principal invoking this method. It must be an

  111.      * owner of this ACL.

  112.      *

  113.      * @param entry the ACL entry to be added to this ACL.

  114.      *

  115.      * @return true on success, false if an entry of the same type

  116.      * (positive or negative) for the same principal is already

  117.      * present in this ACL.

  118.      *

  119.      * @exception NotOwnerException if the caller principal

  120.      *  is not an owner of this ACL.  

  121.      */

  122.     public boolean addEntry(Principal caller, AclEntry entry)

  123.       throws NotOwnerException;

  124. 

  125.     /**

  126.      * Removes an ACL entry from this ACL.

  127.      * 

  128.      * @param caller the principal invoking this method. It must be an

  129.      * owner of this ACL.

  130.      *  

  131.      * @param entry the ACL entry to be removed from this ACL.

  132.      * 

  133.      * @return true on success, false if the entry is not part of this ACL.

  134.      * 

  135.      * @exception NotOwnerException if the caller principal is not

  136.      * an owner of this Acl.

  137.      */

  138.     public boolean removeEntry(Principal caller, AclEntry entry)

  139.           throws NotOwnerException;

  140. 

  141.     /**

  142.      * Returns an enumeration for the set of allowed permissions for the 

  143.      * specified principal (representing an entity such as an individual or 

  144.      * a group). This set of allowed permissions is calculated as

  145.      * follows:<p>

  146.      *

  147.      * <ul>

  148.      *  

  149.      * <li>If there is no entry in this Access Control List for the 

  150.      * specified principal, an empty permission set is returned.<p>

  151.      * 

  152.      * <li>Otherwise, the principal's group permission sets are determined.

  153.      * (A principal can belong to one or more groups, where a group is a 

  154.      * group of principals, represented by the Group interface.)

  155.      * The group positive permission set is the union of all 

  156.      * the positive permissions of each group that the principal belongs to.

  157.      * The group negative permission set is the union of all 

  158.      * the negative permissions of each group that the principal belongs to.

  159.      * If there is a specific permission that occurs in both 

  160.      * the positive permission set and the negative permission set, 

  161.      * it is removed from both.<p>

  162.      *

  163.      * The individual positive and negative permission sets are also 

  164.      * determined. The positive permission set contains the permissions 

  165.      * specified in the positive ACL entry (if any) for the principal. 

  166.      * Similarly, the negative permission set contains the permissions

  167.      * specified in the negative ACL entry (if any) for the principal. 

  168.      * The individual positive (or negative) permission set is considered 

  169.      * to be null if there is not a positive (negative) ACL entry for the

  170.      * principal in this ACL.<p>

  171.      *

  172.      * The set of permissions granted to the principal is then calculated 

  173.      * using the simple rule that individual permissions always override 

  174.      * the group permissions. That is, the principal's individual negative

  175.      * permission set (specific denial of permissions) overrides the group 

  176.      * positive permission set, and the principal's individual positive 

  177.      * permission set overrides the group negative permission set. 

  178.      * 

  179.      * </ul>

  180.      *

  181.      * @param user the principal whose permission set is to be returned.

  182.      * 

  183.      * @return the permission set specifying the permissions the principal 

  184.      * is allowed. 

  185.      */

  186.     public Enumeration<Permission> getPermissions(Principal user);

  187. 

  188.     /**

  189.      * Returns an enumeration of the entries in this ACL. Each element in 

  190.      * the enumeration is of type AclEntry.

  191.      * 

  192.      * @return an enumeration of the entries in this ACL.

  193.      */

  194.     public Enumeration<AclEntry> entries();

  195. 

  196.     /**

  197.      * Checks whether or not the specified principal has the specified 

  198.      * permission. If it does, true is returned, otherwise false is returned.

  199.      * 

  200.      * More specifically, this method checks whether the passed permission

  201.      * is a member of the allowed permission set of the specified principal.

  202.      * The allowed permission set is determined by the same algorithm as is 

  203.      * used by the <code>getPermissions</code> method.

  204.      * 

  205.      * @param principal the principal, assumed to be a valid authenticated 

  206.      * Principal.

  207.      * 

  208.      * @param permission the permission to be checked for.

  209.      * 

  210.      * @return true if the principal has the specified permission, false 

  211.      * otherwise.

  212.      * 

  213.      * @see #getPermissions

  214.      */

  215.     public boolean checkPermission(Principal principal, Permission permission);

  216. 

  217.     /**

  218.      * Returns a string representation of the 

  219.      * ACL contents.

  220.      * 

  221.      * @return a string representation of the ACL contents.

  222.      */

  223.     public String toString();

  224. }

  225. 

  226. 

  227. 

  228. 

  229. 

  230. 

  231. 

  232. 

  233. 

  234. 

  235. 

  236. 

  237. 

  238. 

  239. 

  240.