Module-to-ACS Protocol

DACS's mod_auth_dacs module for Apache invokes the dacs_acs program to do the hard part of deciding whether a request should be granted or denied. The module is responsible for configuring itself using new Apache directives, gathering information required to make the access control decision, passing that information to dacs_acs, and receiving the access control decision from dacs_acs, together with either environment information (if access is granted to an executable request) or error handling directives (if access is denied).

To prevent potentially sensitive information from becoming visible, mod_auth_dacs passes information to dacs_acs over an interprocess communication channel (pipe(2)). dacs_acs reads its standard input, makes the access control decision, and writes either environment information or an optional error handling directive to its standard output. The exit status of dacs_acs communicates its decision: zero means the request should be granted, anything else means the request should be denied.

The information passed to dacs_acs from Apache is in the format:

variable-name="variable-value"

each of which is terminated by a newline character. These variables are listed below. For details about how to reference these values, see Variables Available To Rules.

If access is granted, dacs_acs may provide a set of control directives for mod_auth_dacs to interpret, followed by a set of environment variables for mod_auth_dacs to introduce into the environment of an executable request. Each control directive starts with a "=" character and is terminated by a newline. Environment variables are specified in the format:

variable-name=variable-value

each of which is terminated by a newline character.

If access is denied, dacs_acs may instead provide an error handling directive, newline terminated, in the form expected as the third argument to Apache's ap_custom_response() function.

Credentials

DACS credentials can be passed to dacs_acs in several ways, but they have the following representation:

DACS:federation-name::[jurisdiction-name]:[username]=value[; ...]

If the jurisdiction-name is omitted, the username must also be omitted (see COOKIE_NAME_TERMINATORS). The string is URL encoded. If there are multiple credentials, they are separated by any combination of spaces and ";" characters.

Credentials are passed from mod_auth_dacs to dacs_acs using the SERVICE_COOKIE variable (transmitted over a pipe(2))

Because a process's environment is public on some systems, DACS takes care not to pass credentials using environment variables. Passing credentials through the HTTP_COOKIE environment variable is forbidden unless enabled by the ALLOW_HTTP_COOKIE directive. When specifically enabled by a rule's attribute, they can be passed using the DACS_COOKIE environment variable (see the pass_credentials attribute described in dacs.acls(5)).

If an HTTP Authorization header is used with the "DACS" authentication scheme, the "basic-credentials" component of the header may contain DACS credentials. Please refer to RFC 2617. These credentials have the format given above but are also base-64 encoded.

Please refer to dacs_authenticate(8) for additional information.

Rlinks

DACS provides an alternate authentication and authorization mechanism. An Rlink (rule link) is a special URL that includes an Rname component, which is essentially the name of an access control rule. Instead of matching the name of a requested resource against rules, as is normally done by DACS, the request itself (indirectly) specifies authorization constraints that DACS must apply to the request. Optionally, a DACS identity and other information can be included in the Rlink.

During authorization processing, the Rname is resolved to an access control rule that is processed the same as any other access control rule and the requested resource must be DACS-wrapped. In other words, a request that is recognized as an Rlink essentially says "use the rule identified by this request's Rname to decide whether or not to grant access and do not consider any other rule". Subsequent access control processing is identical to the normal case.

In typical usage, an Rlink is created (probably, but not necessarily by dacsrlink(1)) and the resulting URL is distributed (e.g., by email) to those parties intended to be able to access the resource. Similar mechanisms are widely used by web-based applications. For example, consider the case where a customer has purchased a digital resource and it is time to make the item (e.g., a file) available for downloading. A new Rlink is created for the item and given to the customer. The customer invokes the URL to obtain the item. Each customer receives a unique Rlink but there only needs to be one instance of the resource. Only those with a valid Rlink can access the resource. No traditional account needs to be created for the customer, and the Rlink does not authorize the customer to access any other secure resource. When the resource has been accessed, a log record will be created that identifies the customer and confirms the download.

