Element-Level Security (EACLs)

Historically, AccuRev has supported a security mechanism for depots and streams using Access Control Lists (ACLs). To address customer needs for more extensive security, AccuRev 5.2 introduced greatly enhanced ACL security control at the element level.

Overview

A depot ACL protects all the elements, streams, and issues in the depot. A user who has no access to the depot can still see the stream hierarchy, but none of the files in the streams. They can also not edit the streams in anyway. A stream ACL prohibits editing streams and viewing content in a stream. It can also be inheritable down the hierarchy. The table below shows what stream, depot and element ACLs restrict:

	Viewing Content	Editing Stream	Viewing and Editing Issues
Stream ACL	Yes	Yes	No
Depot ACL	Yes	Yes	Yes
Element ACL	Yes	No	No

Features

There are three main features of the new element security mechanism:

The ability to allow or deny access to all versions of an element, no matter what stream they are in, for a specified user or group. If a user is denied access they cannot see or view the element.
The ability to specify who can modify the access to an element. This is a higher privilege than just being allowed access.
The ability to view the history of access changes for auditing purposes. This means being able to trace who assigned access to an element, when they did it and what they did.

Basic Terms

To control access to elements (files and directories), AccuRev 5.x implements a new eacl command (see eacl in CLI Help) to set and modify Access Control Lists (ACLs) and Access Control Entries (ACEs). An ACL is a list of security protections that applies to an element. An ACE is an entry in an ACL that defines a principal and a privilege.

A principal can be:

a user
a group
all

A privilege can be:

Full - the ability to see and view the element and to modify its ACL
Allow - the ability to see and view the element, but not modify its ACL
Read only - prevents the user from modifying the element or its ACL during add, keep, move, defunct, and revert commands.
Deny - the inability to see and view the element or modify its ACL

An ACL contains zero or more ACEs. An element can have only one ACL assigned to it at any point in time. You specify whether to set, add, or remove an ACE (principal and privilege) to an element, and AccuRev takes care of the ACLs automatically. Note that ACLs cannot be created or modified without an element.

Important Concepts

Before jumping into implementation details, it is important to keep the following concepts in mind to avoid confusion and incorrect assumptions:

Element-based security

AccuRev security is based on AccuRev elements rather than pathnames, and this makes AccuRev security both more powerful and more complex than typical filesystem security. don't forget: an AccuRev element can be either a file or a directory, and can also be an element link (elink) or symbolic link (slink).

An element is defined by its element id ("EID"), which never changes. It also has a pathname (defined by its "parent EID") and a name, both of which can change.

A symbolic link (slink) is an element whose contents is a pathname which can point to either AccuRev or non-AccuRev data.

An element link (elink) is an element whose contents is a pointer to another element, which must be in the same workspace. The target element can be a directory element, a file element, another element link, or a symbolic link.

A key concept to master is how ACLs apply to the element versus the element's contents. See Inheritance (below) to understand how access to contents and namespace differs,

Likewise, if you use element links (elinks), you must understand how AccuRev element security does and does not apply to the link and to the destination file, otherwise a file that you think is denied to a principal may still be accessible.

In AccuRev, the same element can have multiple pathnames, depending on what streams it is in at different times. While pathnames and filenames can change, the element id (EID) never does, and this is what AccuRev security is based upon. This allows you to secure the contents of an element no matter what its current pathname is.

Remember:

A simple pathname may refer to more than one element (such as both ends of an elink), and likewise a single element may have more than one pathname (such as one pathname to the actual file, and a different pathname for that file as a target of an elink).
An element may have different paths in different streams, and may have different paths at different points in time.

ACLs are not TimeSafe®

The third concept to keep in mind when using AccuRev element security is that ACLs are always current: they are NOT TimeSafe, and they are not affected by what stream they happen to appear in. This means that you cannot recreate ACLs as they appeared at a certain point the same way as you can recreate file versions or stream configurations. (You can, however, view ACL changes through the hist command.) It also means that the appearance of a snapshot stream can change for a particular user or group, The snapshot doesn't change—that is TimeSafe. But a user's access to the contents of that snapshot can change. If your access changes, the next time you perform a pop command on your workspace, you may see files appear or disappear.

