Java Server

Access Control Lists (Beta)


Introduction / ACL Structure / Calculating Permissions / Example Permissions / Example Usage

Introduction

An Access Control List (ACL) is a data structure that guards access to resources. The java.security.acl package provides the interface to such a data structure and the sun.security.acl data structure provides a default implementation of the interfaces specified in the java.security.acl package. An ACL can be thought of as a data structure with multiple ACL entries. Each ACL entry is a set of permissions associated with a particular principal or group. Additionally, each ACL has a sign that indicates whether or not the permissions are to be granted or denied. An access control list is independent of the authentication scheme used to verify the validity of the principal. It is also independent of the encryption scheme used to transmit the data across the network. The ACL is consulted after the authentication phase. After the principal is verified to be an authenticated user in the system, the principal might access resources. For each such resource, the principal might or might not be granted access depending on the permissions that is granted to the principal in the ACL that guards the resource. The ACL itself is independent of the resource that it guards. The ACL can be consulted to find the list of permissions a particular principal has or to find out whether or not a principal is granted a particular permission.

ACL Structure

An ACL is an object that implements the java.security.acl.Acl interface. Each Acl is a list of AclEntry objects. Each AclEntry associates a Principal or a Group object to a list of Permission objects. Each AclEntry can also be designated as a positive entry or a negative entry. A positive entry grants the list of permissions in the entry to the principal or group and a negative entry denies the list of permissions to the principal or group.

Calculating Permissions

When calculating the net permissions a principal is granted, the following rules are used.
  1. Each principal or group can have one positive entry and one negative entry. That is to say, duplicate acl entries are not allowed.
  2. If there is no entry for a particular principal or a group, then this means that the principal or the group has the null permission set.
  3. The net group positive permission set for an principal is the union of all the positive permissions of each group that the principal belongs to.
  4. The net group negative permission set for an principal is the union of all the negative permissions of each group that the principal belongs to.
  5. If there is a positive entry that grants a principal or a group a particular permission and a negative entry that denies the principal or group the same permission, then that permission is removed from both the positive permissions set and the negative permissions set.
  6. Individual permissions (permissions granted or denied to a specific principal) always override the Group permissions. Specifically, individual negative permissions (specific denial of permissions) override the groups positive permissions. And individual positive permissions override the groups negative permissions.
  7. Assume that the positive permission set of all the groups that the principal belongs to is g1 and the negative permission set of all the groups that the principal belongs to is g2. Also assume that the the individual positive permission set for the principal is p1 and the individual negative permission set for the principal is p2. Then the resulting permissions that the principal is granted is (p1 + (g1 - p2)) - (p2 + (g2 - p1)).

Example Permissions

Assume that a principal P belongs to groups G1 and G2. The table below shows 5 columns using some examples of permissions given to G1, G2 and P. The resulting permissions granted to P is shown in the last column.
Group G1 Permissions Group G2 Permissions Union (G1, G2) perms Individual Permissions Resulting Permissions
Positive A B A+B C A+B+C
Negative null set null set null set null set






Positive A B B C B+C
Negative -C -A -C null set






Positive A B A+B C B+C
Negative null set null set null set -A






Positive A C A B B
Negative -C -B -B -A

Example Usage


import java.security.acl.*; 
import sun.security.acl.*; 

public class Example { 
    Principal p1 = new PrincipalImpl("user1"); 
    Principal p2 = new PrincipalImpl("user2"); 
    Principal owner = new PrincipalImpl("owner"); 
 
    Permission read = new PermissionImpl("READ"); 
    Permission write = new PermissionImpl("WRITE"); 
 
    Group g = new GroupImpl("group1"); 
    g.addMember(p1); 
    g.addMember(p2); 
 
    // 
    // create a new acl with the name "exampleAcl" 
    // 
    Acl acl = new AclImpl(owner, "exampleAcl"); 
 
    // 
    // Allow group all permissions 
    // 
    AclEntry entry1 = new AclEntryImpl(g); 
    entry1.addPermission(read); 
    entry1.addPermission(write); 
    acl.addEntry(owner, entry1); 
 
    // 
    // Take away WRITE permissions for  
    // user1. All others in groups still have 
    // WRITE privileges. 
    // 
    AclEntry entry2 = new AclEntryImpl(p1); 
    entry2.addPermission(write); 
    entry2.setNegativePermissions(); 
    acl.addEntry(owner, entry2);	 
 
    // 
    // This enumeration is an enumeration of  
    // Permission interfaces. It should return 
    // only "READ" permission. 
    Enumeration e1 = acl.getPermissions(p1); 
 
    // 
    // This enumeration should have "READ" and"WRITE"  
    // permissions. 
    Enumeration e2 = acl.getPermissions(p2); 
 
    // This should return false. 
    boolean b1 = acl.checkPermission(p1, write); 
     
    // This should all return true; 
    boolean b2 = acl.checkPermission(p1, read); 
    boolean b3 = acl.checkPermission(p2, read); 
    boolean b4 = acl.checkPermission(p2, write); 
}

Top
java-server-feedback@java.sun.com