Provided by: dacs_1.4.38a-2build1_amd64 
NAME
dacs_acs - DACS access control service
SYNOPSIS
dacs_acs [dacsoptions[1]] [-dcc] [-proxy-static] [-proxy-exec]
dacs_acs-test
DESCRIPTION
This program is part of the DACS suite.
The DACS access control service, dacs_acs (or simply ACS) is responsible for making access
control decisions on web service requests. It is run by a web server. In the current
implementation, dacs_acs is executed by the web server as an external program. ACS
provides attribute- and role-based access control using the DACS rule-processing engine,
which consults access control rules (also referred to as ACLs) provided with DACS or
written by a DACS administrator. Because access control is performed on URIs, ACS can
control access to arbitrary resources, such as web pages, files, or programs.
A generic interface to DACS's rule processing engine is given by dacscheck(1)[2].
A web server runs dacs_acs to determine whether a particular service request is
authorized. Although in theory any web server that provides appropriate hooks could call
dacs_acs, at present only Apache 2.x and 2.2.x web servers are supported. A DACS-aware
Apache module called mod_auth_dacs[3] is configured using custom Apache directives and
runs dacs_acs. A web server having mod_auth_dacs[3] functionality is said to be
DACS-enhanced and web services that are under the control of mod_auth_dacs[3] are said to
be DACS-wrapped.
When Apache receives a DACS-wrapped service request, the mod_auth_dacs module is run,
which in turn runs dacs_acs to determine whether the request should be granted. The module
provides dacs_acs with the name of the requested service ("What is being accessed?"),
parameters that were passed in the request ("How is it being accessed?"), the identity of
the client ("Who is making the request?"), and other context associated with the request.
With this information at hand, dacs_acs consults a set of access control rules (the
ruleset) (see dacs.acls(5)[4]). Additional contextual information, such as DACS
configuration directives and build-time options, and the run-time environment, is also
available. The information returned by dacs_acs to the module either causes Apache to
grant permission, possibly with a constraint that specifies additional, service-specific
information, or denies permission, possibly with a reason for denial. dacs_acs may also
instruct the web server to redirect the client.
All DACS services must be under the control of dacs_acs, even those that do not require
the client to be authenticated. Also, a web server must be configured such that only
DACS-controlled services and no other services can be invoked through URLs associated with
its DACS jurisdiction.
It is not a requirement that all of a web server's resources be under the control of DACS.
That is, it is not necessary to DACS-wrap everything, but it is certainly possible.
Please refer to the documentation for mod_auth_dacs[3] for information on configuring the
DACS Apache module.
Security
A dacs_acs process, which is created by httpd, should ordinarily run as the same user
id as httpd. File and directory ownership and modes must be set so that it can read
its configuration files, access control rules, and so on. The DACS expression language
includes functions that can execute an arbitrary program and perform file system
operations, so care must be taken to ensure that files used by DACS cannot be edited
or replaced by non-privileged users. In some circumstances, it may be necessary for
dacs_acs to run as root, in which case a DACS administrator must be extra careful in
this regard.
Tip
One way to understand what dacs_acs is doing, or to debug it, is to enable the most
detailed level of logging[5]. This will emit a copious quantity of output to the DACS
log file, so be sure to reduce the logging level and delete the log file when you are
finished.
Setting the LOG_LEVEL[6] directive to "debug" or "trace" will produce detailed output
(although it can be moderated using the LOG_FILTER[7] directive). LOG_LEVEL has the
disadvantage that it cannot take effect until after configuration processing.
To enable logging output at the earliest possible time, you can add the desired
dacsoptions[1] flags to Apache's AddDACSAuth[8] directive; for example, by using a
directive like the following in httpd.conf:
AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs "-t -v"
Note that httpd must be restarted before changes to this directive take effect.
An alternative method of enabling detailed logging, equivalent to using the -t and -v
flags if neither has been specified, is to create a file in the DACS_HOME[9] directory
with the name debug_progname. For example, to enable detailed logging for dacs_acs,
the following command might be used:
% touch /usr/local/dacs/debug_dacs_acs
This method takes effect immediately and applies to any DACS web service or command
that accepts dacsoptions[1] at the time they begin execution. It overrides the current
value of LOG_LEVEL, is more selective because it applies only to progname (unlike
LOG_LEVEL), is easily turned on by creating the file and turned off by removing the
file, and neither requires changes to httpd.conf nor an httpd restart.
Module-to-ACS Protocol
DACS's mod_auth_dacs[3] 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[3]
passes information to dacs_acs over an interprocess communication channel (pipe(2)[10]).
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.
Important
The module provides dacs_acs with its DACS version number to ensure that it is
compatible. dacs_acs will deny all access to DACS-wrapped resources if its version
number does not exactly match the module's. This requirement helps to protect against
build or installation mistakes.
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[11].
SERVICE_ARGS
The query arguments (if any and whether GET or POST method is being used) followed by
POST arguments (if any and to the maximum length configured), base-64 encoded.
SERVICE_ARGS_TRUNCATED
For POST method requests, if the POST data stream (i.e., the request's entity-body)
was not completely captured, such as if the maximum length was reached, this variable
will be present and assigned the value 1.
SERVICE_AUTHORIZATION
The value of the Authorization HTTP header field, if present.
SERVICE_CONTENT_ENCODING
The value of the Content-Encoding HTTP header field, if present.
SERVICE_CONTENT_LENGTH
The value of the Content-Length HTTP header field, if present.
SERVICE_CONTENT_TYPE
The value of the Content-Type HTTP header field, if present.
SERVICE_COOKIE
The value of the Cookie HTTP header field, if present.
SERVICE_FILENAME
The name of the file, as determined by Apache, corresponding to this response.
SERVICE_HOSTNAME
The name of the host as set by the full URI or Host HTTP header field, as determined
by Apache.
SERVICE_HTTPS
If the request came over SSL/TLS (HTTPS), this variable will be present and set to
"on".
SERVICE_METHOD
The request method, as set by Apache (e.g., "GET").
SERVICE_MOD_AUTH_DACS_VERSION
The DACS version number string associated with the mod_auth_dacs[3] module.
SERVICE_PATH_INFO
The PATH_INFO part of the URI, as set by Apache.
SERVICE_POSTDATA
When available, the POST data stream (the HTTP message body) (or part of it: see the
description of the SetDACSAuthPostBuffer directive to mod_auth_dacs[12]). It is MIME
base-64 encoded.
SERVICE_PROXY_AUTH
The value of the DACS-Proxy-Authorization HTTP header field, if present. (Not
currently used).
SERVICE_PROXYREQ
If the current request involves proxy processing on this server, this identifies the
type of processing as "proxy" (for "forward proxying"), "proxy_reverse" (for "reverse
proxying"), or "proxy_response".
SERVICE_QUERY
The value of the query string component of the URI.
SERVICE_REMOTE_ADDR
The client's IP address.
SERVICE_REMOTE_HOST
The client's DNS name, if known by Apache.
SERVICE_SERVER_PORT
The TCP/IP port on which the request was received by Apache.
SERVICE_URI
The path portion of the URI, as determined by Apache.
SERVICE_USER_AGENT
The value of the User-Agent HTTP header field, if present.
If access is granted, dacs_acs may provide a set of control directives for
mod_auth_dacs[3] to interpret, followed by a set of environment variables for
mod_auth_dacs[3] 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[13]). 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[3] to dacs_acs using the SERVICE_COOKIE variable
(transmitted over a pipe(2)[10])
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[14] 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)[4]).
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[15]. These credentials have the format given above but are also base-64 encoded.
Security
It is forbidden to submit multiple credentials for the same identity to DACS and such
a request will trigger an error.
It is also forbidden to submit multiple DACS authentication cookies with the same
cookie name.
Please refer to dacs_authenticate(8)[16] 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)[17])
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()[18] 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.
Rlink Details
When an Rlink is used as a kind of "secret URL" that grants access to anyone who uses
it, an Rname is a randomly generated identifier that is unique, with very high
probability, relative to its namespace at a jurisdiction. By default, an Rname
consists of eight symbols from the set of upper- and lower-case alphabetics and
digits, yielding a namespace in excess of 10^14 identifiers. This makes guessing a
valid Rname highly unlikely. The characteristics of new Rnames can be changed at will;
the alphabet from which they are generated should be considered carefully, however, to
avoid problems that might arise when they are embedded within a URL or used as a
filename. RLINK[19] directives can map Rnames to the same or different namespaces,
depending on the filestore selected by a directive.
Note
An Rlink does not have to be used as a secret URL though, and its creator can
choose any Rname that will work with the mechanism described here.
If a rule contains the optional name attribute, the attribute value must exactly
match the Rname.
The base name of a file containing an Rlink will be its Rname. This naming scheme
is different from the one used for normal rules[20].
This feature allows multiple versions of an Rlink to be created, each bound to a
different identity. By attaching an identity to an Rlink, its creator can confer
different rights to different users, or simply track who has used the Rlink. These
identities may or may not correspond to "real" identities that are associated with
DACS authentication (i.e., there may or may not be an account associated with them);
DACS administrators should keep this mind to avoid any confusion.
An Rname may be followed by a suffix that directly or indirectly associates a DACS
identity with the Rlink. For want of a better name, this composite identifier is
called an RnameIdent and has the following syntax:
RnameIdent -> Rname ':' ident | Rname ';' iptr
In the direct mode of identity attachment, the Rname is followed by a separator (a
colon, which cannot appear in an Rname) and ident, a cryptographically protected and
base-64 encoded concise user identity[21] that is created by dacsrlink(1)[17]. These
encrypted identities are not the same as encrypted credentials. Different encrypted
identifiers may represent exactly the same identity. If DACS recognizes the Rname,
when it performs authorization checking it will do so assuming the specified identity,
ignoring any other credentials that might have accompanied the request.
In the indirect mode, the Rname is followed by a different separator (a semi-colon,
which cannot appear in an Rname) and an arbitrary string, called an iptr (identity
pointer) that is safe to embed in a URI. The same character set from which an Rname
can be generated is safe for an iptr: any number of alphanumerics, hyphens, and
underscores. The rule that is specified by the Rname is expected to map the string to
an identity, probably by using the identity element[22], and the identity is used in
the same way as in the direct mode. Like an Rname, in typical usage an iptr must be
difficult to guess and be kept secret, otherwise a valid Rlink might easily be
constructed that is associated with a chosen identity. The indirect mode has the
advantages of keeping the URL relatively short, is immune to changes of the encryption
key, and allows identities to be modified after an Rlink is shared.
An identity obtained using either attachment mode is tested for revocation.
The Rname, specified identity, and identity pointer are accessible in the DACS
namespace[11], when they are available, as ${DACS::RNAME}, ${DACS::RIDENT}, and
${DACS::RIPTR}, respectively.
Rlinks can easily be created manually or by a custom program, but the dacsrlink(1)[17]
utility provides a simple interface to create and administer them. Rules created by
dacsrlink can be manually edited and deleted just like any other rule. There is no a
priori limit on the lifetime of an Rlink; it continues to exist as far as DACS is
concerned if the Rname is recognized by an RLINK directive and the named rule exists
and is valid. Deleting the rule corresponding to an Rname effectively invalidates that
Rlink.
An Rname can be presented as an ordinary web service argument, as a component of the
request URI, or via the special DACS_ACS argument[23]:
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
Each of these approaches has advantages and disadvantages; the best choice depends on
web site and application details. For example, embedding an Rname as a component of a
URI is particularly well suited to CGI programs and web services (e.g.,
https://example.com/cgi-bin/manage/jigrFUwF, where manage is the name of the program).
Using the DACS_ACS argument allows the Rname to be used during access control testing
but completely hidden from the requested resource.
RLINK[19] directives are used to examine an incoming request, decide whether an Rname
is present, extract the Rname, and specify where the rule can be found. If an Rname is
present, normal access control processing is disabled and no search of the usual DACS
rulesets for an applicable rule occurs. If no RLINK directive finds an Rname, normal
access control processing occurs.
HTTP Authentication
dacs_acs can be configured to trigger HTTP authentication (see RFC 2617[15]) 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[15] protocol to have dacs_authenticate authenticate the user.
Also see autologin(8)[24].
Tip
This feature is configured through the HTTP_AUTH_ENABLE[25] and HTTP_AUTH[26]
directives, some configuration variables, and Auth clause directives[27]. Please refer
to them for details.
When HTTP authentication is triggered in this way, no extra Apache configuration needs
to be done or should be done. All that is required of Apache is that the resource that
should trigger authentication be DACS-wrapped.
Any password style authentication module, or the CAS authentication module, can be
configured in conjunction with DACS's HTTP Basic authentication (RFC 2617[15]). That
is, DACS can be configured to cause a browser to pop-up a username/password prompt and
then use the values supplied by the user as if they were the USERNAME and PASSWORD
arguments to dacs_authenticate. The authentication module on the backend of the
authentication procedure can use any type of Apache password file or DACS password
file, NTLM, CAS, etc.
Besides authenticating against an Apache password file created by htpasswd, htdigest,
or htdbm, this means that an ordinary browser can be used to capture a username and
password for any DACS authentication module that requires it. Please refer to the
description of the local_apache_authenticate[28] module for details.
If the feature is enabled and applies to a request:
1. any ACS_ERROR_HANDLER[29], AUTH_SUCCESS_HANDLER[30], and AUTH_ERROR_HANDLER[31]
directives that would ordinarily apply are overridden.
2. the HTTP_AUTH[26] directive that applies to the request specifies the authentication
scheme, realm, and any additional authentication parameters.
3. a WWW-Authenticate response header is returned to the browser. For example, for HTTP
Basic authentication this header might look like:
WWW-Authenticate: Basic realm="My Realm"
4. an HTTP status value of 401 (RFC 2616[32]) is returned. If the variable
${Conf::http_auth_message} is defined, its value is used as the message body; if it is
"", then no message body will be sent; if not provided, the string "902 Authentication
by DACS is required" is used.
5. if the variable ${Conf::http_auth_jurisdiction} is configured, it is expected to be
the name of the jurisdiction (within the current federation) at which
dacs_authenticate is to be invoked to authenticate the user; if the variable is
undefined, the name of the current jurisdiction is used.
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:
1. The user hits a DACS-wrapped URL when not authenticated; if dacs_acs is configured to
perform HTTP authentication for the request, it returns a 401 ("Unauthorized") status
code and a WWW-Authenticate header;
2. The browser prompts for a username and password; the user enters the information and
the browser re-submits the request, which this time includes an Authorization header;
3. dacs_acs again denies the request because the user is not authenticated, but sees an
Authorization header and redirects the user to dacs_authenticate (at
${Conf::http_auth_jurisdiction} or the current jurisdiction) with arguments necessary
for the selected authentication scheme; dacs_authenticate maps the given username (and
password, if available) to the USERNAME argument (and possibly the PASSWORD argument)
and invokes authentication modules as necessary;
4. If authentication succeeds, credentials are issued and the user is redirected to the
original request (via the GET method);
5. If authentication fails, the procedure is repeated from the beginning.
Important
The main advantages of HTTP Basic and Digest authentication (RFC 2617[15]) are its
simplicity and near-universal support. It does have some serious drawbacks compared to
a cookie-based (token) implementation, however. Here are a few:
• While various kludges exist, there is no standard way to de-authenticate, to tell
a client to stop sending an Authorization request header. Consequently, if a user
that has authenticated using HTTP Basic authentication signs out of DACS and in
the same browser session visits a link that triggers authentication, DACS
credentials may be automatically re-issued without prompting.
• In HTTP Basic authentication, there are more opportunities for an attacker to
capture a username and password, on the client side (which must cache both
parameters indefinitely), at a web server, or at a proxy server, even when SSL/TLS
is used.
• Any method can be used by a web server to validate a username and password. In the
common HTTP Basic authentication deployment, the web server must validate the
Authorization request header each time it is sent by a client, perhaps with every
request, meaning that an expensive authentication function may need to be executed
many times with exactly the same parameters during a particular session.
With Digest authentication, various aspects of the authentication protocol are subject
to time limits as a security measure. The configuration variable
${Conf::http_auth_timeout_secs} can be set to the number of seconds for which a nonce
is valid, thereby overriding the default; only advanced administrators familiar with
RFC 2617[15] should change the default.
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)[33] 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)[33], 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[15] 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[34].
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:
• users tend to make many requests for the same resource, or for a set of resources that
are managed by the same rule (such as CSS files or images);
• rule evaluation is relatively slow or expensive;
• there are a large number of rules and/or rule retrieval is relatively slow;
• re-evaluation of the rule is unnecessary (e.g., the rule does not update any state
information)
• it is acceptable for changes to the ruleset to not immediately affect cachable
decisions
Security
Pending further testing, this feature should be considered experimental. Use it in
production situations only after you have satisfied yourself that it is working
properly with your access control rules.
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)[35]) of a cryptographically
strong pseudo-random 16 byte value. Also see the COOKIE_NAME_TERMINATORS[13] 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[36], or "/", determines the cookie's path attribute. The
COOKIE_NO_DOMAIN[37] and COOKIE_HTTP_ONLY[38] 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.
Note
In the current implementation, each access token is contained within its own cookie,
rather than a jurisdiction collecting all of the user's tokens within a single cookie.
A user might therefore simultaneously hold many access tokens from each jurisdiction.
This should not be significant for middleware agents, but web browsers typically
impose various kinds of limits on cookie "real estate". Administrators should take
this into account when using this feature.
Before it can be used, DACS must be built with the feature enabled (see
--enable-access-tokens in dacs.install(7)[39]). 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[40], ACS_ACCESS_TOKEN_LIFETIME_LIMIT[41], and
ACS_ACCESS_TOKEN_LIFETIME_SECS[42]).
Enabling the feature in a particular context also requires setting a rule's permit_caching
attribute to "yes" (see dacs.acls(5)[43]). Whenever access is granted because of the rule,
authorization caching of the rule is possible.
Note
Only the url_pattern of the rule's matching Service element (or the path derived from
a url_expr attribute) is associated with the access token. This implies that when a
rule has more than one service element, as in the example rule above, a single access
token would be associated with only one of the two resources. Requests for different
services could result in multiple access tokens being returned to a user, one for each
service. A wildcard pattern is required if an access token is intended to grant access
to more than one resource (this restriction may be lifted in future releases).
Although a service request's arguments may be significant when initially granting
access, they are not significant with respect to authorization caching applied to
subsequent requests that use the access token. Once an access token is issued, the
resource or resources named by it may therefore be invoked with different arguments
without negating authorization caching.
If any constraint, permit_chaining pass_credentials, or pass_http_cookie attributes
are associated with the cachable rule, their values are also remembered and set if the
access token subsequently causes access to be granted.
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[44]
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.
Note
A positive result will be cached regardless of whether the requested resource actually
exists or is subsequently processed without error by the web server. It is therefore
possible for an access token to be issued for a resource that does not exist at the
time of issue but which is created at some later time.
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)[45] command and
dacs_admin(8)[46] service can perform administrative functions on the entry database.
Security
Access tokens are created and used in such a way that it is practically impossible for
an attacker to manufacture a valid access token or to convert an access token valid
for one resource into one valid for a different resource.
If a user is authenticated at the time an access token is generated, the token is
"tied" to those credentials (all of them) and becomes invalid if any of the
credentials become invalid or are not sent with the access token. If a user signs out
or reauthenticates after being issued an access token, therefore, the access token
will become invalid. Additional credentials, beyond what were present at the time an
access token was generated, have no effect in this regard.
As with cookies bearing DACS credentials, cookies containing access tokens must be
kept private. For an authenticated user, an attacker would need to acquire an access
token and all credentials to make use of the token. For an unauthenticated user, only
the access token is needed; presumably (but not necessarily) in this case a lower
level of security is being applied to the resource in any case.
It is the administrator's responsibility to ensure that authorization caching does not
break the intended semantics of a rule - DACS does not do any consistency or sanity
checks. For instance, if a rule is written to grant access only between 12:00 and
12:59 but an access token produced by the rule could continue to be valid beyond that
time interval, authorization caching could violate the intent of the rule. Also, a
rule that ordinarily produces side effects would not do so for any requests granted
through authorization caching.
As long as an authorization decision remains valid, changes to the ruleset will not
cause a cached decision to be reversed. That is, a change to the ruleset that would
ordinarily cause a request to be denied will have no effect on a cached decision. The
revocation list[47] is, however, processed as usual, so it is possible for a cached
decision to be denied due to revocation. An error encountered during processing would
also cause access to be denied, regardless of authorization caching.
XML Output
When XML output has been enabled, dacs_acs will emit a document (conforming to
dacs_acs.dtd[48]) 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)[49]). 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)[50] and dacs.conf(5)[49] 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}).
Note
Because at present a variable cannot be multi-valued, if a variable is set more than
once its value at the time of evaluation is not predictable. For example, given this
query string you cannot depend on which value is assigned to ${Args::ARG}:
.../cgi-bin/foo?ARG=hello&ARG=world
This also creates problems if you need to examine arguments produced by an HTML SELECT
element within a form when the MULTIPLE attribute is used because each OPTION selected
by the user will be associated with the same argument name. Syntactical and functional
improvements are planned in this regard.
Any "null" arguments in the query string (e.g., "&&") are ignored. A query string with
a component that has a value but not a name (e.g., "&=foo") is considered to be
invalid.
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)[51] 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}).
Standard Environment Variables
For dacs_acs, the Env namespace is comprised of CGI variables exported by Apache,
which includes HTTP request variables such as ${Env::HTTP_USER_AGENT}. The values of
recognized headers that might compromise security are edited or deleted. Apache will
export unrecognized HTTP request headers by prefixing the header name with HTTP_ and
mapping the header name to upper case; this example results in ${Env::AUGGIE} having
the value "Doggie":
% dacshttp -header Auggie Doggie https://example.com/cgi-bin/dacs/someprog
For other programs, the Env namespace is populated from the program's normal
environment.
These namespaces are reserved from other uses and their contents are, for the most
part, read-only.
The only MIME content types currently supported with respect to capturing CGI
parameters are application/x-www-form-urlencoded, which is the default used by
browsers when submitting a form, and multipart/form-data. At present, only 7bit data
encoding is supported. The methods by which values from forms can be returned to a
server are described in RFC 1867[52], RFC 2388[53], and HTML 4[54].
Note
In some contexts, Apache's PATH_TRANSLATED environment variable is not passed to
dacs_acs (it is still available as unusual to CGI programs).
Exported DACS Variables
The following variables are exported to the "DACS" namespace (e.g., ${DACS::QUERY}).
Upper and lower case are distinct in variable names. These values are either obtained
from Apache or are elements of the client's credentials.
ACS
If dacs_acs is requested to test access, this variable will be defined and have
the value of the DACS_ACS argument.
ARGS
A string representing all of the parameters to a CGI program, excluding
multipart/form-data, encoded as a query string. If the number or total size of the
parameters exceeded the implementation-dependent limit, the variable
ARGS_TRUNCATED will be defined and have a non-zero value.
ARGS_TRUNCATED
If this variable is defined and its value is non-zero, the argument list has been
truncated. This means that not all arguments to the CGI program are accessible to
dacs_acs and the value of one argument may have been truncated. See
ACS_POST_EXCEPTION_MODE[55].
ARG_COUNT
The number of arguments available in the Args namespace. If there are four
arguments in a request's query string and two arguments within its
application/x-www-form-urlencoded message body, for instance, then the value of
${DACS::ARG_COUNT} will be six. These arguments will be available collectively as
the value of ${DACS::ARGS} and individually in the Args namespace.
AUTHORIZATION
The value of the Authorization HTTP header field, if available.
CONTENT_ENCODING
The value of the Content-Encoding HTTP header field, if available.
CONTENT_LENGTH
The value of the Content-Length HTTP header field, if available.
CONTENT_TYPE
The value of the Content-Type HTTP header field, if available.
CURRENT_URI
The full URI for the requested resource, including any query component.
CURRENT_URI_NO_QUERY
The full URI for the requested resource, excluding any query component.
FEDERATION
The official name of the federation to which JURISDICTION belongs. If the user was
not authenticated, this variable will be undefined.
FILENAME
The full path of the file corresponding to the URL being invoked, equivalent to
Apache's SCRIPT_FILENAME environment variable or its REQUEST_FILENAME variable.
IDENTITY
The DACS identity (the username component plus federation and jurisdiction
components) if the user was authenticated, otherwise undefined.
INTERACTIVE
If the standard input is a valid terminal type device, this variable is set to 1,
otherwise it is undefined.
IP
The IP address, in standard numeric dot notation, associated with USERNAME. If the
user was not authenticated, this variable will be undefined.
JURISDICTION
The official, abbreviated name of the jurisdiction that authenticated USERNAME. If
the user was not authenticated, this variable will be undefined.
METHOD
The method used to invoke the URL, equivalent to Apache's REQUEST_METHOD
environment variable.
PATH_INFO
The PATH_INFO part of the URI, as set by Apache.
POSTDATA
A MIME base-64 encoded string representing the data stream (message body) sent to
a CGI program. If the number or total size of the parameters exceeded the
configured limit, the variable ARGS_TRUNCATED will be defined and have a non-zero
value. See the description of the SetDACSAuthPostBuffer directive to
mod_auth_dacs[12]).
PROXYREQ
If set, the type of proxy processing performed for this request by Apache (from
SERVICE_PROXYREQ).
QUERY
The query string, if any, that was appended to the URL.
REMOTE_ADDR
The REMOTE_ADDR, as set by Apache.
REMOTE_HOST
The REMOTE_HOST, as set by Apache.
RIDENT
The Rlink identity, if any, associated with the rule currently being evaluated.
See Rlinks[56].
RIPTR
The Rlink identity pointer, if any, associated with the rule currently being
evaluated. See Rlinks[56].
RNAME
The Rname, if any, associated with the rule currently being evaluated. This is
also available as ${Args::RNAME}. See Rlinks[56].
ROLES
The role string associated with USERNAME. If the user was not authenticated, this
variable will be undefined.
URI and URL
The URL being invoked.
USERNAME
The username (without any federation or jurisdiction component). If the user was
not authenticated, this variable will be undefined.
USER_AGENT
When provided by the user agent, this is equivalent to the HTTP User-Agent
request-header field and HTTP_USER_AGENT environment variable provided by Apache.
When an actual value is unavailable, this variable is set to "unknown".
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.
Note
Environment variables with the prefix "DACS_" are reserved for use by DACS and should
not be used for other purposes by an application. Upper and lower case are distinct in
variable names.
Tip
If PHP[57] is installed, a nice way to see the DACS environment variables that are
passed to a CGI program is to run a DACS-wrapped script like this:
<!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>
Alternatively, you can use dacs_prenv(8)[58].
The environment variables that are exported (when defined) are listed here. More detailed
descriptions of these variables appear in other DACS documents.
DACS_ACS_JURISDICTION
This is the official DACS internal, abbreviated name for the jurisdiction that has
granted access.
DACS_APPROVAL
A digitally signed message that confirms that DACS authorized the request. See
dacs_acs(8)[59].
DACS_CONCISE_IDENTITY
This is the full DACS identity to which access was granted expressed in the concise
syntax used by dacscheck(1)[2]. When available, the user's roles and IP address are
included.
DACS_CONF
This is the full pathname of the DACS configuration file.
DACS_CONSTRAINT
A constraint string associated with a sub-component of the matching access control
rule permitting the service request.
DACS_DEFAULT_CONSTRAINT
A constraint string associated with the matching access control rule.
DACS_FEDERATION
This is the federation name component of DACS_IDENTITY.
DACS_IDENTITY
This is the full DACS identity to which access was granted. Apache's REMOTE_USER
environment variable is also set to this value, so it is available for logging
purposes and export to CGI programs.
DACS_JURISDICTION
This is the jurisdiction component of DACS_IDENTITY.
DACS_MOD_AUTH_DACS
This is the date and time mod_auth_dacs[3] was built.
DACS_MOD_AUTH_DACS_VERSION
This is the DACS version identification string for the mod_auth_dacs[3] being used
(i.e., the DACS distribution that this module was built with).
DACS_ROLES
This is the role string associated with DACS_USERNAME within DACS_JURISDICTION.
DACS_SITE_CONF
This is the full pathname of the DACS site configuration file.
DACS_USERNAME
This is the username component of the identity to which access was granted.
DACS_VERSION
The major version number of DACS.
About Servlets
Note
The details of how environment variables are passed from Apache to servlets are
beyond the scope of DACS. But for what it's worth, the following illustrates how
to export and access them from servlets that are under the control of DACS in
conjunction with mod_jk[60] and Tomcat[61]. This used to work at one time but may
no longer be correct.
The following directives (which appear in, or are included in, the Apache
configuration file) are used (this list may be expanded):
<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>
From a servlet, the values of these variables can be obtained through the
getAttribute() method, invoked on an HttpServletRequest object. For example:
Object username = req.getAttribute("DACS_USERNAME");
out.println("roles = " + req.getAttribute("DACS_ROLES"));
OPTIONS
In addition to the standard dacsoptions[1], dacs_acs recognizes the following arguments:
-dcc
Disable the mod_auth_dacs[3] compatibility check. Use with care, normally only for
testing and debugging.
-proxy-static
Reserved for future use.
-proxy-exec
Reserved for future use.
-test
Perform some self-tests, then exit. A non-zero exit status means an error occurred. If
-test is the only argument (recommended), no configuration is necessary; otherwise,
normal configuration processing will be performed before the self-tests.
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.
Tip
The space character(s) must be properly escaped; e.g., as %20 or +.
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[62]).
The following flags are recognized:
-check_only
The presence of this flag tells dacs_acs not to actually execute the web service or
return the resource, but to merely return the access control decision. This flag and
the -check_fail flag are mutually exclusive.
If the access check was performed, HTTP status code 200 (OK) will be returned; any
other result indicates that the check could not be executed (e.g., due to an Apache
configuration problem or a DACS error). If the check is performed, a DACS-Status-Line
HTTP extension header is included in the response by default (see below).
The default response consists of a single line of text that gives the result. This
line consists of a three decimal digit result code, followed by a space, an
explanatory message, and a newline character; for example,
797 Access denied
798 Access granted
799 Access error
Inspecting the result code is sufficient to obtain the outcome of the check. Any
Apache ErrorDocument[63] directive for "error-code" 200 is overridden. The -format
flag (see below) can be used to select a different output format.
Note
The service or resource in question does not have to exist for dacs_acs to grant
access; for instance, this can happen if a wildcard rule pattern is used. Also,
keep in mind that access control rules can be written to be highly context
specific. The result of a test for a particular resource need not be the same an
instant later (access control rules can depend on the current date or time, for
instance).
Rules can be written such that their evaluation results in persistent changes; for
example, a database might be updated. These kinds of changes will occur both in
normal operation and when only checking access. dacs_acs defines the variable
${DACS::ACS} only during the testing mode of operation so that, if necessary,
rules can be written to differentiate between testing mode and normal operation.
-check_fail
This flag is like the -check_only flag, except if access is granted the request is
allowed to proceed. If access is not granted and HTTP status code 200 is returned, a
DACS-Status-Line HTTP extension header is included in the response by default (see
below). The -check_fail flag is useful in situations where a -check_only test that
indicates that access would be granted is always immediately followed by the actual
request. This flag and the -check_only flag are mutually exclusive.
-format fmt
By default, the -check_only flag (and in the case where access is denied, also the
-check_fail flag) results in a single line of text being output (equivalent to
"-format text"). If more detail is required, an XML description can be produced by
specifying any of the XML output formats. Refer to XML Output[64], the FORMAT CGI
argument[65], and the -format[66] command line argument.
-rname rname
The string rname, which is assumed to be the name of an Rlink, is made available
available as ${Args::RNAME} during evaluation of ACS_PRE_AUTH[67] directive
expressions.
-status_line
-no-status_line
The -status_line flag enables the DACS-Status-Line[68] header, overriding the setting
of the STATUS_LINE[69] configuration directive. The -no_status_line flag always
suppresses this header, regardless of the STATUS_LINE[69] directive and the
-check_only and -check_fail flags.
-visible
-invisible
If the DACS_ACS argument is passed as a query argument, the default behaviour is to
delete it so that it cannot be seen after access control processing grants access.
This deletion is explicitly enabled by the -invisible flag and disabled by the
-visible flag. If DACS_ACS is not deleted, it will be passed to an invoked program and
might affect subsequent processing.
Important
Deletion of the DACS_ACS argument is currently possible only if it is passed as a
query argument.
For example, consider the hypothetical URL:
https://example.com/cgi-bin/myprog?DACS_ACS=-check_fail+-visible&foo=baz
If the CGI program myprog is executed, it will not only see the foo=baz argument, but
also the DACS_ACS=-check_fail+-visible argument, and this could trigger an error or
incorrect behaviour when myprog processes it.
All DACS web services ignore a DACS_ACS argument, however, so its presence will not
affect them.
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'
The DACS-Status-Line header
When the DACS_ACS=-check_only argument is present, the response from DACS includes an
extension header named DACS-Status-Line. The format of this extension header follows
that of the HTTP Status-Line (RFC 2616[32], section 6.1):
DACS-Status-Line = "DACS-Status-Line" ":" DACS-Version SP ACS-Status-Code
SP Reason-Phrase CRLF
Where:
DACS-Version = "DACS-" Version
and Version is the DACS_VERSION_RELEASE string (e.g., 1.4.8b), and where:
ACS-Status-Code = "797" | "798" | "799"
The status code 797 means that DACS denies access, 798 means that it grants access,
and 799 means that an error occurred during processing.
Here are some examples:
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
The reason phrases in the examples are only recommendations; they may be replaced by
local equivalents without affecting the protocol.
Note
The reason phrase may include additional information, such as an audit identifier
that can be used to track the request in the DACS logs:
DACS-Status-Line: DACS-1.4.10 798 Access granted, unauth user (j10OXL2Z)
This header is also returned when -check_fail is requested, but only if access is not
granted.
The DACS_APPROVAL environment variable
If enabled by the ACS_EMIT_APPROVAL[70] directive, the DACS_APPROVAL environment
variable will be passed to a DACS-wrapped program. If the program cares to verify that
its execution has been authorized, it may validate the approval's signature (to ensure
that the approval has not been forged) and validate the stamp (to ensure that the
approval is not being replayed). If a man-in-the-middle attack is of concern,
end-to-end encryption should always be used.
With proper configuration, this feature can be used by a web-based program that is not
DACS-wrapped but for which authorization has been obtained indirectly. For example,
when dacs_uproxy(8)[71], invokes a program, dacs_uproxy will forward the value of
DACS_APPROVAL (when available) to the invoked program, which can obtain the value in
its HTTP_DACS_UPROXY_APPROVAL environment variable. If it is able to validate the
value (or can trust it), the invoked program knows that its execution was authorized
by DACS, even though DACS may not be configured or even installed on the host where
the invoked program runs.
A jurisdiction's cryptographic keys, identified by the virtual filestore item type
jurisdiction_keys, must be configured so that the approval can be digitally signed.
The value of DACS_APPROVAL has the following format:
a="dacs64-approval-message", s="dacs64-signature"
The dacs64-approval-message is a dacs64[35] encoded string, described below. The
dacs64-signature is the dacs64 encoded RSA signature of the approval message, which is
the unencoded dacs64-approval-message.
An approval message has the following format:
j="jurisdiction-name"<newline>
h="digest-name"<newline>
s="stamp"<newline>
u="uri"<newline>
m="method"<newline>
i="ident"
Here, jurisdiction-name is the name of the jurisdiction (including its federation
name) that generated the approval. The name of the message digest (secure hash)
algorithm used to sign the approval is digest-name. The unique stamp is stamp (as
generated by ustamp()[72]) and the URI, including any query component, is uri. The
HTTP method is method. The DACS identity of the user for which access was granted is
ident (or "unauth", if none). The stamp and method are mapped to lowercase. Here is an
example of an approval message:
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"
The RSA signature is computed using the jurisdiction's private key and SHA-1 (by
default) over the approval message. A different message digest algorithm can be used
by setting the configuration variable ${Conf::dacs_approval_digest_name} (see
digest()[73] for information about message digest algorithms):
EVAL ${Conf::dacs_approval_digest_name} = "SHA256"
DIAGNOSTICS
The program exits 0 if everything was fine, 1 if an error occurred.
NOTES
It ought to be possible to add functionality to clear or modify the Authorization header
associated with a particular resource by recognizing an argument much like -check_only.
SEE ALSO
dacsacl(1)[45], dacscheck(1)[2], dacs.acls(5)[4], dacs.conf(5)[49], dacs_admin(8)[46]
BUGS
While the DACS_ACS mechanism can be useful, it is still a kludge,
AUTHOR
Distributed Systems Software (www.dss.ca[74])
COPYING
Copyright2003-2016 Distributed Systems Software. See the LICENSE[75] file that accompanies
the distribution for licensing information.
NOTES
1. dacsoptions
http://dacs.dss.ca/man/dacs.1.html#dacsoptions
2. dacscheck(1)
http://dacs.dss.ca/man/dacscheck.1.html
3. mod_auth_dacs
http://dacs.dss.ca/man/mod_auth_dacs.html
4. dacs.acls(5)
http://dacs.dss.ca/man/dacs.acls.5.html
5. logging
http://dacs.dss.ca/man/dacs.1.html#logging
6. LOG_LEVEL
http://dacs.dss.ca/man/dacs.conf.5.html#LOG_LEVEL
7. LOG_FILTER
http://dacs.dss.ca/man/dacs.conf.5.html#LOG_FILTER
8. AddDACSAuth
http://dacs.dss.ca/man/mod_auth_dacs.html#AddDACSAuth
9. DACS_HOME
http://dacs.dss.ca/man/dacs.conf.5.html#var_dacs_home
10. pipe(2)
http://www.freebsd.org/cgi/man.cgi?query=pipe&apropos=0&sektion=2&manpath=FreeBSD+10.1-RELEASE&format=html
11. Variables Available To Rules
http://dacs.dss.ca/man/#vars_in_rules
12. mod_auth_dacs
http://dacs.dss.ca/man/mod_auth_dacs.html#SetDACSAuthPostBuffer
13. COOKIE_NAME_TERMINATORS
http://dacs.dss.ca/man/dacs.conf.5.html#COOKIE_NAME_TERMINATORS
14. ALLOW_HTTP_COOKIE
http://dacs.dss.ca/man/dacs.conf.5.html#ALLOW_HTTP_COOKIE
15. RFC 2617
http://www.rfc-editor.org/rfc/rfc2617.txt
16. dacs_authenticate(8)
http://dacs.dss.ca/man/dacs_authenticate.8.html#credentials
17. dacsrlink(1)
http://dacs.dss.ca/man/dacsrlink.1.html
18. redirect()
http://dacs.dss.ca/man/dacs.exprs.5.html#redirect
19. RLINK
http://dacs.dss.ca/man/dacs.conf.5.html#RLINK
20. the one used for normal rules
http://dacs.dss.ca/man/dacs.acls.5.html#acl_files
21. concise user identity
http://dacs.dss.ca/man/dacs.1.html#concise_user_syntax
22. identity element
http://dacs.dss.ca/man/dacs.acls.5.html#elements
23. DACS_ACS argument
http://dacs.dss.ca/man/#dacs_acs_argument
24. autologin(8)
http://dacs.dss.ca/man/autologin.8.html
25. HTTP_AUTH_ENABLE
http://dacs.dss.ca/man/dacs.conf.5.html#HTTP_AUTH_ENABLE
26. HTTP_AUTH
http://dacs.dss.ca/man/dacs.conf.5.html#HTTP_AUTH
27. Auth clause directives
http://dacs.dss.ca/man/dacs_authenticate.8.html#auth_clause
28. local_apache_authenticate
http://dacs.dss.ca/man/dacs_authenticate.8.html#local_apache_authenticate
29. ACS_ERROR_HANDLER
http://dacs.dss.ca/man/dacs.conf.5.html#ACS_ERROR_HANDLER
30. AUTH_SUCCESS_HANDLER
http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_SUCCESS_HANDLER
31. AUTH_ERROR_HANDLER
http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_ERROR_HANDLER
32. RFC 2616
http://www.rfc-editor.org/rfc/rfc2616.txt
33. dacshttp(1)
http://dacs.dss.ca/man/dacshttp.1.html
34. passed using this request-header
http://dacs.dss.ca/man/#http_authentication
35. dacs.exprs(5)
http://dacs.dss.ca/man/dacs.exprs.5.html#encode
36. COOKIE_PATH
http://dacs.dss.ca/man/dacs.conf.5.html#COOKIE_PATH
37. COOKIE_NO_DOMAIN
http://dacs.dss.ca/man/dacs.conf.5.html#COOKIE_NO_DOMAIN
38. COOKIE_HTTP_ONLY
http://dacs.dss.ca/man/dacs.conf.5.html#COOKIE_HTTP_ONLY
39. dacs.install(7)
http://dacs.dss.ca/man/dacs.install.7.html#configure_options
40. ACS_ACCESS_TOKEN_ENABLE
http://dacs.dss.ca/man/dacs.conf.5.html#ACS_ACCESS_TOKEN_ENABLE
41. ACS_ACCESS_TOKEN_LIFETIME_LIMIT
http://dacs.dss.ca/man/dacs.conf.5.html#ACS_ACCESS_TOKEN_LIFETIME_LIMIT
42. ACS_ACCESS_TOKEN_LIFETIME_SECS
http://dacs.dss.ca/man/dacs.conf.5.html#ACS_ACCESS_TOKEN_LIFETIME_SECS
43. dacs.acls(5)
http://dacs.dss.ca/man/dacs.acls.5.html#acl_syntax
44. tail matching
http://dacs.dss.ca/man/dacs.acls.5.html#tail_matching
45. dacsacl(1)
http://dacs.dss.ca/man/dacsacl.1.html
46. dacs_admin(8)
http://dacs.dss.ca/man/dacs_admin.8.html
47. revocation list
http://dacs.dss.ca/man/dacs.acls.5.html#revocation_list
48. dacs_acs.dtd
http://dacs.dss.ca/man/../dtd-xsd/dacs_acs.dtd
49. dacs.conf(5)
http://dacs.dss.ca/man/dacs.conf.5.html
50. dacs_notices(8)
http://dacs.dss.ca/man/dacs_notices.8.html
51. dacs.exprs(5)
http://dacs.dss.ca/man/dacs.exprs.5.html#variables
52. RFC 1867
http://www.rfc-editor.org/rfc/rfc1867.txt
53. RFC 2388
http://www.rfc-editor.org/rfc/rfc2388.txt
54. HTML 4
http://www.w3.org/TR/html4
55. ACS_POST_EXCEPTION_MODE
http://dacs.dss.ca/man/dacs.conf.5.html#ACS_POST_EXCEPTION_MODE
56. Rlinks
http://dacs.dss.ca/man/#rlinks
57. PHP
http://www.php.net
58. dacs_prenv(8)
http://dacs.dss.ca/man/dacs_prenv.8.html
59. dacs_acs(8)
http://dacs.dss.ca/man/dacs_acs.8.html#dacs_approval
60. mod_jk
http://tomcat.apache.org/connectors-doc/generic_howto/quick.html
61. Tomcat
http://jakarta.apache.org
62. -invisible
http://dacs.dss.ca/man/#invisible_flag
63. ErrorDocument
http://httpd.apache.org/docs/2.2/mod/core.html#errordocument
64. XML Output
http://dacs.dss.ca/man/#XML-output
65. FORMAT CGI argument
http://dacs.dss.ca/man/dacs.1.html#FORMAT
66. -format
http://dacs.dss.ca/man/dacs.1.html#format-arg
67. ACS_PRE_AUTH
http://dacs.dss.ca/man/dacs.conf.5.html#ACS_PRE_AUTH
68. DACS-Status-Line
http://dacs.dss.ca/man/dacs_acs.8.html#dacs_status_line
69. STATUS_LINE
http://dacs.dss.ca/man/dacs.conf.5.html#STATUS_LINE
70. ACS_EMIT_APPROVAL
http://dacs.dss.ca/man/dacs.conf.5.html#ACS_EMIT_APPROVAL
71. dacs_uproxy(8)
http://dacs.dss.ca/man/dacs_uproxy.8.html
72. ustamp()
http://dacs.dss.ca/man/dacs.exprs.5.html#ustamp
73. digest()
http://dacs.dss.ca/man/dacs.exprs.5.html#digest
74. www.dss.ca
http://www.dss.ca
75. LICENSE
http://dacs.dss.ca/man/../misc/LICENSE