1. /*

  2.  * @(#)Acl.java	1.18 00/02/02

  3.  *

  4.  * Copyright 1996-2000 Sun Microsystems, Inc. All Rights Reserved.

  5.  * 

  6.  * This software is the proprietary information of Sun Microsystems, Inc.  

  7.  * Use is subject to license terms.

  8.  * 

  9.  */

  10. 

  11. package java.security.acl;

  12. 

  13. import java.util.Enumeration;

  14. import java.security.Principal;

  15. 

  16. /**

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

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

  19.  * resources.<p>

  20.  *

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

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

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

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

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

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

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

  28.  * are to be denied.<p>

  29.  *

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

  31.  *

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

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

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

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

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

  37.  * 

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

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

  40.  *

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

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

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

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

  45.  *

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

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

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

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

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

  51.  *

  52.  * </ul>

  53.  *

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

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

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

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

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

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

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

  61.  * 

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

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

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

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

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

  67.  * to the ACL.

  68.  * 

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

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

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

  72.  * 

  73.  * @version 1.18, 00/02/02

  74.  * @author Satish Dharmaraj 

  75.  */

  76. 

  77. public interface Acl extends Owner {

  78. 

  79.     /**

  80.      * Sets the name of this ACL.

  81.      *

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

  83.      * owner of this ACL.

  84.      *

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

  86.      *

  87.      * @exception NotOwnerException if the caller principal

  88.      * is not an owner of this ACL.  

  89.      */

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

  91.       throws NotOwnerException;

  92. 

  93.     /**

  94.      * Returns the name of this ACL. 

  95.      *

  96.      * @return the name of this ACL.

  97.      */

  98.     public String getName();

  99. 

  100.     /**

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

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

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

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

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

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

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

  108.      * 

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

  110.      * owner of this ACL.

  111.      *

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

  113.      *

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

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

  116.      * present in this ACL.

  117.      *

  118.      * @exception NotOwnerException if the caller principal

  119.      *  is not an owner of this ACL.  

  120.      */

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

  122.       throws NotOwnerException;

  123. 

  124.     /**

  125.      * Removes an ACL entry from this ACL.

  126.      * 

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

  128.      * owner of this ACL.

  129.      *  

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

  131.      * 

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

  133.      * 

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

  135.      * an owner of this Acl.

  136.      */

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

  138.           throws NotOwnerException;

  139. 

  140.     /**

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

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

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

  144.      * follows:<p>

  145.      *

  146.      * <ul>

  147.      *  

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

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

  150.      * 

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

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

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

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

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

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

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

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

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

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

  161.      *

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

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

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

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

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

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

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

  169.      * principal in this ACL.<p>

  170.      *

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

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

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

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

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

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

  177.      * 

  178.      * </ul>

  179.      *

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

  181.      * 

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

  183.      * is allowed. 

  184.      */

  185.     public Enumeration getPermissions(Principal user);

  186. 

  187.     /**

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

  189.      * the enumeration is of type AclEntry.

  190.      * 

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

  192.      */

  193.     public Enumeration entries();

  194. 

  195.     /**

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

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

  198.      * 

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

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

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

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

  203.      * 

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

  205.      * Principal.

  206.      * 

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

  208.      * 

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

  210.      * otherwise.

  211.      * 

  212.      * @see #getPermissions

  213.      */

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

  215. 

  216.     /**

  217.      * Returns a string representation of the 

  218.      * ACL contents.

  219.      * 

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

  221.      */

  222.     public String toString();

  223. }

  224. 

  225. 

  226. 

  227. 

  228. 

  229. 

  230. 

  231. 

  232. 

  233. 

  234. 

  235. 

  236. 

  237. 

  238. 

  239.