1. /*

  2.  * @(#)Acl.java	1.17 01/11/29

  3.  *

  4.  * Copyright 2002 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.17, 01/11/29

  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.     public void setName(Principal caller, String name)

  88.       throws NotOwnerException;

  89. 

  90.     /**

  91.      * Returns the name of this ACL. 

  92.      *

  93.      * @return the name of this ACL.

  94.      */

  95.     public String getName();

  96. 

  97.     /**

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

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

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

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

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

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

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

  105.      * 

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

  107.      * owner of this ACL.

  108.      *

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

  110.      *

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

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

  113.      * present in this ACL.

  114.      *

  115.      * @exception NotOwnerException if the caller principal

  116.      *  is not an owner of this ACL.  

  117.      */

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

  119.       throws NotOwnerException;

  120. 

  121.     /**

  122.      * Removes an ACL entry from this ACL.

  123.      * 

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

  125.      * owner of this ACL.

  126.      *  

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

  128.      * 

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

  130.      * 

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

  132.      * an owner of this Acl.

  133.      */

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

  135.           throws NotOwnerException;

  136. 

  137.     /**

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

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

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

  141.      * follows:<p>

  142.      *

  143.      * <ul>

  144.      *  

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

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

  147.      * 

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

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

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

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

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

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

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

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

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

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

  158.      *

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

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

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

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

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

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

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

  166.      * principal in this ACL.<p>

  167.      *

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

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

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

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

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

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

  174.      * 

  175.      * </ul>

  176.      *

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

  178.      * 

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

  180.      * is allowed. 

  181.      */

  182.     public Enumeration getPermissions(Principal user);

  183. 

  184.     /**

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

  186.      * the enumeration is of type AclEntry.

  187.      * 

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

  189.      */

  190.     public Enumeration entries();

  191. 

  192.     /**

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

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

  195.      * 

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

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

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

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

  200.      * 

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

  202.      * Principal.

  203.      * 

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

  205.      * 

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

  207.      * otherwise.

  208.      * 

  209.      * @see #getPermissions

  210.      */

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

  212. 

  213.     /**

  214.      * Returns a string representation of the 

  215.      * ACL contents.

  216.      * 

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

  218.      */

  219.     public String toString();

  220. }

  221. 

  222. 

  223. 

  224. 

  225. 

  226. 

  227. 

  228. 

  229. 

  230. 

  231. 

  232. 

  233. 

  234. 

  235. 

  236.