Privileges

The default behavior for an element whose ACL doesn't contain an ACE for a user is to deny access to that user. The deny privilege overrides allow and full. This makes it easy to give access to everyone (all), but then deny a few. If a user has both allow and full, then full privilege is granted.

The full privilege means the ability to change which ACL is associated with the element and to modify the ACL as well. A user only needs to have allow privilege to show ACLs on an element or to view the ACL. When setting or modifying an ACL for an element, it is the current ACL associated with the element that controls the ability to set or modify the ACL. The table below describes what a user can or cannot do based on privileges:

	View ACL	Modify ACL	View Elements	Modify Elements
Full	Yes	Yes	Yes	Yes
Allow	Yes	No	Yes	Yes
Deny	No	No	No	No
Read only	Yes	No	Yes	No

Inheritance

Element security inheritance differs for content and namespace.

Content is based on a static inheritance model. This means that an ACL is set for an element when assigned by the user or when it is created and inherits the ACL from its parent.

Namespace access is based on dynamic inheritance. This means that it is computed by the element's pathname when it is accessed.

This means that if you are denied access to a particular element, you cannot see the contents or even the name of the element. However, if you are denied access to directory, but not denied access to a file in that directory, you can still perform certain operations on that file by using its EID. For example, if you know its EID, you can cat the file. You will not be able to see its name, but you can see its contents.

The user also has the ability to set an ACL recursively down the directory tree, making it easy to assign an ACL to multiple elements. Multiple elements can be specified on the command line as well.

Renaming, moving, or defuncting an element does not change its ACL or access. Only setting or modifying an ACL on the element can change access to the element.

Access Denied

This section describes what it means when access is denied to the content or the name space of an element:

A user is denied access to the content and namespace of an element if they are denied access to the element itself.
A user is also denied access to the namespace of an element if they are denied access to any of the directories in the element path.
If a user is denied access to the namespace, but not the element, the user will be denied access to the content if they try to specify the element name.
If a user is denied access to the namespace, but not the element, the user will NOT be denied access to the content if they try to specify the element EID.

Create a superuser to Administer Element Security

When you install an AccuRev release that contains element security for the first time, all elements are assigned the allow privilege. This provides new and existing customers with the exact same behavior provided by previous versions of AccuRev, but it does not permit existing privileges to be modified: modifying an element privilege (an EACL) requires the full privilege.

Only AccuRev users identified as a superuser are granted the full privilege needed to modify element privileges. The superuser always has full access to all elements and is needed to begin the process of setting up element security, and to fix problems that users may cause, such as denying everyone access to an element.

The AccuRev administrator can set or unset a user as a superuser using the maintain program, as follows.

To set a user as a superuser, run this command:

maintain su -a <principal_name>

To remove superuser status from a user, run the same command with the -r option:

maintain su -r <principal_name>

Auditing

To provide auditing (or history) capability for element security, AccuRev keeps track of all ACL changes to elements. This doesn't mean that element ACLs are TimeSafe(and it is important to realize that element ACLs are not TimeSafe). The most recent version of an ACL and the most recent ACL assigned to an element is always used for authorization of access. Historical information on changes to ACLs is only used for audit reporting. The hist command is used to display the history of ACL changes on an elements.

Setting Permissions for a Replica Server

If you are using a replica server in an EACL environment, it is critical that you set EACL permissions correctly not only for the users on the replica, but for the special replica user account (replica-user ) that is used to communicate between the replica and the master server.

For example, assume that you want the users of a replica server to be able to access all of the files underneath folder offshore_files, but that you do not wish them to be able to see anything under hq_files. If you fail to assign allow permission to replica-user for offshore_files, the replica may not be able to fetch any files from the master.

