Access Control Lists

Documentation / Administrator Docs / Developer Docs / Index / Security Administration / Security API

This document has the following sections:

ACL Structure
Calculating Permissions
Example Permissions
Example Usage

For information on how to set up Access Control Lists using Administration Tool, see the Access Control Lists page.

Introduction

Access control lists are associated with resources which need protection, and are used as the second half of familiar identity-based access control schemes:

First, a user Authenticates himself (or herself) to some realm. They do this by identifying themselves, and provide some sort of proof (such as a passphrase) that this is the correct identity. Implicitly, membership in some "groups" may be determined by this authentication.
Second, the system uses this user identity, and any associated groups, when it decides whether the user is Authorized to perform some action on some resource. It does this by using the authenticated "user" and "group" data, and comparing that to access rules provided in the Access Control List.

So for example an ACL might say that "alice" is allowed to "create" documents in some shared storage area, or that members of the "reviewers" group are not allowed to "modify" such documents.

User identifiers are not unique. There may be two different users named "alice"; they will not however be in the same realm so they will not be mistaken for each other. The principal identifiers in one ACL only come from a realm that will not mistake those identifiers. This is why ACLs are associated with only one realm.

Also, notice that like other objects, ACLs themselves need to be access controlled.

Access Control List Structure

An Access Control List (ACL) is a data structure that guards access to resources. In JDK 1.1, the java.security.acl package provides the interface to such data structures. The JavaServer Toolkit builds on the sun.security.acl implementation of those interfaces, enhancing them in these ways:

They are coupled with the realms used to authenticate the principals (users, groups, hosts) in the ACLs;
Implementations in the sun.security.realm package are automatically persistent;
Permission rules now support "host" based principals.

In JDK 1.1, a java.security.acl.Acl is a data structure with one or more owners and ACL entries. Only owners can change the ACL. Each ACL entry is a set of permissions associated with a particular principal, identifying one (or more) users in some authentication scheme. Each ACL entry has a flag that indicates whether or not the permissions listed there are to be granted or denied.

Entries: java.security.acl.AclEntry

Entries in access control lists contain these three things:

A single java.security.Principal object.
One or more java.security.acl.Permission values.
A flag indicating whether the permissions are being granted or denied to that principal.

Principals

Several kinds of Principals are commonly found in ACLs in the JavaServer Toolkit:

sun.security.realm.User ...as exposed through the Realm of which this ACL is a part..
java.security.acl.Group ... groups are sets of principals, including potentially other groups. Like Users, these come from the realm of which this ACL is a part.
sun.security.realm.Host ... a host is a specific fully qualified Internet host name, or a pattern for all such hosts in a domain, such as *.foo.net.

NOTE: Host principals are not associated with realms, and are not authenticatable. Their use is accordingly discouraged.

Permissions

Permissions are interpreted with respect to the object to which access is being controlled. For example, a restart permission may be important when talking about a host or network service, but will not be meaningful when talking about a file access through a filing protocol such as HTTP or NFS. And a access hosts permission might be quite general, or it might be further restricted so that not all hosts could be accessed.

NOTE: Permissions are evolving in an upcoming release of the JDK. If you define permissions, assume you will be modifying how you use them and the interfaces you must support. At this time it is best to restrict permissions to be strings which describe classes of operations on objects, such as read, modify, create, and administer.

Negative Permissions

Use of the deny flag to define "negative permissions" should be done with extreme caution. Although it is a powerful mechanism, it is also sufficiently complex that most users will not understand the effects which can be caused by using this flag, especially in conjunction with groups. See the examples of permission semantics below.

Ownership: java.security.acl.Owner

Each ACL has a set of owners associated with it, by virtue of implementing the java.security.acl.Owner interface. The only principals allowed to modify ACL entries, or the list of ACL owners, are its owners.

NOTE: At this time it is not possible to enumerate the list of owners of an ACL, so that ACL ownership can not be administered. Also, the method used to control who may modify that list of owners is weak. At this time, you should use a single well-known principal, such as "admin" or "root", to own all ACLs.

Calculating Permissions

When calculating the net permissions a principal is granted, the following rules are used.

Each principal or group can have one positive entry and one negative entry. That is to say, duplicate acl entries are not allowed.
If there is no entry for a particular principal or a group, then this means that the principal or the group has the null explicit permission set. (Permissions may be implied by membership in some group.)
The net group positive permission set for a principal is the union of all the positive permissions of each group that the principal belongs to.
The net group negative permission set for a principal is the union of all the negative permissions of each group that the principal belongs to.
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.
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.
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)).

The above text needs enhancement to describe how host entries apply (they are orthogonal, yes? applied first, if present?) and needs to be checked with respect to the clarifications adopted into the JDK 1.1 security APIs.

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	A+B+C

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

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

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

Example Usage

import java.security.acl.*;
import sun.security.acl.PermissionImpl;
import sun.server.realm.*;

public class Example {

  public static void main (String argv []) {

    //
    // Get the realm and three users
    //
    Realm         r = Realm.get ("myRealm");

    User          user1 = r.getUser ("user1");
    User          user2 = r.getUser ("user2");
    User          owner = r.getUser ("owner");

    //
    // Create a new group
    //
    Group         group1 = r.makeGroup ("group1");

    group1.addMember(user1);
    group1.addMember(user2);

    //
    // Create a new acl with the name "exampleAcl" and owned
    // by the owner we've chosen
    //
    Acl           acl = r.makeAcl ("exampleAcl", owner);

    //
    // Create the permissions understood by object we're protecting.
    // "READ" and "MODIFY" have very standard semantics.
    //
    // NOTE that normally the object being protected would have been
    // associated with permissions that make sense to it.  Servers
    // should not need to create permission objects like this, but
    // in this sample program this is how it needs to be done.
    //
    Permission    readPermission = new PermissionImpl ("READ");
    Permission    modifyPerm = new PermissionImpl ("MODIFY");

    //
    // Create an entry allowing group1 both READ and MODIFY permissions
    //
    AclEntry      entry;

    entry = = new AclEntryImpl (group1);
    entry.addPermission (readPermission);
    entry.addPermission (modifyPermission);
    acl.addEntry (owner, entry);

    //
    // Take away MODIFY permissions only for user1.
    //
    entry = new AclEntryImpl (user1);
    entry.addPermission (modifyPermission);
    entry.setNegativePermissions ();
    acl.addEntry (owner, entry);

    //
    // Verify that user1 only has READ permission by looking
    // at all the privileges it's granted.
    //
    Enumeration e1 = acl.getPermissions (user1);

    //
    // Verify that user2 has both READ and MODIFY permissions.
    //
    Enumeration e2 = acl.getPermissions (user2);

    //
    // This should return false.
    //
    boolean b1 = acl.checkPermission (p1, modifyPermission);

    //
    // This should all return true;
    //
    boolean b2 = acl.checkPermission (p1, readPermission);
    boolean b3 = acl.checkPermission (p2, readPermission);
    boolean b4 = acl.checkPermission (p2, modifyPermission);
  }
}

Top

java-server-feedback@java.sun.com