The main advantage of Rlinks is that they make controlled file sharing and web service access simple. An Rlink is created and disseminated, and all recipients can access the named resource (subject to the Rlink's rule) using any web browser. Any number of different rules can be created for the same resource, with each one having a different Rname. An Rlink's rule can be changed or deleted by its owner at any time, even after it has been distributed.

Rlinks also offer an alternative way to make exceptions to the rule normally applicable. Rather than revising the "normal" rule for a resource or set of resources to take account for the exceptions, one or more Rlinks can be created to handle the special cases and the normal rules need not be touched.

Another application of Rlinks is as a short representation of an arbitrary URL. Someone accessing an Rlink that has been configured in this way is redirected to a specified URL; see the redirect() function. The URL can be changed at will simply by editing the Rlink's rule. The Rlink need not be kept secret when it is used for this purpose.

The main disadvantage of Rlinks is that security may rely on keeping Rnames secret, and because an Rlink may be visible in a URL, this can be difficult to keep up. Anyone who can capture an Rname and use it properly with a resource to which it applies can potentially gain access to that resource. An Rname might be found in a log file, or in a browser's history or bookmark list. Although this method is convenient for users, the requirement for secrecy means that it might not be appropriate in some situations. At the expense of some convenience, however, a password can be bound to an Rlink when it is created; for the Rlink to be valid when it is invoked, the same password must be presented as an argument. Furthermore, because the access control rule associated with an Rname is the same as any other rule, it may express any conditions it likes, so it can still require authentication to have been performed, restrict the user's IP address, and so on. Also, an Rlink cannot be used to gain access to a resource that is not described by its rule's services element.

  RnameIdent  -> Rname ':' ident | Rname ';' iptr

https://example.com/~alice/photos/myphoto.gif?RNAME=jigrFUwF
https://example.com/cgi-bin/manage.cgi/jigrFUwF
https://example.com/private/data?DACS_ACS=-rname+jigrFUwF

HTTP Authentication

dacs_acs can be configured to trigger HTTP authentication (see RFC 2617) by returning a WWW-Authenticate response header in certain circumstances. This will usually cause a browser or other web user agent to use its built-in mechanism for prompting the user for a username and password that corresponds to a particular access realm (a label that identifies a URL path prefix belonging to the server).

If dacs_acs denies access because the user is not authenticated (code 902, ACS_DENIAL_REASON_NO_AUTH), it checks to see if HTTP authentication has been enabled for the request. If not, processing of the denied request proceeds normally, otherwise DACS will try to use the RFC 2617 protocol to have dacs_authenticate authenticate the user.

Also see autologin(8).

If the feature is enabled and applies to a request:

The values of some of these variables are neither examined by DACS nor meaningful to it. For example, all that DACS requires of the realm string is that it be syntactically valid.

When enabled, the following flow of control occurs:

The following is an example of configuration that might appear in the appropriate section (or sections) in DACS configuration files:

HTTP_AUTH_ENABLE "yes"
HTTP_AUTH "Basic \"Doggies\" /basic/*"

EVAL ${Conf::http_auth_message} = \
  "902 https://example.com/cgi-bin/dacs/dacs_authenticate"

Given this example configuration, whenever access is denied for a resource having a URL path that begins with "/basic/" because the user is not authenticated, the following response-headers will be returned:

WWW-Authenticate: Basic realm="Doggies"
Status: 401

and the message body will contain the single line:

902 https://example.com/cgi-bin/dacs/dacs_authenticate

Instead of enabling the feature for all requests, the following example enables it only for those user agents that supply a User-Agent request-header that matches the regular expression "DACS-http/.*" (which happens to match the default User-Agent string sent by the DACS dacshttp(1) utility).

HTTP_AUTH_ENABLE = regmatch("${DACS::USER_AGENT}", "DACS-http/.*") ? "yes" : "no"

A similar expression would enable the feature only for Internet Explorer, Mozilla, curl, dacshttp(1), etc., or some combination of browsers. Simply obtain the User-Agent string(s) sent by the browser(s) and write the appropriate regular expression to match it/them.

Although RFC 2617 allows multiple WWW-Authenticate response-headers to be returned, this mechanism can only send one.

When provided by a user agent, dacs_acs makes the value of the Authorization request-header available to access control rules through the ${DACS::AUTHORIZATION} variable. DACS credentials can also be passed using this request-header.

Authorization Caching

After a rule grants access, dacs_acs can be configured to save some context about its access control decision so that if the user makes a subsequent request for a resource managed by the same rule in a similar context, authorization can be granted quickly and without having to search for the applicable rule or re-evaluate it. Basically, the administrator tells DACS that if the rule grants access to a particular user, then it is safe for DACS to assume that future requests for the same resource by the same user should be granted without doing a complete authorization check.

This mechanism offers improved performance in cases where:

Authorization caching is implemented using a special HTTP cookie, called an access token (not related to the tokens used in authentication), and a simple database maintained by dacs_acs. A cookie is returned to the user when caching is possible and the user does not already possess a valid cookie. An access token points to server-side data that describes the cached authorization, including the context in which it is valid. Immediately after revocation testing, dacs_acs checks if authorization caching applies to the current request; if it does, no access control rules are examined and access is immediately granted. If caching does not apply, processing continues as usual. If any invalid access tokens were sent with the request, dacs_acs will ask for them to be deleted (i.e., it unsets the cookies). These cookies have the following format:

DACS:federation-name::jurisdiction-name::TOKEN-unique

Here, unique is the "dacs64" encoding (see dacs.exprs(5)) of a cryptographically strong pseudo-random 16 byte value. Also see the COOKIE_NAME_TERMINATORS directive. Since access control is purely a jurisdictional responsibility in DACS, a cookie is meaningful only to the jurisdiction that issues it.

These cookies are non-persistent (they are supposed to disappear when a browser session ends). The value of COOKIE_PATH, or "/", determines the cookie's path attribute. The COOKIE_NO_DOMAIN and COOKIE_HTTP_ONLY directives are also honoured.

Here is a simple example of how DACS might be configured to enable authorization caching for a particular resource. The jurisdiction's dacs.conf would include directives similar to the following:

ACS_ACCESS_TOKEN_ENABLE        "yes"
ACS_ACCESS_TOKEN_LIFETIME_SECS "43200"
VFS                            "[tokens]dacs-kwv-fs:/usr/local/dacs/conf/tokens"

A rule for the resource might look like this:

<acl_rule status="enabled">
   <services>
     <service url_pattern="/cgi-bin/database.cgi"/>
     <service url_pattern="/cgi-bin/someprog.cgi"/>
   </services>
      
   <rule order="allow,deny">
     <allow permit_caching="yes">
       user("auth")
     </allow>
   </rule>
</acl_rule>

Given this configuration, the first time an authenticated user requests, say, https://example.com/cgi-bin/database.cgi, he will be issued an access token. This token will be valid for up to 12 hours, and its associated data will be stored as an entry in the file /usr/local/dacs/conf/tokens.

Before it can be used, DACS must be built with the feature enabled (see --enable-access-tokens in dacs.install(7)). The virtual filestore item type "tokens" must be configured to identify an indexed virtual storage method and location for storing cache entries. Also, the authorization caching mechanism must be configured (see ACS_ACCESS_TOKEN_ENABLE, ACS_ACCESS_TOKEN_LIFETIME_LIMIT, and ACS_ACCESS_TOKEN_LIFETIME_SECS).

Enabling the feature in a particular context also requires setting a rule's permit_caching attribute to "yes" (see dacs.acls(5)). Whenever access is granted because of the rule, authorization caching of the rule is possible.

Authorization caching is possible irrespective of whether a user has been authenticated. Caching is not allowed, however, in cases where the granting rule uses tail matching and a rule exists for a subordinate URL (i.e., where there is a "more specific" rule for some other resource that should not be overridden by caching the "more general" rule). These cases are simply ignored; they are not considered to be errors. It is therefore not possible to cache the outcome of a rule with a url_pattern of "/*", for example, unless it is the only rule in the ruleset.

The store of tokens may be deleted or modified at any time. Any access token that points to an invalid or missing entry in the store becomes invalid.

Over time, the server-side access token database tends to accumulate entries for access tokens that no longer exist or have expired. These should be garbage collected. (This is currently not automated, so the database needs to be truncated. There should also be way to list the entries and manually delete entries.) The dacsacl(1) command and dacs_admin(8) service can perform administrative functions on the entry database.

XML Output

When XML output has been enabled, dacs_acs will emit a document (conforming to dacs_acs.dtd) when access is denied, a processing error occurs, or when an access testing mode has been requested using the DACS_ACS argument.

dacs_acs associates an error code with each event or reason for which access might be denied (see the description of the ACS_ERROR_HANDLER directive in dacs.conf(5)). The error code is itself sufficient for a client to know why access was denied. When access is denied, an appropriately named XML element is emitted. The element will include an explanatory text message, and optionally, the URI of a handler that the client might call to continue the workflow. This URI is obtained from the applicable ACS_ERROR_HANDLER directive, if any.

The event905 element corresponds to the ACK_NEEDED (equivalent to error code 905) DACS error event. It is emitted if the client must acknowledge one or more notices before the request will be granted. Its handler attributes, which are optional, are obtained from the ACS_ERROR_HANDLER directive that applies to this error and the NOTICES_ACK_HANDLER directive. If the ack_handler attribute is absent, then the presentation_handler is expected to perform both presentation and acknowledgement handling functions. The notice_uris attribute is a comma-separated list of URIs of notices that must be acknowledged by the user. The resource_uris attribute is a comma-separated list of URIs of resources associated with this request; this will usually be only a single URI. The time and hmac attributes are used to enforce a secure workflow mode. Please refer to dacs_notices(8) and dacs.conf(5) for additional detail.

A common_status element indicates that dacs_acs could not process the request. This might happen, for example, if dacs_acs were not properly configured.

Variables Available To Rules

dacs_acs predefines several variables that may be accessed by rules. Additionally, variables obtained from the request's credentials are exported into the environment of an invoked CGI program. In this way, services can know who is making the request, to retrieve user preferences, for example.

In addition, parameters passed to a CGI program, whether through a query string or a message body (e.g., POST method data), may be accessed as variables. For example, for the service request:

 .../cgi-bin/foo?A=hello&B=world

the variables ${Args::A} with the value hello and ${Args::B} with the value world will be defined at the time ACL rulesets are evaluated. Also, variables obtained from the authenticated credentials may be referenced (e.g., ${DACS::JURISDICTION}).

 .../cgi-bin/foo?ARG=hello&ARG=world

From these sources, the execution environment, and from the DACS configuration, dacs_acs automatically creates four "classes" of variables: CGI parameter variables, configuration variables, environment variables, and request-specific variables created by DACS. These classes are called namespaces; please refer to dacs.exprs(5) for details. For example, the value of a CGI parameter is accessed by ${Args::varname}, the value of a DACS context variable is accessed by ${DACS::varname} (e.g., ${DACS::JURISDICTION}), and the value of configuration variable is obtained using ${Conf::varname} (e.g., ${Conf::FEDERATION_DOMAIN}).

% dacshttp -header Auggie Doggie https://example.com/cgi-bin/dacs/someprog

Exported Environment Variables

The normal execution environment of a CGI program or internally processed script (e.g., mod_php) that is DACS-wrapped is augmented with environment variables instantiated from validated credentials, access control rules, configuration information, and so on. Through these variables, services have access to the identity of the user making the request to retrieve user preferences, for example, or make run-time decisions.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head>
<meta http-equiv="Content-type" content="text/html;charset=ISO-8859-1">
<title></title></head>
<body>
<p>
<?php
phpinfo();
?>
</p>
</body></html>

The environment variables that are exported (when defined) are listed here. More detailed descriptions of these variables appear in other DACS documents.

<IfModule mod_jk.c>
  JkEnvVar DACS_FEDERATION         NONE
  JkEnvVar DACS_JURISDICTION       NONE
  JkEnvVar DACS_ACS_JURISDICTION   NONE
  JkEnvVar DACS_ROLES              NONE
  JkEnvVar DACS_USERNAME           NONE
  JkEnvVar DACS_CONSTRAINT         NONE
  JkEnvVar DACS_DEFAULT_CONSTRAINT NONE
  JkEnvVar DACS_COOKIE             NONE
  JkEnvVar DACS_MOD_AUTH_DACS      NONE
</IfModule mod_jk.c>

Object username = req.getAttribute("DACS_USERNAME");
out.println("roles = " + req.getAttribute("DACS_ROLES"));

The DACS_ACS Argument

Various aspects of the behaviour of dacs_acs can be controlled by an optional argument named DACS_ACS. This argument, which may be passed to any web service, is interpreted by dacs_acs rather than the web service that is being invoked. The value of this argument is parsed as a list of space-separated command line flags.

One use of this feature is when an application or middleware would like to know whether DACS will grant or deny a service request without having to actually execute the service request. When building a menu, for instance, an application might want to exclude items involving service requests that would be denied to the user. dacs_acs provides this capability.

To check whether access would be granted or denied, the application invokes the DACS-wrapped service or resource exactly as it would normally except that it provides the DACS_ACS argument. In some situations, if access would be denied dacs_acs will return an indication of what must be done; e.g., the user must authenticate or a notice must be acknowledged. There can be multiple reasons for denying access, in which case an application may have to repeatedly request a check and address the reason for denial before access may be granted.

The DACS_ACS argument can be a query argument or can appear in a message body with the content type application/x-www-form-urlencoded (as in the case of an HTML form submitted using the POST method, for example). The DACS_ACS argument may not be specified more than once. It is not always possible to escape this argument (see -invisible).

The following flags are recognized:

The flag list is processed from left to right. Any flag may be repeated, with the value of a later occurrence overriding an earlier one. If some part of the DACS_ACS argument is invalid, the initial, valid part will still be effective; e.g., if the initial part is -format XML, the output format will be XML.

dacs_acs removes the DACS_ACS argument from the rule-processing environment so as not to disturb access control processing. DACS credentials may accompany the service request just as they would a real request and are incorporated into the check.

Assuming the target resource is DACS-wrapped, instead of returning the resource, accessing the following URL would return an indication of whether an actual request to access the resource would be granted or denied:

% dacshttp -v -v \
 'https://dacs.dss.ca/cgi-bin/dacs/dacs_version?DACS_ACS=-check_only%20-format+xml'

DACS-Status-Line = "DACS-Status-Line" ":" DACS-Version SP ACS-Status-Code
  SP Reason-Phrase CRLF

DACS-Version = "DACS-" Version

ACS-Status-Code = "797" | "798" | "799"

DACS-Status-Line: DACS-1.4.8b 797 Access denied
DACS-Status-Line: DACS-1.4.8b 798 Access granted
DACS-Status-Line: DACS-1.4.8b 799 Access error

DACS-Status-Line: DACS-1.4.10 798 Access granted, unauth user (j10OXL2Z)

a="dacs64-approval-message", s="dacs64-signature"

j="jurisdiction-name"<newline>
h="digest-name"<newline>
s="stamp"<newline>
u="uri"<newline>
m="method"<newline>
i="ident"

j="DSS::DSS-dacs"
h="SHA1"
s="1185565675:130",
u="http://example.com/cgi-bin/dacs/dacs_current_credentials?FORMAT=HTML"
m="get"
i="unauth"

EVAL ${Conf::dacs_approval_digest_name} = "SHA256"