table of contents
DACS_ACS(8) | DACS Web Services Manual | DACS_ACS(8) |
NAME¶
dacs_acs - DACS access control serviceSYNOPSIS¶
dacs_acs [dacsoptions[1]]
[-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 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 DACSApache module.AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs "-t -v"
% touch /usr/local/dacs/debug_dacs_acs
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. The information passed todacs_acsfromApache is in the format:variable-name="variable-value"
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 (HTTPS), this variable will
be present and set to "on".
SERVICE_METHOD
The request method, as set by Apache (e.g.,
"GET").
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
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[; ...]
Rlinks¶
An Rlink (rule link) is an alternate mechanism for providing DACS authentication and authorization. Instead of matching the name of a requested resource against rules, as is normally done by DACS, the request indirectly specifies authorization constraints that must be applied to the request. Optionally, a DACS identity and other information can accompany the request. An Rname, which is essentially the name of an access control rule, is used to point at the authorization constraints. An Rlink is a URL that includes an Rname. 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)[16]) 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. 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[17] directives can map Rnames to the same or different namespaces, depending on the filestore selected by a directive.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[14]) 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[14] protocol to have dacs_authenticate authenticate the user. 1.any ACS_ERROR_HANDLER[27],
AUTH_SUCCESS_HANDLER[28], and AUTH_ERROR_HANDLER[29] directives
that would ordinarily apply are overridden.
2.the HTTP_AUTH[24] 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 Basic authentication this header might look like:
WWW-Authenticate: Basic realm="My Realm"
4.an HTTP status value of 401 ( RFC
2616[30]) 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.
HTTP_AUTH_ENABLE "yes" HTTP_AUTH "Basic \"Doggies\" /basic/*" EVAL ${Conf::http_auth_message} = \ "902 https://example.com/cgi-bin/dacs/dacs_authenticate"
WWW-Authenticate: Basic realm="Doggies" Status: 401
HTTP_AUTH_ENABLE = regmatch("${DACS::USER_AGENT}", "DACS-http/.*") ? "yes" : "no"
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
DACS: federation-name::jurisdiction-name::TOKEN-unique
ACS_ACCESS_TOKEN_ENABLE "yes" ACS_ACCESS_TOKEN_LIFETIME_SECS "43200" VFS "[tokens]dacs-kwv-fs:/usr/local/dacs/conf/tokens"
<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>
XML Output¶
When XML output has been enabled, dacs_acs will emit a document (conforming to dacs_acs.dtd[46]) 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)[47]). 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)[48] and dacs.conf(5)[47] 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
.../cgi-bin/foo?ARG=hello&ARG=world
% http -header Auggie Doggie https://example.com/cgi-bin/dacs/someprog
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[53].
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[54].
RIPTR
The Rlink identity pointer, if any, associated with the
rule currently being evaluated. See Rlinks[54].
RNAME
The Rname, if any, associated with the rule currently
being evaluated. This is also available as ${Args::RNAME}. See
Rlinks[54].
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) invoked through DACS 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>
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)[57].
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 a version identification string for
mod_auth_dacs[3].
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.
<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"));
OPTIONS¶
In addition to the standard dacsoptions[1], dacs_acs recognizes the following arguments: -proxy-staticReserved 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.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 digit result code, followed by a space, an
explanatory message, and a newline character; for example,
Inspecting the result code is sufficient to obtain the outcome of the check. Any
ApacheErrorDocument 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; there is no guarantee that the same decision made at one
point in time will also be made 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
797 Access denied 798 Access granted 799 Access error
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[61], the
FORMAT CGI argument[62], and the -format[63]
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[64] directive expressions.
-status_line
The -status_line flag enables the
DACS-Status-Line[65] header, overriding the setting of the
STATUS_LINE[66] configuration directive. The -no_status_line
flag always suppresses this header, regardless of the
STATUS_LINE[66] directive and the -check_only and
-check_fail flags.
-visible
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:
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 -formatXML, 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:
% http -v -v \ 'https://dacs.dss.ca/infocard-demo/cgi-bin/dacs/dacs_version?DACS_ACS=-check_only%20-format+xml'
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[30], section 6.1):
Where:
and Version is the DACS_VERSION_RELEASE string (e.g., 1.4.8b), and
where:
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:
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:
This header is also returned when -check_fail is requested, but only if
access is not granted.
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)
If enabled by the ACS_EMIT_APPROVAL[67] 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). Note that if a man-in-the-middle attack is of
concern, end-to-end encryption should 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)[68], 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:
The dacs64-approval-message is a dacs64[33] 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:
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()[69]) 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:
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()[70] for
information about message digest algorithms):
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"
DIAGNOSTICS¶
The program exits 0 if everything was fine, 1 if an error occurred.SEE ALSO¶
dacsacl(1)[43], dacscheck(1)[2], dacs.acls(5)[4], dacs.conf(5)[47], dacs_admin(8)[44]BUGS¶
While the DACS_ACS mechanism can be useful, it is still a kludge,AUTHOR¶
Distributed Systems Software ( www.dss.ca[71])COPYING¶
Copyright2003-2013 Distributed Systems Software. See the LICENSE[72] file that accompanies the distribution for licensing information.NOTES¶
- 1.
- dacsoptions
- 2.
- dacscheck(1)
- 3.
- mod_auth_dacs
- 4.
- dacs.acls(5)
- 5.
- logging
- 6.
- LOG_LEVEL
- 7.
- LOG_FILTER
- 8.
- AddDACSAuth
- 9.
- DACS_HOME
- 10.
- pipe(2)
- 11.
- Variables Available To Rules
- 12.
- mod_auth_dacs
- 13.
- ALLOW_HTTP_COOKIE
- 14.
- RFC 2617
- 16.
- dacsrlink(1)
- 17.
- RLINK
- 18.
- the one used for normal rules
- 19.
- concise user identity
- 20.
- identity element
- 21.
- DACS_ACS argument
- 22.
- redirect()
- 23.
- HTTP_AUTH_ENABLE
- 24.
- HTTP_AUTH
- 25.
- Auth clause directives
- 26.
- local_apache_authenticate
- 27.
- ACS_ERROR_HANDLER
- 28.
- AUTH_SUCCESS_HANDLER
- 29.
- AUTH_ERROR_HANDLER
- 30.
- RFC 2616
- 31.
- dacshttp(1)
- 32.
- passed using this request-header
- 33.
- dacs.exprs(5)
- 34.
- COOKIE_PATH
- 35.
- COOKIE_NO_DOMAIN
- 36.
- COOKIE_HTTP_ONLY
- 37.
- dacs.install(7)
- 38.
- ACS_ACCESS_TOKEN_ENABLE
- 39.
- ACS_ACCESS_TOKEN_LIFETIME_LIMIT
- 40.
- ACS_ACCESS_TOKEN_LIFETIME_SECS
- 41.
- dacs.acls(5)
- 42.
- tail matching
- 43.
- dacsacl(1)
- 44.
- dacs_admin(8)
- 45.
- revocation list
- 46.
- dacs_acs.dtd
- 47.
- dacs.conf(5)
- 48.
- dacs_notices(8)
- 49.
- dacs.exprs(5)
- 50.
- RFC 1867
- 51.
- RFC 2388
- 52.
- HTML 4
- 53.
- ACS_POST_EXCEPTION_MODE
- 54.
- Rlinks
- 55.
- PHP
- 56.
- dacs_prenv(8)
- 57.
- dacs_acs(8)
- 58.
- mod_jk
- 59.
- Tomcat
- 60.
- -invisible
- 61.
- XML Output
- 62.
- FORMAT CGI argument
- 63.
- -format
- 64.
- ACS_PRE_AUTH
- 65.
- DACS-Status-Line
- 66.
- STATUS_LINE
- 67.
- ACS_EMIT_APPROVAL
- 68.
- dacs_uproxy(8)
- 69.
- ustamp()
- 70.
- digest()
- 71.
- www.dss.ca
- 72.
- LICENSE
07/17/2013 | DACS 1.4.28b |