More importantly, if you fail to assign deny permission to replica-user for hq_files, it would be possible for a privileged user to log into the replica and bring the denied files down to the replica. Continuing this example, say that a privileged user from corporate headquarters visits the offshore site where the replica is being used. If the replica-user is not correctly configured, the privileged user could log into the replica server and inadvertently bring down hq-files elements by doing an update. If the replica-user is configured with deny access to these files, the server will not send them to the replica.

EACL Usage Scenarios

The following examples illustrate two basic approaches to setting up element ACLs:

less restrictive—By default, all users have allow access to all elements, unless explicitly denied.
more restrictive—By default, all users are denied access to all elements, unless explicitly allowed.

Both examples make use of the same environment: Assume that your company ("Acme Agile, Inc.") has a new product ("Product3000"), and you will be collaborating with two partners to develop the code ("Partnership_1" and "Partnership_2"). For simplicity, these examples illustrate settings ACLs for specific users. In a real-life scenario, you would typically assign many users to various groups, and then set the element ACLs by group.

Set Up

The AccuRev administrator initially set up a basic stream structure:

You, Acme employee user "acme_1", create a workspace off of stream prod_3000_devel and set up the initial files and folders for the project:

Since you are a trusted user, the AccuRev administrator grants you "superuser" status so that you will be able to assign element ACLs as needed.

To make you a superuser, the AccuRev administrator logs in to the AccuRev server machine and uses the AccuRev maintain command.

Note: The administrator must first shut down the AccuRev server before using maintain.

> maintain su -a acme_1
AccuRev 6.0 (2013/05/20)
Copyright (c) 1995-2013 AccuRev Inc. All rights reserved
Changed user 'acme_1' to a super user
>

The administrator restarts the AccuRev server, and you log in to the AccuRev CLI as acme_1 and start assigning EACLS as shown below.

Less Restrictive Scenario

Your starting point is the system default for first time AccuRev installations: everybody has allow access to all files and namespaces, and you will explicitly change privileges to certain elements for certain users to either full or deny.

Remember:

deny means that the user cannot even see the element.
allow means that the user can see and work with an element, but not change its ACL
full means that the user not only can see and work with an element, but can also set the ACL on that element.
deny overrides allow and full, and if there is no explicit allow, a user is denied.

In this case, you want to grant the user from Partnership_1 ("part_1") allow privileges on the partner_1 files, but deny that user any privileges on the partner_2 files or the acme_proprietary files. Likewise, the user from Partnership_2 ("part_2") should have allow privileges to the partner_2 files, but deny privilege to the partner_1 and acme_proprietary files.

Note: It is conceivable that partners might want full access to their own files so that they could set specific ACLs for their own users. However, the full privilege is very powerful and should not be granted unless absolutely necessary. A partner with full access could deny you access to files on your own system, or inadvertently deny access to everybody, both of which would require superuser intervention.

Both partners should retain allow access to the Acme common_files folder and its contents.

Finally, you (acme_1) want to have full privileges on all elements in the project. To set up these ACLs:

> accurev login acme_1

Change to the workspace directory for the prod_3000_devel project and grant yourself (acme_1) full access to all project files.
```
>accurev eacl -a acme_1:full -R prod_3000_devel_files
```
Note: Since we want to leave the default all:allow ACL in place for all the files in the project, and explicitly adjust the ACLs of specific files and specific users, it is critical that we use the
-a (add) option here, and not -n (new). If we had specified -n, user acme_1 would have been granted full access, while removing access for everybody else. Removing access is the same as specifying deny.
Explicitly deny both partners any access to the Acme proprietary elements:
```
>accurev eacl -a part_1:deny,part_2:deny -R prod_3000_devel_files\acme_proprietary
```
Again, note the use of -a, which retains the default allow access to these elements for other users (such as other Acme employees). Using -n here to set deny access to the partners would have been the same as setting all:deny, since it would have removed the default all:allow setting.
Deny Partnership_1 any access to Partnership_2 files, while granting allow access to them to the Partnership_2 user (and retaining the default all:allow access to all other users).
```
>accurev eacl -a part_2:allow,part_1:deny -R prod_3000_devel_files\partners\partner_2
```
Deny Partnership_2 any access to Partnership_1 files, while granting allow access to them to the Partnership_1 user (and retaining the default all:allow access to all other users).
```
>accurev eacl -a part_1:allow,part_2:deny -R prod_3000_devel_files\partners\partner_1
```

