Revoking Access and Disabling Authentication: The Revocation List

It is sometimes useful to have the administrative capability to "pull the plug" on a particular user, class of users, or depending on other context. This can be done in a "global" way by configuring a revocation list. The revocation list is consulted during authorization checking and by various authentication related components. The revocation list is processed by dacs_acs(8) before the rulesets, thereby overriding all access control rules, to see if a request should be denied based on the current credentials (if any) associated with the user making the request. The revocation list is also used by dacs_authenticate(8), dacs_auth_transfer(8), and dacs_auth_agent(8) immediately after a tentatively successful authentication to check if access has been revoked for the DACS identity established through the normal authentication procedure. Note that the revocation list is not used by dacsauth(1) or dacscheck(1) (although it arguably it should be, at least optionally).

A revocation list must be configured through the item type "revocations" and must be readable, although it can be empty.

The list consists of a sequence of lines, evaluated in the order in which they appear, each of which may contain:

The keywords are case insensitive and one or more whitespace characters appear between a keyword and the expression. A line can be continued by ending it with a backslash. Any line may be preceded by whitespace characters.

DACS expressions are described in dacs.exprs(5).

Examples:

# Deny access to all
deny user("any")

# Deny access to any user not already authenticated
# (subsequently no one will be able to authenticate)
deny user("unauth")

# Revoke all identities, making all users effectively unauthenticated
revoke user("any")

# Deny access to any user not authenticated by this jurisdiction
deny user("unauth") or not user("${Conf::JURISDICTION_NAME}:")

# Revoke the identity DSS:rmorriso
revoke user("DSS:rmorriso")

# Deny all access on the weekend
deny time("wday") eq 6 or time("wday") eq 0

# Deny any request not originating from a local network
deny not (from("10.0.0.0/8") or from("192.168.2.0/24"))

# Do not issue credentials to anyone from 10.0.0.124 but access is
# still possible
disable from("10.0.0.124")

# Do not issue credentials to DSS:bobo
disable user("DSS:bobo")

# Neither issue credentials nor grant access to DSS:bobo
block user("DSS:bobo")

URL Paths and Service Name Matching

While matching a service request against ACL rules, ACS recognizes a hierarchical structure for service names based on the path component of an HTTP (or HTTPS) URL. The URL path "/cgi-bin", for example, is considered to be an ancestor or parent of the path "/cgi-bin/program". The former URL path has two components, the latter has three components. The one-component URL path "/" is considered to be the ancestor of all other paths.

The * operator, which matches zero or more components that follow it, has special meaning only when it appears as a path component at the end of a URL path pattern specified by a rule. A system administrator can use the tail matching (wildcard) capability to establish default rules for portions of the name space of service requests. For instance the URL path pattern "/cgi-bin/*" is considered to be the ancestor of all paths having the prefix "/cgi-bin/" and matches service requests for "/cgi-bin/printenv", "/cgi-bin/", and "/cgi-bin".

Before matching a service request against the ruleset, ACS converts the service request into a canonical form. It strips any trailing / characters off of the service name (although the URL path pattern "/" is unchanged). Only absolute URLs can be specified in an ACL rule. The URL expressing the service request must also be absolute when received by DACS; typically, a web server will canonicalize the pathname corresponding to static content before ACS is invoked.

ACS searches the ruleset for the rule having the most specific URL path pattern that applies to a given request URI; that is, it examines the rules to find the one that has the greatest number of components in common with the service request's. If no exact match is found, it will search for increasingly general rules that apply. Only the most specific matching rule will be applied to the request; if it fails, no other (less specific) matching rule will be considered. If two or more rules "tie" (e.g., because of duplicate rules), one rule will be chosen arbitrarily. If no suitable match if found, ACS will deny access.

ACS does not recognize alternate names for the same resource (e.g., achieved using symbolic links), so it is possible for each of several names for the identical resource to be associated with different access control rules.

It should be emphasized that the service request URL received by the web server is textually matched against ACL rules without any interpretation on the part of ACS. Other than whether it will be mapped to static content or a CGI program, what the URL represents or how it will be processed by the web server is not taken into account by ACS.

For example, a service request for "/weekly" is not the same as a service request for "/weekly/index.html", even if "/weekly" is a directory and the web server would map the request to a file named "/weekly/index.html" and return its contents. A rule with the URL path pattern "/weekly/index.html" or "/weekly/*" (or perhaps "/*") is needed to control access to the file "/weekly/index.html".