Once you (acme_1) promote all these elements up the stream, the effect of the ACLs becomes obvious.

Note: The promote has nothing to do with setting EACLs; it is just that the files were being set up for the first time in acme_1's workspace and do not even exist in the stream hierarchy until they are promoted.

When you (acme_1, who has full access to all elements) view the contents of the prod_3000_itr stream, all folders and elements are visible. In the following example, the elements in partner_2 are displayed.

However, if user part_1 logs in and views the same stream, he or she sees a very different display. Only the partner_1 files and the common Acme files are visible. From user part_1's perspective, the partner_2 and Acme proprietary files and folders do not even exist.

User part_2 would see a similar display, except the partner_2 files and folder would be visible, while those of partner_1 could not be seen.

Although the ACL setting is not visible from the GUI, an ACL list from the CLI will reveal that while user acme_1 has full access to the partner_1 elements and user part_2 has no access to the partner_1 elements, user part_1 has allow access to the Acme common files through the default all ACL:

>accurev eacl common_files

/prod_3000_devel_files/common_files
	all:allow
	acme_1:full

>accurev eacl partners\partner_1

/prod_3000_devel_files/partners/partner_1
	all:allow
	acme_1:full
	part_1:allow
	part_2:deny

More Restrictive Scenario

This scenario is similar to the less restrictive scenario above, except that the default privilege for all users to all files will be deny. We will then adjust ACLS to increase privileges as needed.

Similar to the previous scenario, we will start by giving user acme_1 full access to all project files, but this time we will use the -n option instead of -a:

> accurev login acme_1

Change to the workspace directory for the prod_3000_devel project and use the -n option to grant yourself (acme_1) full access to all project files, replacing the default all:allow ACL.
```
>accurev eacl -n acme_1:full -R prod_3000_devel_files
```
Note: Unlike the previous scenario which used -a, all users except acme_1 are now denied access to all elements in the project by default.
Explicitly grant the user from each partnership allow access to the top of the project tree (but do not recurse through the tree structure, since we want to be selective about what they can and cannot access):
```
>accurev eacl -a part_1:allow,part_2:allow prod_3000_devel_files
```
Now, provide the Partnership_1 user (part_1) and Partnership_2 user (part_2) allow access to the partners directory:
```
accurev eacl -a part_1:allow,part_2:allow prod_3000_devel_files\partners 
```
Explicitly grant the Partnership_1 user (part_1) allow access to the Partnership_1 files and to the Acme common files. Note that unlike the previous example, it is necessary now to explicitly grant allow access to the common files, since the all:allow default ACL was implicitly removed in Step 2.
```
>accurev eacl -a part_1:allow -R prod_3000_devel_files\partners\partner_1
```
```
>accurev eacl -a part_1:allow -R prod_3000_devel_files\common_files
```

Likewise, explicitly grant the Partnership_2 user (part_2) allow access to the Partnership_2 files and to the Acme common files.

>accurev eacl -a part_2:allow -R prod_3000_devel_files\partners\partner_2

>accurev eacl -a part_2:allow -R prod_3000_devel_files\common_files

Because the default setting in this scenario is to deny access to users who have not been explicitly granted access, the above steps only address users acme_1, part_1, and part_2. You would need to continue these procedures to grant access to other Acme users as needed. In a real-life scenario, you would typically assign users to groups and assign ACLs to those groups rather than to individual users.