Service Parameters

A user agent may optionally pass parameters to CGI programs. With the HTTP GET method, the parameters are appended to the URL sent to the web server (the "query string") and the CGI program. While the HTTP specification (RFC 2616) does not impose a limit on the length of a URL, a browser or web server may impose a maximum. (Recent versions of Internet Explorer have a maximum URL length of 2,083 bytes and the Apache web server imposes a limit of about 8192 bytes.) In the case of the HTTP POST method, the parameters are streamed from the user agent to the web server and then to the CGI program, so the potential number of parameters and their combined size is unbounded. ACS can optionally provide a finer granularity of access control by inspecting the parameters passed with a service request. By examining parameters, an ACL rule can be used to prevent certain users from gaining particular kinds of access. A rule might restrict a parameter value to be within a certain allowed range, for example. ACS supports expressions that may test whether particular service parameters are present or reference their values.

Because in the case of the POST method it is impractical, in general, to pass ACS all parameters and their values, a web server may impose limits on the number of parameters and aggregate size of parameters that it will make available to ACS. An invoked CGI program is unaffected by this limitation, however. Apache's mod_auth_dacs module allows its administrator to configure the maximum size of parameter data provided by the POST method that is made available to ACS.

Constraints

In some cases, merely testing parameter values is insufficient to determine whether access should be granted. Consider the case where a service is a program, a request's parameters represent the coordinates of a geographic area to be displayed, and some areas are not to be shown to some users, perhaps because they are "top secret". Examination of the parameters alone may be insufficient to determine whether the area they describe is within such a restricted area and perhaps ought not to be displayed. That determination might also depend on the contents of a database or complex calculations, for example. It is, therefore, beyond the scope of ACS to make access control decisions in such cases.

ACS addresses this problem by allowing constraints to be attached to an ACL rule and by passing them, and the identity of the client, to the service. A constraint may be thought of as a tag or additional argument that a service recognizes. If an ACL rule permits the service to be invoked, it is the responsibility of the service to take any constraints into consideration and make the final decision about granting access, which it is much better qualified to do than is ACS. In the case previously described, a constraint might notify the service that the particular user should be granted access only if the request does not involve a restricted area.

Of course, the purpose and meaning of a constraint depends on the implementation of a particular service. Different services might interpret the same constraint in completely different ways. For example, a service that performs both read-only operations and update operations might be implemented to recognize the constraint string "read-only" as meaning that it should only perform read-only operations. Alternatively, that same service might instead handle a request accompanied by the constraint string "updates-allowed" by permitting any operation for the user making the request; the absence of that constraint would restrict its functionality to read-only operations.

For additional detail, please refer to descriptions of the DACS_CONSTRAINT and DACS_DEFAULT_CONSTRAINT environment variables.

ACL Files

Each access control rule is stored in a virtual filestore under the item types acls and dacs_acls. The acls must be configured, and ordinarily consists of site-specific or jurisdiction-specific rules; the latter (dacs_acls) is optional and is intended to configure rules for the standard DACS web services.

The default configuration (from site.conf-std) is:

VFS "[acls]dacs-fs:${Conf::FEDERATIONS_ROOT}/\
${Conf::FEDERATION_DOMAIN}/${Conf::JURISDICTION_NAME}/acls"
VFS "[dacs_acls]dacs-fs:${Conf::DACS_HOME}/acls"

Most installations store ACLs as ordinary files. This is reflected in the default configuration directive shown above and is why they are imprecisely referred to as "ACL files".

acl-photos.0
acl-photos.1
acl-files.40

disabled-acl-photos.0
disabled-acl-photos.1
disabled-acl-files.40

/usr/local/dacs/federations/dss/acls/acl-x.0
/usr/local/dacs/federations/dss/acls/acl-x.2
/usr/local/dacs/federations/dss/acls/acl-x.3/acl-y.7
/usr/local/dacs/federations/dss/acls/acl-x.4
/usr/local/dacs/federations/dss/acls/acl-x.5
/usr/local/dacs/federations/dss/acls/acl-x.6/acl-x.1

ACL Syntax

Basically, an ACL rule compactly expresses the triple (What, Who, How).

Although it's certainly possible to write complicated access control rules, you needn't be intimidated. Rules are typically quite simple and easy to understand, such as the following rule which applies to a URL that has a path component ending in /cgi-bin/dacs/myprog.php and grants access to any authenticated user:

<acl_rule status="enabled">
  <services>
    <service url_pattern="/cgi-bin/dacs/myprog.php"/>
  </services>

  <rule order="allow,deny">
     <allow>
       user("auth")
     </allow>
  </rule>
</acl_rule>

An access control rule is written and stored externally as an XML document with the following DTD (acl.dtd). Management of ACL rules can be done using a standard text editor, web-based interface, or special-purpose GUI. An administrator might only see a user-friendly description of the rules and need never see a lower-level representation such as this XML representation.

<!ELEMENT acl_rule (services, (identity)*, (rule)+)>
<!ATTLIST acl_rule
  status (enabled | disabled)             #IMPLIED
  name CDATA                              #IMPLIED
  expires_expr CDATA                      #IMPLIED
  constraint CDATA                        #IMPLIED
  permit_chaining (yes | no)              #IMPLIED
  pass_credentials (none | matched | all) #IMPLIED
  pass_http_cookie (yes | no)             #IMPLIED
  permit_caching (yes | no)               #IMPLIED
>

<!ELEMENT services (service | delegate)+>
<!ATTLIST services
    shared (yes | no) #IMPLIED
>

<!ELEMENT service EMPTY>
<!ATTLIST service
    id          CDATA #IMPLIED
    url_pattern CDATA #IMPLIED
    url_expr    CDATA #IMPLIED
>

<!ELEMENT delegate EMPTY>
<!ATTLIST delegate
    id          CDATA #IMPLIED
    url_pattern CDATA #IMPLIED
    url_expr    CDATA #IMPLIED
    rule_uri    CDATA #REQUIRED
>

<!ELEMENT identity EMPTY>
<!ATTLIST identity
    id            CDATA #IMPLIED
    iptr          CDATA #REQUIRED
    ident         CDATA #REQUIRED
    selector_expr CDATA #REQUIRED
>

<!ELEMENT rule ((precondition)?, (allow | deny)*) >
<!ATTLIST rule
    id CDATA                                #IMPLIED
    order CDATA #REQUIRED
    <!-- order is either of: "allow,deny" or "deny,allow" -->
    constraint CDATA                        #IMPLIED
    permit_chaining (yes | no)              #IMPLIED
    pass_credentials (none | matched | all) #IMPLIED
    pass_http_cookie (yes | no)             #IMPLIED
    permit_caching (yes | no)               #IMPLIED
>

<!ELEMENT precondition ((user_list)?, (predicate)?)>

<!ELEMENT user_list (user)*>

<!ELEMENT user EMPTY>
<!ATTLIST user
    id   CDATA #IMPLIED
    name CDATA #REQUIRED
>

<!ELEMENT predicate (#PCDATA)>

<-- The allow element allows (grants) access, subject to the -->
<-- allow,deny/deny,allow order, if the enclosed expression is TRUE -->
<-- Note: any '<' and '&amp;' characters appearing within an allow element -->
<-- must be escaped as &lt; and &amp;, respectively -->

<!ELEMENT allow (#PCDATA)>
<!ATTLIST allow
    id CDATA                                #IMPLIED
    constraint CDATA                        #IMPLIED
    permit_chaining (yes | no)              #IMPLIED
    pass_credentials (none | matched | all) #IMPLIED
    pass_http_cookie (yes | no)             #IMPLIED
    permit_caching (yes | no)               #IMPLIED
>

<-- The deny element denies access, subject to the allow,deny/deny,allow -->
<-- order, if the enclosed expression is TRUE -->
<-- Note: any '<' and '&amp;' characters appearing within an allow element -->
<-- must be escaped as &lt; and &amp;, respectively -->

<!ELEMENT deny (#PCDATA)>
<!ATTLIST deny
    id CDATA                                #IMPLIED
>

The optional id attribute assigns a unique label (within its acl_rule) to an element so that it can be identified conveniently and unambiguously. Attribute values consist of one or more alphanumerics and underscores. At present, no other semantics are assigned to this attribute, but this may change in future releases. Labels that begin with an underscore are reserved for DACS-generated labels.

The ACL Selection and Evaluation Algorithm

The following algorithm is used by ACS to determine if a particular service request (S, in canonical form) with optional parameters (P) should be granted for a user with verified credentials (C) within a particular execution environment (E). At this point, ACS has already determined that the revocation list has not denied access.