.\" Copyright (c) 2003-2012 .\" Distributed Systems Software. All rights reserved. .\" See the file LICENSE for redistribution information. .\" $Id: copyright-nr 2564 2012-03-02 00:17:08Z brachman $ '\" t .\" Title: dacs_acs .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 08/23/2020 .\" Manual: DACS Web Services Manual .\" Source: DACS 1.4.40 .\" Language: English .\" .TH "DACS_ACS" "8" "08/23/2020" "DACS 1.4.40" "DACS Web Services Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" dacs_acs \- \fBDACS\fR access control service .SH "SYNOPSIS" .HP \w'\fBdacs_acs\fR\fBdacs_acs\fR\ 'u \fBdacs_acs\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR] [\fB\-dcc\fR] [\fB\-proxy\-static\fR] [\fB\-proxy\-exec\fR] .br \fBdacs_acs\fR\fB\-test\fR .SH "DESCRIPTION" .PP This program is part of the \fBDACS\fR suite\&. .PP The \fBDACS\fR access control service, \fBdacs_acs\fR (or simply \fBACS\fR) is responsible for making access control decisions on web service requests\&. It is run by a web server\&. In the current implementation, \fBdacs_acs\fR is executed by the web server as an external program\&. \fBACS\fR provides attribute\- and role\-based access control using the \fBDACS\fR rule\-processing engine, which consults access control rules (also referred to as ACLs) provided with \fBDACS\fR or written by a \fBDACS\fR administrator\&. Because access control is performed on URIs, \fBACS\fR can control access to arbitrary resources, such as web pages, files, or programs\&. .PP A generic interface to \fBDACS\*(Aqs\fR rule processing engine is given by \m[blue]\fBdacscheck(1)\fR\m[]\&\s-2\u[2]\d\s+2\&. .PP A web server runs \fBdacs_acs\fR to determine whether a particular service request is authorized\&. Although in theory any web server that provides appropriate hooks could call \fBdacs_acs\fR, at present only \fBApache\fR 2\&.4\&.x and 2\&.2\&.x web servers are supported\&. A \fBDACS\fR\-aware \fBApache\fR module called \m[blue]\fBmod_auth_dacs\fR\m[]\&\s-2\u[3]\d\s+2 is configured using custom \fBApache\fR directives and runs \fBdacs_acs\fR\&. A web server having \m[blue]\fBmod_auth_dacs\fR\m[]\&\s-2\u[3]\d\s+2 functionality is said to be \fBDACS\fR\-enhanced and web services that are under the control of \m[blue]\fBmod_auth_dacs\fR\m[]\&\s-2\u[3]\d\s+2 are said to be \fBDACS\fR\-wrapped\&. .PP When \fBApache\fR receives a \fBDACS\fR\-wrapped service request, the \fBmod_auth_dacs\fR module is run, which in turn runs \fBdacs_acs\fR to determine whether the request should be granted\&. The module provides \fBdacs_acs\fR 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, \fBdacs_acs\fR consults a set of access control rules (the ruleset) (see \m[blue]\fBdacs\&.acls(5)\fR\m[]\&\s-2\u[4]\d\s+2)\&. Additional contextual information, such as \fBDACS\fR configuration directives and build\-time options, and the run\-time environment, is also available\&. The information returned by \fBdacs_acs\fR to the module either causes \fBApache\fR to grant permission, possibly with a constraint that specifies additional, service\-specific information, or denies permission, possibly with a reason for denial\&. \fBdacs_acs\fR may also instruct the web server to redirect the client\&. .PP All \fBDACS\fR services must be under the control of \fBdacs_acs\fR, even those that do not require the client to be authenticated\&. Also, a web server must be configured such that only \fBDACS\fR\-controlled services and no other services can be invoked through URLs associated with its \fBDACS\fR jurisdiction\&. .PP It is not a requirement that all of a web server\*(Aqs resources be under the control of \fBDACS\fR\&. That is, it is not necessary to \fBDACS\fR\-wrap everything, but it is certainly possible\&. .PP Please refer to the documentation for \m[blue]\fBmod_auth_dacs\fR\m[]\&\s-2\u[3]\d\s+2 for information on configuring the \fBDACS\fR \fBApache\fR module\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBSecurity\fR .ps -1 .br .PP A \fBdacs_acs\fR process, which is created by \fBhttpd\fR, should ordinarily run as the same user id as \fBhttpd\fR\&. File and directory ownership and modes must be set so that it can read its configuration files, access control rules, and so on\&. The \fBDACS\fR 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 \fBDACS\fR cannot be edited or replaced by non\-privileged users\&. In some circumstances, it may be necessary for \fBdacs_acs\fR to run as root, in which case a \fBDACS\fR administrator must be extra careful in this regard\&. .sp .5v .RE .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBTip\fR .ps -1 .br .PP One way to understand what \fBdacs_acs\fR is doing, or to debug it, is to enable the most detailed level of \m[blue]\fBlogging\fR\m[]\&\s-2\u[5]\d\s+2\&. This will emit a copious quantity of output to the \fBDACS\fR log file, so be sure to reduce the logging level and delete the log file when you are finished\&. .PP Setting the \m[blue]\fBLOG_LEVEL\fR\m[]\&\s-2\u[6]\d\s+2 directive to "debug" or "trace" will produce detailed output (although it can be moderated using the \m[blue]\fBLOG_FILTER\fR\m[]\&\s-2\u[7]\d\s+2 directive)\&. LOG_LEVEL has the disadvantage that it cannot take effect until after configuration processing\&. .PP To enable logging output at the earliest possible time, you can add the desired \m[blue]\fB\fIdacsoptions\fR\fR\m[]\&\s-2\u[1]\d\s+2 flags to Apache\*(Aqs \m[blue]\fBAddDACSAuth\fR\m[]\&\s-2\u[8]\d\s+2 directive; for example, by using a directive like the following in httpd\&.conf: .sp .if n \{\ .RS 4 .\} .nf AddDACSAuth dacs\-acs /usr/local/dacs/bin/dacs_acs "\-t \-v" .fi .if n \{\ .RE .\} .sp Note that \fBhttpd\fR must be restarted before changes to this directive take effect\&. .PP An alternative method of enabling detailed logging, equivalent to using the \fB\-t\fR and \fB\-v\fR flags if neither has been specified, is to create a file in the \m[blue]\fBDACS_HOME\fR\m[]\&\s-2\u[9]\d\s+2 directory with the name debug_\fIprogname\fR\&. For example, to enable detailed logging for \fBdacs_acs\fR, the following command might be used: .sp .if n \{\ .RS 4 .\} .nf % touch /usr/local/dacs/debug_dacs_acs .fi .if n \{\ .RE .\} .sp This method takes effect immediately and applies to any \fBDACS\fR web service or command that accepts \m[blue]\fB\fIdacsoptions\fR\fR\m[]\&\s-2\u[1]\d\s+2 at the time they begin execution\&. It overrides the current value of LOG_LEVEL, is more selective because it applies only to \fIprogname\fR (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 \fBhttpd\fR restart\&. .sp .5v .RE .SS "Module\-to\-ACS Protocol" .PP \fBDACS\fR\*(Aqs \m[blue]\fBmod_auth_dacs\fR\m[]\&\s-2\u[3]\d\s+2 module for \fBApache\fR invokes the \fBdacs_acs\fR 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 \fBApache\fR directives, gathering information required to make the access control decision, passing that information to \fBdacs_acs\fR, and receiving the access control decision from \fBdacs_acs\fR, together with either environment information (if access is granted to an executable request) or error handling directives (if access is denied)\&. .PP To prevent potentially sensitive information from becoming visible, \m[blue]\fBmod_auth_dacs\fR\m[]\&\s-2\u[3]\d\s+2 passes information to \fBdacs_acs\fR over an interprocess communication channel (\m[blue]\fBpipe(2)\fR\m[]\&\s-2\u[10]\d\s+2)\&. \fBdacs_acs\fR 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 \fBdacs_acs\fR communicates its decision: zero means the request should be granted, anything else means the request should be denied\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBImportant\fR .ps -1 .br .PP The module provides \fBdacs_acs\fR with its \fBDACS\fR version number to ensure that it is compatible\&. \fBdacs_acs\fR will deny all access to \fBDACS\fR\-wrapped resources if its version number does not exactly match the module\*(Aqs\&. This requirement helps to protect against build or installation mistakes\&. .sp .5v .RE .PP The information passed \fIto\fR \fBdacs_acs\fR \fIfrom\fR \fBApache\fR is in the format: .sp .if n \{\ .RS 4 .\} .nf \fIvariable\-name\fR="\fIvariable\-value\fR" .fi .if n \{\ .RE .\} .sp each of which is terminated by a newline character\&. These variables are listed below\&. For details about how to reference these values, see \m[blue]\fBVariables Available To Rules\fR\m[]\&\s-2\u[11]\d\s+2\&. .PP \fISERVICE_ARGS\fR .RS 4 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\&. .RE .PP \fISERVICE_ARGS_TRUNCATED\fR .RS 4 For POST method requests, if the POST data stream (i\&.e\&., the request\*(Aqs entity\-body) was not completely captured, such as if the maximum length was reached, this variable will be present and assigned the value 1\&. .RE .PP \fISERVICE_AUTHORIZATION\fR .RS 4 The value of the Authorization HTTP header field, if present\&. .RE .PP \fISERVICE_CONTENT_ENCODING\fR .RS 4 The value of the Content\-Encoding HTTP header field, if present\&. .RE .PP \fISERVICE_CONTENT_LENGTH\fR .RS 4 The value of the Content\-Length HTTP header field, if present\&. .RE .PP \fISERVICE_CONTENT_TYPE\fR .RS 4 The value of the Content\-Type HTTP header field, if present\&. .RE .PP \fISERVICE_COOKIE\fR .RS 4 The value of the Cookie HTTP header field, if present\&. .RE .PP \fISERVICE_FILENAME\fR .RS 4 The name of the file, as determined by \fBApache\fR, corresponding to this response\&. .RE .PP \fISERVICE_HOSTNAME\fR .RS 4 The name of the host as set by the full URI or Host HTTP header field, as determined by \fBApache\fR\&. .RE .PP \fISERVICE_HTTPS\fR .RS 4 If the request came over SSL/TLS (HTTPS), this variable will be present and set to "on"\&. .RE .PP \fISERVICE_METHOD\fR .RS 4 The request method, as set by \fBApache\fR (e\&.g\&., "GET")\&. .RE .PP \fISERVICE_MOD_AUTH_DACS_VERSION\fR .RS 4 The DACS version number string associated with the \m[blue]\fBmod_auth_dacs\fR\m[]\&\s-2\u[3]\d\s+2 module\&. .RE .PP \fISERVICE_PATH_INFO\fR .RS 4 The \fBPATH_INFO\fR part of the URI, as set by \fBApache\fR\&. .RE .PP \fISERVICE_POSTDATA\fR .RS 4 When available, the POST data stream (the HTTP message body) (or part of it: see the description of the SetDACSAuthPostBuffer directive to \m[blue]\fBmod_auth_dacs\fR\m[]\&\s-2\u[12]\d\s+2)\&. It is MIME base\-64 encoded\&. .RE .PP \fISERVICE_PROXY_AUTH\fR .RS 4 The value of the DACS\-Proxy\-Authorization HTTP header field, if present\&. (Not currently used)\&. .RE .PP \fISERVICE_PROXYREQ\fR .RS 4 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"\&. .RE .PP \fISERVICE_QUERY\fR .RS 4 The value of the query string component of the URI\&. .RE .PP \fISERVICE_REMOTE_ADDR\fR .RS 4 The client\*(Aqs IP address\&. .RE .PP \fISERVICE_REMOTE_HOST\fR .RS 4 The client\*(Aqs DNS name, if known by \fBApache\fR\&. .RE .PP \fISERVICE_SERVER_PORT\fR .RS 4 The TCP/IP port on which the request was received by \fBApache\fR\&. .RE .PP \fISERVICE_URI\fR .RS 4 The path portion of the URI, as determined by \fBApache\fR\&. .RE .PP \fISERVICE_USER_AGENT\fR .RS 4 The value of the User\-Agent HTTP header field, if present\&. .RE .PP If access is granted, \fBdacs_acs\fR may provide a set of control directives for \m[blue]\fBmod_auth_dacs\fR\m[]\&\s-2\u[3]\d\s+2 to interpret, followed by a set of environment variables for \m[blue]\fBmod_auth_dacs\fR\m[]\&\s-2\u[3]\d\s+2 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: .sp .if n \{\ .RS 4 .\} .nf \fIvariable\-name\fR=\fIvariable\-value\fR .fi .if n \{\ .RE .\} .sp each of which is terminated by a newline character\&. .PP If access is denied, \fBdacs_acs\fR may instead provide an error handling directive, newline terminated, in the form expected as the third argument to \fBApache\fR\*(Aqs \fBap_custom_response()\fR function\&. .SS "Credentials" .PP \fBDACS\fR credentials can be passed to \fBdacs_acs\fR in several ways, but they have the following representation: .sp .if n \{\ .RS 4 .\} .nf DACS:\fIfederation\-name\fR::[\fIjurisdiction\-name\fR]:[\fIusername\fR]=\fIvalue\fR[; \&.\&.\&.] .fi .if n \{\ .RE .\} .sp If the \fIjurisdiction\-name\fR is omitted, the \fIusername\fR must also be omitted (see \m[blue]\fBCOOKIE_NAME_TERMINATORS\fR\m[]\&\s-2\u[13]\d\s+2)\&. The string is URL encoded\&. If there are multiple credentials, they are separated by any combination of spaces and ";" characters\&. .PP Credentials are passed from \m[blue]\fBmod_auth_dacs\fR\m[]\&\s-2\u[3]\d\s+2 to \fBdacs_acs\fR using the \fISERVICE_COOKIE\fR variable (transmitted over a \m[blue]\fBpipe(2)\fR\m[]\&\s-2\u[10]\d\s+2) .PP Because a process\*(Aqs environment is public on some systems, \fBDACS\fR takes care not to pass credentials using environment variables\&. Passing credentials through the \fBHTTP_COOKIE\fR environment variable is forbidden unless enabled by the \m[blue]\fBALLOW_HTTP_COOKIE\fR\m[]\&\s-2\u[14]\d\s+2 directive\&. When specifically enabled by a rule\*(Aqs attribute, they can be passed using the \fBDACS_COOKIE\fR environment variable (see the pass_credentials attribute described in \m[blue]\fBdacs\&.acls(5)\fR\m[]\&\s-2\u[4]\d\s+2)\&. .PP If an HTTP Authorization header is used with the "DACS" authentication scheme, the "basic\-credentials" component of the header may contain \fBDACS\fR credentials\&. Please refer to \m[blue]\fBRFC 2617\fR\m[]\&\s-2\u[15]\d\s+2\&. These credentials have the format given above but are also base\-64 encoded\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBSecurity\fR .ps -1 .br .PP It is forbidden to submit multiple credentials for the same identity to \fBDACS\fR and such a request will trigger an error\&. .PP It is also forbidden to submit multiple \fBDACS\fR authentication cookies with the same cookie name\&. .sp .5v .RE .PP Please refer to \m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[16]\d\s+2 for additional information\&. .SS "Rlinks" .PP \fBDACS\fR 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 \fBDACS\fR, the request itself (indirectly) specifies authorization constraints that \fBDACS\fR must apply to the request\&. Optionally, a \fBDACS\fR identity and other information can be included in the Rlink\&. .PP 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 \fBDACS\fR\-wrapped\&. In other words, a request that is recognized as an Rlink essentially says "use the rule identified by this request\*(Aqs 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\&. .PP In typical usage, an Rlink is created (probably, but not necessarily by \m[blue]\fBdacsrlink(1)\fR\m[]\&\s-2\u[17]\d\s+2) 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\&. .PP 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\*(Aqs 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\*(Aqs rule can be changed or deleted by its owner at any time, even after it has been distributed\&. .PP 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\&. .PP 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 \m[blue]\fBredirect()\fR\m[]\&\s-2\u[18]\d\s+2 function\&. The URL can be changed at will simply by editing the Rlink\*(Aqs rule\&. The Rlink need not be kept secret when it is used for this purpose\&. .PP 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\*(Aqs 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\*(Aqs IP address, and so on\&. Also, an Rlink cannot be used to gain access to a resource that is not described by its rule\*(Aqs services element\&. .sp .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBRlink Details\fR .RS 4 .PP 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\&. \m[blue]\fBRLINK\fR\m[]\&\s-2\u[19]\d\s+2 directives can map Rnames to the same or different namespaces, depending on the filestore selected by a directive\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .PP 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\&. .PP If a rule contains the optional name attribute, the attribute value must exactly match the Rname\&. .PP The base name of a file containing an Rlink will be its Rname\&. This naming scheme is different from \m[blue]\fBthe one used for normal rules\fR\m[]\&\s-2\u[20]\d\s+2\&. .sp .5v .RE .PP 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 \fBDACS\fR authentication (i\&.e\&., there may or may not be an account associated with them); \fBDACS\fR administrators should keep this mind to avoid any confusion\&. .PP An Rname may be followed by a suffix that directly or indirectly associates a \fBDACS\fR identity with the Rlink\&. For want of a better name, this composite identifier is called an RnameIdent and has the following syntax: .sp .if n \{\ .RS 4 .\} .nf \fIRnameIdent\fR \-> \fIRname\fR \*(Aq:\*(Aq \fIident\fR | \fIRname\fR \*(Aq;\*(Aq \fIiptr\fR .fi .if n \{\ .RE .\} .PP In the \fIdirect\fR mode of identity attachment, the Rname is followed by a separator (a colon, which cannot appear in an Rname) and \fIident\fR, a cryptographically protected and base\-64 encoded \m[blue]\fBconcise user identity\fR\m[]\&\s-2\u[21]\d\s+2 that is created by \m[blue]\fBdacsrlink(1)\fR\m[]\&\s-2\u[17]\d\s+2\&. These encrypted identities are \fInot\fR the same as encrypted credentials\&. Different encrypted identifiers may represent exactly the same identity\&. If \fBDACS\fR recognizes the Rname, when it performs authorization checking it will do so assuming the specified identity, \fIignoring any other credentials that might have accompanied the request\fR\&. .PP In the \fIindirect\fR mode, the Rname is followed by a different separator (a semi\-colon, which cannot appear in an Rname) and an arbitrary string, called an \fIiptr\fR (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 \fIiptr\fR: 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 \m[blue]\fBidentity element\fR\m[]\&\s-2\u[22]\d\s+2, and the identity is used in the same way as in the direct mode\&. Like an Rname, in typical usage an \fIiptr\fR 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\&. .PP An identity obtained using either attachment mode is tested for revocation\&. .PP The Rname, specified identity, and identity pointer are accessible in the \m[blue]\fB\fIDACS\fR namespace\fR\m[]\&\s-2\u[11]\d\s+2, when they are available, as \fI${DACS::RNAME}\fR, \fI${DACS::RIDENT}\fR, and \fI${DACS::RIPTR}\fR, respectively\&. .PP Rlinks can easily be created manually or by a custom program, but the \m[blue]\fBdacsrlink(1)\fR\m[]\&\s-2\u[17]\d\s+2 utility provides a simple interface to create and administer them\&. Rules created by \fBdacsrlink\fR can be manually edited and deleted just like any other rule\&. There is no \fIa priori\fR limit on the lifetime of an Rlink; it continues to exist as far as \fBDACS\fR 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\&. .PP An Rname can be presented as an ordinary web service argument, as a component of the request URI, or via the special \m[blue]\fBDACS_ACS argument\fR\m[]\&\s-2\u[23]\d\s+2: .sp .if n \{\ .RS 4 .\} .nf 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 .fi .if n \{\ .RE .\} .sp 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 \fIDACS_ACS\fR argument allows the Rname to be used during access control testing but completely hidden from the requested resource\&. .PP \m[blue]\fBRLINK\fR\m[]\&\s-2\u[19]\d\s+2 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 \fBDACS\fR rulesets for an applicable rule occurs\&. If no RLINK directive finds an Rname, normal access control processing occurs\&. .RE .SS "HTTP Authentication" .PP \fBdacs_acs\fR can be configured to trigger HTTP authentication (see \m[blue]\fBRFC 2617\fR\m[]\&\s-2\u[15]\d\s+2) 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)\&. .PP If \fBdacs_acs\fR denies access because the user is not authenticated (code \fB902\fR, 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 \fBDACS\fR will try to use the \m[blue]\fBRFC 2617\fR\m[]\&\s-2\u[15]\d\s+2 protocol to have \fBdacs_authenticate\fR authenticate the user\&. .PP Also see \m[blue]\fBautologin(8)\fR\m[]\&\s-2\u[24]\d\s+2\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBTip\fR .ps -1 .br .PP This feature is configured through the \m[blue]\fBHTTP_AUTH_ENABLE\fR\m[]\&\s-2\u[25]\d\s+2 and \m[blue]\fBHTTP_AUTH\fR\m[]\&\s-2\u[26]\d\s+2 directives, some configuration variables, and \m[blue]\fBAuth clause directives\fR\m[]\&\s-2\u[27]\d\s+2\&. Please refer to them for details\&. .PP When HTTP authentication is triggered in this way, \fIno extra \fR\fI\fBApache\fR\fR\fI configuration needs to be done or should be done\fR\&. All that is required of \fBApache\fR is that the resource that should trigger authentication be \fBDACS\fR\-wrapped\&. .PP \fIAny\fR password style authentication module, or the CAS authentication module, can be configured in conjunction with \fBDACS\*(Aqs\fR HTTP Basic authentication (\m[blue]\fBRFC 2617\fR\m[]\&\s-2\u[15]\d\s+2)\&. That is, \fBDACS\fR 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 \fIUSERNAME\fR and \fIPASSWORD\fR arguments to \fBdacs_authenticate\fR\&. The authentication module on the backend of the authentication procedure can use any type of \fBApache\fR password file or \fBDACS\fR password file, NTLM, CAS, etc\&. .PP Besides authenticating against an \fBApache\fR password file created by \fBhtpasswd\fR, \fBhtdigest\fR, or \fBhtdbm\fR, this means that an ordinary browser can be used to capture a username and password for any \fBDACS\fR authentication module that requires it\&. Please refer to the description of the \m[blue]\fBlocal_apache_authenticate\fR\m[]\&\s-2\u[28]\d\s+2 module for details\&. .sp .5v .RE .PP If the feature is enabled and applies to a request: .sp .RS 4 .ie n \{\ \h'-04' 1.\h'+01'\c .\} .el \{\ .sp -1 .IP " 1." 4.2 .\} any \m[blue]\fBACS_ERROR_HANDLER\fR\m[]\&\s-2\u[29]\d\s+2, \m[blue]\fBAUTH_SUCCESS_HANDLER\fR\m[]\&\s-2\u[30]\d\s+2, and \m[blue]\fBAUTH_ERROR_HANDLER\fR\m[]\&\s-2\u[31]\d\s+2 directives that would ordinarily apply are overridden\&. .RE .sp .RS 4 .ie n \{\ \h'-04' 2.\h'+01'\c .\} .el \{\ .sp -1 .IP " 2." 4.2 .\} the \m[blue]\fBHTTP_AUTH\fR\m[]\&\s-2\u[26]\d\s+2 directive that applies to the request specifies the authentication scheme, realm, and any additional authentication parameters\&. .RE .sp .RS 4 .ie n \{\ \h'-04' 3.\h'+01'\c .\} .el \{\ .sp -1 .IP " 3." 4.2 .\} a WWW\-Authenticate response header is returned to the browser\&. For example, for HTTP Basic authentication this header might look like: .sp .if n \{\ .RS 4 .\} .nf WWW\-Authenticate: Basic realm="My Realm" .fi .if n \{\ .RE .\} .sp .RE .sp .RS 4 .ie n \{\ \h'-04' 4.\h'+01'\c .\} .el \{\ .sp -1 .IP " 4." 4.2 .\} an HTTP status value of \fB401\fR (\m[blue]\fBRFC 2616\fR\m[]\&\s-2\u[32]\d\s+2) is returned\&. If the variable \fI${Conf::http_auth_message}\fR 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\&. .RE .sp .RS 4 .ie n \{\ \h'-04' 5.\h'+01'\c .\} .el \{\ .sp -1 .IP " 5." 4.2 .\} if the variable \fI${Conf::http_auth_jurisdiction}\fR is configured, it is expected to be the name of the jurisdiction (within the current federation) at which \fBdacs_authenticate\fR is to be invoked to authenticate the user; if the variable is undefined, the name of the current jurisdiction is used\&. .RE .PP The values of some of these variables are neither examined by \fBDACS\fR nor meaningful to it\&. For example, all that \fBDACS\fR requires of the realm string is that it be syntactically valid\&. .PP When enabled, the following flow of control occurs: .sp .RS 4 .ie n \{\ \h'-04' 1.\h'+01'\c .\} .el \{\ .sp -1 .IP " 1." 4.2 .\} The user hits a \fBDACS\fR\-wrapped URL when not authenticated; if \fBdacs_acs\fR is configured to perform HTTP authentication for the request, it returns a \fB401\fR ("Unauthorized") status code and a WWW\-Authenticate header; .RE .sp .RS 4 .ie n \{\ \h'-04' 2.\h'+01'\c .\} .el \{\ .sp -1 .IP " 2." 4.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; .RE .sp .RS 4 .ie n \{\ \h'-04' 3.\h'+01'\c .\} .el \{\ .sp -1 .IP " 3." 4.2 .\} \fBdacs_acs\fR again denies the request because the user is not authenticated, but sees an Authorization header and redirects the user to \fBdacs_authenticate\fR (at \fI${Conf::http_auth_jurisdiction}\fR or the current jurisdiction) with arguments necessary for the selected authentication scheme; \fBdacs_authenticate\fR maps the given username (and password, if available) to the \fIUSERNAME\fR argument (and possibly the \fIPASSWORD\fR argument) and invokes authentication modules as necessary; .RE .sp .RS 4 .ie n \{\ \h'-04' 4.\h'+01'\c .\} .el \{\ .sp -1 .IP " 4." 4.2 .\} If authentication succeeds, credentials are issued and the user is redirected to the original request (via the GET method); .RE .sp .RS 4 .ie n \{\ \h'-04' 5.\h'+01'\c .\} .el \{\ .sp -1 .IP " 5." 4.2 .\} If authentication fails, the procedure is repeated from the beginning\&. .RE .sp .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBImportant\fR .ps -1 .br .PP The main advantages of HTTP Basic and Digest authentication (\m[blue]\fBRFC 2617\fR\m[]\&\s-2\u[15]\d\s+2) 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: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} 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 \fBDACS\fR and in the same browser session visits a link that triggers authentication, \fBDACS\fR credentials may be automatically re\-issued without prompting\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} 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\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} 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 \fIeach time\fR 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\&. .RE .PP With Digest authentication, various aspects of the authentication protocol are subject to time limits as a security measure\&. The configuration variable \fI${Conf::http_auth_timeout_secs}\fR can be set to the number of seconds for which a nonce is valid, thereby overriding the default; only advanced administrators familiar with \m[blue]\fBRFC 2617\fR\m[]\&\s-2\u[15]\d\s+2 should change the default\&. .sp .5v .RE .PP The following is an example of configuration that might appear in the appropriate section (or sections) in \fBDACS\fR configuration files: .sp .if n \{\ .RS 4 .\} .nf HTTP_AUTH_ENABLE "yes" HTTP_AUTH "Basic \e"Doggies\e" /basic/*" EVAL ${Conf::http_auth_message} = \e "902 https://example\&.com/cgi\-bin/dacs/dacs_authenticate" .fi .if n \{\ .RE .\} .sp 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: .sp .if n \{\ .RS 4 .\} .nf WWW\-Authenticate: Basic realm="Doggies" Status: 401 .fi .if n \{\ .RE .\} .sp and the message body will contain the single line: .sp .if n \{\ .RS 4 .\} .nf 902 https://example\&.com/cgi\-bin/dacs/dacs_authenticate .fi .if n \{\ .RE .\} .PP Instead of enabling the feature for \fIall\fR 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 \fBDACS\fR \m[blue]\fBdacshttp(1)\fR\m[]\&\s-2\u[33]\d\s+2 utility)\&. .sp .if n \{\ .RS 4 .\} .nf HTTP_AUTH_ENABLE = regmatch("${DACS::USER_AGENT}", "DACS\-http/\&.*") ? "yes" : "no" .fi .if n \{\ .RE .\} .sp A similar expression would enable the feature only for \fBInternet Explorer\fR, \fBMozilla\fR, \fBcurl\fR, \m[blue]\fBdacshttp(1)\fR\m[]\&\s-2\u[33]\d\s+2, 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\&. .PP Although \m[blue]\fBRFC 2617\fR\m[]\&\s-2\u[15]\d\s+2 allows multiple WWW\-Authenticate response\-headers to be returned, this mechanism can only send one\&. .PP When provided by a user agent, \fBdacs_acs\fR makes the value of the Authorization request\-header available to access control rules through the \fI${DACS::AUTHORIZATION}\fR variable\&. \fBDACS\fR credentials can also be \m[blue]\fBpassed using this request\-header\fR\m[]\&\s-2\u[34]\d\s+2\&. .SS "Authorization Caching" .PP After a rule grants access, \fBdacs_acs\fR 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 \fBDACS\fR that if the rule grants access to a particular user, then it is safe for \fBDACS\fR to assume that future requests for the same resource by the same user should be granted without doing a complete authorization check\&. .PP This mechanism offers improved performance in cases where: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} 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); .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} rule evaluation is relatively slow or expensive; .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} there are a large number of rules and/or rule retrieval is relatively slow; .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} re\-evaluation of the rule is unnecessary (e\&.g\&., the rule does not update any state information) .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} it is acceptable for changes to the ruleset to not immediately affect cachable decisions .RE .sp .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBSecurity\fR .ps -1 .br .PP 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\&. .sp .5v .RE .PP 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 \fBdacs_acs\fR\&. 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, \fBdacs_acs\fR 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, \fBdacs_acs\fR will ask for them to be deleted (i\&.e\&., it unsets the cookies)\&. These cookies have the following format: .sp .if n \{\ .RS 4 .\} .nf DACS:\fIfederation\-name\fR::\fIjurisdiction\-name\fR::TOKEN\-\fIunique\fR .fi .if n \{\ .RE .\} .sp Here, \fIunique\fR is the "dacs64" encoding (see \m[blue]\fBdacs\&.exprs(5)\fR\m[]\&\s-2\u[35]\d\s+2) of a cryptographically strong pseudo\-random 16 byte value\&. Also see the \m[blue]\fBCOOKIE_NAME_TERMINATORS\fR\m[]\&\s-2\u[13]\d\s+2 directive\&. Since access control is purely a jurisdictional responsibility in \fBDACS\fR, a cookie is meaningful only to the jurisdiction that issues it\&. .PP These cookies are non\-persistent (they are supposed to disappear when a browser session ends)\&. The value of \m[blue]\fBCOOKIE_PATH\fR\m[]\&\s-2\u[36]\d\s+2, or "/", determines the cookie\*(Aqs path attribute\&. The \m[blue]\fBCOOKIE_NO_DOMAIN\fR\m[]\&\s-2\u[37]\d\s+2 and \m[blue]\fBCOOKIE_HTTP_ONLY\fR\m[]\&\s-2\u[38]\d\s+2 directives are also honoured\&. .PP Here is a simple example of how \fBDACS\fR might be configured to enable authorization caching for a particular resource\&. The jurisdiction\*(Aqs dacs\&.conf would include directives similar to the following: .sp .if n \{\ .RS 4 .\} .nf ACS_ACCESS_TOKEN_ENABLE "yes" ACS_ACCESS_TOKEN_LIFETIME_SECS "43200" VFS "[tokens]dacs\-kwv\-fs:/usr/local/dacs/conf/tokens" .fi .if n \{\ .RE .\} .sp A rule for the resource might look like this: .sp .if n \{\ .RS 4 .\} .nf user("auth") .fi .if n \{\ .RE .\} .sp 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\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .PP In the current implementation, each access token is contained within its own cookie, rather than a jurisdiction collecting all of the user\*(Aqs 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\&. .sp .5v .RE .PP Before it can be used, \fBDACS\fR must be built with the feature enabled (see \fB\-\-enable\-access\-tokens\fR in \m[blue]\fBdacs\&.install(7)\fR\m[]\&\s-2\u[39]\d\s+2)\&. 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 \m[blue]\fBACS_ACCESS_TOKEN_ENABLE\fR\m[]\&\s-2\u[40]\d\s+2, \m[blue]\fBACS_ACCESS_TOKEN_LIFETIME_LIMIT\fR\m[]\&\s-2\u[41]\d\s+2, and \m[blue]\fBACS_ACCESS_TOKEN_LIFETIME_SECS\fR\m[]\&\s-2\u[42]\d\s+2)\&. .PP Enabling the feature in a particular context also requires setting a rule\*(Aqs permit_caching attribute to "yes" (see \m[blue]\fBdacs\&.acls(5)\fR\m[]\&\s-2\u[43]\d\s+2)\&. Whenever access is granted because of the rule, authorization caching of the rule is possible\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .PP Only the url_pattern of the rule\*(Aqs 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)\&. .PP Although a service request\*(Aqs 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\&. .PP 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\&. .sp .5v .RE .PP Authorization caching is possible irrespective of whether a user has been authenticated\&. Caching is not allowed, however, in cases where the granting rule uses \m[blue]\fBtail matching\fR\m[]\&\s-2\u[44]\d\s+2 \fIand\fR 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\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .PP 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\&. .sp .5v .RE .PP 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\&. .PP 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 \m[blue]\fBdacsacl(1)\fR\m[]\&\s-2\u[45]\d\s+2 command and \m[blue]\fBdacs_admin(8)\fR\m[]\&\s-2\u[46]\d\s+2 service can perform administrative functions on the entry database\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBSecurity\fR .ps -1 .br .PP 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\&. .PP 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\&. .PP As with cookies bearing \fBDACS\fR credentials, cookies containing access tokens must be kept private\&. For an authenticated user, an attacker would need to acquire an access token \fIand all credentials\fR 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\&. .PP It is the administrator\*(Aqs responsibility to ensure that authorization caching does not break the intended semantics of a rule \- \fBDACS\fR 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\&. .PP 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 \m[blue]\fBrevocation list\fR\m[]\&\s-2\u[47]\d\s+2 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\&. .sp .5v .RE .SS "XML Output" .PP When XML output has been enabled, \fBdacs_acs\fR will emit a document (conforming to \m[blue]\fBdacs_acs\&.dtd\fR\m[]\&\s-2\u[48]\d\s+2) when access is denied, a processing error occurs, or when an access testing mode has been requested using the \fIDACS_ACS\fR argument\&. .PP \fBdacs_acs\fR 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 \m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[49]\d\s+2)\&. 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\&. .PP The event905 element corresponds to the ACK_NEEDED (equivalent to error code \fB905\fR) \fBDACS\fR 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 \m[blue]\fBdacs_notices(8)\fR\m[]\&\s-2\u[50]\d\s+2 and \m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[49]\d\s+2 for additional detail\&. .PP A common_status element indicates that \fBdacs_acs\fR could not process the request\&. This might happen, for example, if \fBdacs_acs\fR were not properly configured\&. .SS "Variables Available To Rules" .PP \fBdacs_acs\fR predefines several variables that may be accessed by rules\&. Additionally, variables obtained from the request\*(Aqs 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\&. .PP 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: .sp .if n \{\ .RS 4 .\} .nf \&.\&.\&./cgi\-bin/foo?A=hello&B=world .fi .if n \{\ .RE .\} .sp the variables \fI${Args::A}\fR with the value hello and \fI${Args::B}\fR 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\&., \fI${DACS::JURISDICTION}\fR)\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .PP 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 \fI${Args::ARG}\fR: .sp .if n \{\ .RS 4 .\} .nf \&.\&.\&./cgi\-bin/foo?ARG=hello&ARG=world .fi .if n \{\ .RE .\} .sp 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\&. .PP 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\&. .sp .5v .RE .PP From these sources, the execution environment, and from the \fBDACS\fR configuration, \fBdacs_acs\fR automatically creates four "classes" of variables: CGI parameter variables, configuration variables, environment variables, and request\-specific variables created by \fBDACS\fR\&. These classes are called namespaces; please refer to \m[blue]\fBdacs\&.exprs(5)\fR\m[]\&\s-2\u[51]\d\s+2 for details\&. For example, the value of a CGI parameter is accessed by \fI${Args::\fR\fI\fIvarname\fR\fR\fI}\fR, the value of a \fBDACS\fR context variable is accessed by \fI${DACS::\fR\fI\fIvarname\fR\fR\fI}\fR (e\&.g\&., \fI${DACS::JURISDICTION}\fR), and the value of configuration variable is obtained using \fI${Conf::\fR\fI\fIvarname\fR\fR\fI}\fR (e\&.g\&., \fI${Conf::FEDERATION_DOMAIN}\fR)\&. .sp .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBStandard Environment Variables\fR .RS 4 .PP For \fBdacs_acs\fR, the \fIEnv\fR namespace is comprised of CGI variables exported by \fBApache\fR, which includes HTTP request variables such as \fI${Env::HTTP_USER_AGENT}\fR\&. The values of recognized headers that might compromise security are edited or deleted\&. \fBApache\fR 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 \fI${Env::AUGGIE}\fR having the value "Doggie": .sp .if n \{\ .RS 4 .\} .nf % dacshttp \-header Auggie Doggie https://example\&.com/cgi\-bin/dacs/someprog .fi .if n \{\ .RE .\} .sp For other programs, the \fIEnv\fR namespace is populated from the program\*(Aqs normal environment\&. .PP These namespaces are reserved from other uses and their contents are, for the most part, read\-only\&. .PP 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 \m[blue]\fBRFC 1867\fR\m[]\&\s-2\u[52]\d\s+2, \m[blue]\fBRFC 2388\fR\m[]\&\s-2\u[53]\d\s+2, and \m[blue]\fBHTML 4\fR\m[]\&\s-2\u[54]\d\s+2\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .PP In some contexts, Apache\*(Aqs \fBPATH_TRANSLATED\fR environment variable is not passed to \fBdacs_acs\fR (it is still available as unusual to CGI programs)\&. .sp .5v .RE .RE .sp .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBExported DACS Variables\fR .RS 4 .PP The following variables are exported to the "\fIDACS\fR" namespace (e\&.g\&., \fI${DACS::QUERY}\fR)\&. Upper and lower case are distinct in variable names\&. These values are either obtained from \fBApache\fR or are elements of the client\*(Aqs credentials\&. .PP \fIACS\fR .RS 4 If \fBdacs_acs\fR is requested to test access, this variable will be defined and have the value of the \fIDACS_ACS\fR argument\&. .RE .PP \fIARGS\fR .RS 4 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 \fIARGS_TRUNCATED\fR will be defined and have a non\-zero value\&. .RE .PP \fIARGS_TRUNCATED\fR .RS 4 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 \fBdacs_acs\fR and the value of one argument may have been truncated\&. See \m[blue]\fBACS_POST_EXCEPTION_MODE\fR\m[]\&\s-2\u[55]\d\s+2\&. .RE .PP \fIARG_COUNT\fR .RS 4 The number of arguments available in the \fIArgs\fR namespace\&. If there are four arguments in a request\*(Aqs query string and two arguments within its application/x\-www\-form\-urlencoded message body, for instance, then the value of \fI${DACS::ARG_COUNT}\fR will be six\&. These arguments will be available collectively as the value of \fI${DACS::ARGS}\fR and individually in the \fIArgs\fR namespace\&. .RE .PP \fIAUTHORIZATION\fR .RS 4 The value of the Authorization HTTP header field, if available\&. .RE .PP \fICONTENT_ENCODING\fR .RS 4 The value of the Content\-Encoding HTTP header field, if available\&. .RE .PP \fICONTENT_LENGTH\fR .RS 4 The value of the Content\-Length HTTP header field, if available\&. .RE .PP \fICONTENT_TYPE\fR .RS 4 The value of the Content\-Type HTTP header field, if available\&. .RE .PP \fICURRENT_URI\fR .RS 4 The full URI for the requested resource, including any query component\&. .RE .PP \fICURRENT_URI_NO_QUERY\fR .RS 4 The full URI for the requested resource, excluding any query component\&. .RE .PP \fIFEDERATION\fR .RS 4 The official name of the federation to which \fIJURISDICTION\fR belongs\&. If the user was not authenticated, this variable will be undefined\&. .RE .PP \fIFILENAME\fR .RS 4 The full path of the file corresponding to the URL being invoked, equivalent to \fBApache\fR\*(Aqs \fBSCRIPT_FILENAME\fR environment variable or its \fIREQUEST_FILENAME\fR variable\&. .RE .PP \fIIDENTITY\fR .RS 4 The \fBDACS\fR identity (the username component plus federation and jurisdiction components) if the user was authenticated, otherwise undefined\&. .RE .PP \fIINTERACTIVE\fR .RS 4 If the standard input is a valid terminal type device, this variable is set to 1, otherwise it is undefined\&. .RE .PP \fIIP\fR .RS 4 The IP address, in standard numeric dot notation, associated with \fIUSERNAME\fR\&. If the user was not authenticated, this variable will be undefined\&. .RE .PP \fIJURISDICTION\fR .RS 4 The official, abbreviated name of the jurisdiction that authenticated \fIUSERNAME\fR\&. If the user was not authenticated, this variable will be undefined\&. .RE .PP \fIMETHOD\fR .RS 4 The method used to invoke the URL, equivalent to \fBApache\fR\*(Aqs \fBREQUEST_METHOD\fR environment variable\&. .RE .PP \fIPATH_INFO\fR .RS 4 The \fBPATH_INFO\fR part of the URI, as set by \fBApache\fR\&. .RE .PP \fIPOSTDATA\fR .RS 4 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 \fIARGS_TRUNCATED\fR will be defined and have a non\-zero value\&. See the description of the SetDACSAuthPostBuffer directive to \m[blue]\fBmod_auth_dacs\fR\m[]\&\s-2\u[12]\d\s+2)\&. .RE .PP \fIPROXYREQ\fR .RS 4 If set, the type of proxy processing performed for this request by Apache (from \fISERVICE_PROXYREQ\fR)\&. .RE .PP \fIQUERY\fR .RS 4 The query string, if any, that was appended to the URL\&. .RE .PP \fIREMOTE_ADDR\fR .RS 4 The \fBREMOTE_ADDR\fR, as set by \fBApache\fR\&. .RE .PP \fIREMOTE_HOST\fR .RS 4 The \fBREMOTE_HOST\fR, as set by \fBApache\fR\&. .RE .PP \fIRIDENT\fR .RS 4 The Rlink identity, if any, associated with the rule currently being evaluated\&. See \m[blue]\fBRlinks\fR\m[]\&\s-2\u[56]\d\s+2\&. .RE .PP \fIRIPTR\fR .RS 4 The Rlink identity pointer, if any, associated with the rule currently being evaluated\&. See \m[blue]\fBRlinks\fR\m[]\&\s-2\u[56]\d\s+2\&. .RE .PP \fIRNAME\fR .RS 4 The Rname, if any, associated with the rule currently being evaluated\&. This is also available as \fI${Args::RNAME}\fR\&. See \m[blue]\fBRlinks\fR\m[]\&\s-2\u[56]\d\s+2\&. .RE .PP \fIROLES\fR .RS 4 The role string associated with \fIUSERNAME\fR\&. If the user was not authenticated, this variable will be undefined\&. .RE .PP \fIURI\fR and \fIURL\fR .RS 4 The URL being invoked\&. .RE .PP \fIUSERNAME\fR .RS 4 The username (without any federation or jurisdiction component)\&. If the user was not authenticated, this variable will be undefined\&. .RE .PP \fIUSER_AGENT\fR .RS 4 When provided by the user agent, this is equivalent to the HTTP User\-Agent request\-header field and \fBHTTP_USER_AGENT\fR environment variable provided by \fBApache\fR\&. When an actual value is unavailable, this variable is set to "unknown"\&. .RE .RE .SS "Exported Environment Variables" .PP The normal execution environment of a CGI program or internally processed script (e\&.g\&., \fBmod_php\fR) that is \fBDACS\fR\-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\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .PP Environment variables with the prefix "DACS_" are reserved for use by \fBDACS\fR and should not be used for other purposes by an application\&. Upper and lower case are distinct in variable names\&. .sp .5v .RE .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBTip\fR .ps -1 .br .PP If \m[blue]\fBPHP\fR\m[]\&\s-2\u[57]\d\s+2 is installed, a nice way to see the \fBDACS\fR environment variables that are passed to a CGI program is to run a \fBDACS\fR\-wrapped script like this: .sp .if n \{\ .RS 4 .\} .nf

.fi .if n \{\ .RE .\} .sp Alternatively, you can use \m[blue]\fBdacs_prenv(8)\fR\m[]\&\s-2\u[58]\d\s+2\&. .sp .5v .RE .PP The environment variables that are exported (when defined) are listed here\&. More detailed descriptions of these variables appear in other \fBDACS\fR documents\&. .PP \fBDACS_ACS_JURISDICTION\fR .RS 4 This is the official \fBDACS\fR internal, abbreviated name for the jurisdiction that has granted access\&. .RE .PP \fBDACS_APPROVAL\fR .RS 4 A digitally signed message that confirms that \fBDACS\fR authorized the request\&. See \m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[59]\d\s+2\&. .RE .PP \fBDACS_CONCISE_IDENTITY\fR .RS 4 This is the full \fBDACS\fR identity to which access was granted expressed in the concise syntax used by \m[blue]\fBdacscheck(1)\fR\m[]\&\s-2\u[2]\d\s+2\&. When available, the user\*(Aqs roles and IP address are included\&. .RE .PP \fBDACS_CONF\fR .RS 4 This is the full pathname of the \fBDACS\fR configuration file\&. .RE .PP \fBDACS_CONSTRAINT\fR .RS 4 A constraint string associated with a sub\-component of the matching access control rule permitting the service request\&. .RE .PP \fBDACS_DEFAULT_CONSTRAINT\fR .RS 4 A constraint string associated with the matching access control rule\&. .RE .PP \fBDACS_FEDERATION\fR .RS 4 This is the federation name component of \fBDACS_IDENTITY\fR\&. .RE .PP \fBDACS_IDENTITY\fR .RS 4 This is the full \fBDACS\fR identity to which access was granted\&. \fBApache\fR\*(Aqs \fBREMOTE_USER\fR environment variable is also set to this value, so it is available for logging purposes and export to CGI programs\&. .RE .PP \fBDACS_JURISDICTION\fR .RS 4 This is the jurisdiction component of \fBDACS_IDENTITY\fR\&. .RE .PP \fBDACS_MOD_AUTH_DACS\fR .RS 4 This is the date and time \m[blue]\fBmod_auth_dacs\fR\m[]\&\s-2\u[3]\d\s+2 was built\&. .RE .PP \fBDACS_MOD_AUTH_DACS_VERSION\fR .RS 4 This is the \fBDACS\fR version identification string for the \m[blue]\fBmod_auth_dacs\fR\m[]\&\s-2\u[3]\d\s+2 being used (i\&.e\&., the \fBDACS\fR distribution that this module was built with)\&. .RE .PP \fBDACS_ROLES\fR .RS 4 This is the role string associated with \fBDACS_USERNAME\fR within \fBDACS_JURISDICTION\fR\&. .RE .PP \fBDACS_SITE_CONF\fR .RS 4 This is the full pathname of the \fBDACS\fR site configuration file\&. .RE .PP \fBDACS_USERNAME\fR .RS 4 This is the username component of the identity to which access was granted\&. .RE .PP \fBDACS_VERSION\fR .RS 4 The major version number of \fBDACS\fR\&. .RE .sp .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBAbout Servlets\fR .RS 4 .PP .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .PP The details of how environment variables are passed from \fBApache\fR to servlets are beyond the scope of \fBDACS\fR\&. But for what it\*(Aqs worth, the following illustrates how to export and access them from servlets that are under the control of \fBDACS\fR in conjunction with \m[blue]\fBmod_jk\fR\m[]\&\s-2\u[60]\d\s+2 and \m[blue]\fBTomcat\fR\m[]\&\s-2\u[61]\d\s+2\&. This used to work at one time but may no longer be correct\&. .sp .5v .RE .PP The following directives (which appear in, or are included in, the \fBApache\fR configuration file) are used (this list may be expanded): .sp .if n \{\ .RS 4 .\} .nf 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 .fi .if n \{\ .RE .\} .PP From a servlet, the values of these variables can be obtained through the \fBgetAttribute()\fR method, invoked on an \fIHttpServletRequest\fR object\&. For example: .sp .if n \{\ .RS 4 .\} .nf Object username = req\&.getAttribute("DACS_USERNAME"); out\&.println("roles = " + req\&.getAttribute("DACS_ROLES")); .fi .if n \{\ .RE .\} .sp .RE .SH "OPTIONS" .PP In addition to the standard \m[blue]\fB\fIdacsoptions\fR\fR\m[]\&\s-2\u[1]\d\s+2, \fBdacs_acs\fR recognizes the following arguments: .PP \fB\-dcc\fR .RS 4 Disable the \m[blue]\fBmod_auth_dacs\fR\m[]\&\s-2\u[3]\d\s+2 compatibility check\&. Use with care, normally only for testing and debugging\&. .RE .PP \fB\-proxy\-static\fR .RS 4 Reserved for future use\&. .RE .PP \fB\-proxy\-exec\fR .RS 4 Reserved for future use\&. .RE .PP \fB\-test\fR .RS 4 Perform some self\-tests, then exit\&. A non\-zero exit status means an error occurred\&. If \fB\-test\fR is the only argument (recommended), no configuration is necessary; otherwise, normal configuration processing will be performed before the self\-tests\&. .RE .SS "The DACS_ACS Argument" .PP Various aspects of the behaviour of \fBdacs_acs\fR can be controlled by an optional argument named \fIDACS_ACS\fR\&. This argument, which may be passed to \fIany\fR web service, is interpreted by \fBdacs_acs\fR 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\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBTip\fR .ps -1 .br .PP The space character(s) must be properly escaped; e\&.g\&., as %20 or +\&. .sp .5v .RE .PP One use of this feature is when an application or middleware would like to know whether \fBDACS\fR 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\&. \fBdacs_acs\fR provides this capability\&. .PP To check whether access would be granted or denied, the application invokes the \fBDACS\fR\-wrapped service or resource exactly as it would normally except that it provides the \fIDACS_ACS\fR argument\&. In some situations, if access would be denied \fBdacs_acs\fR 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\&. .PP The \fIDACS_ACS\fR 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 \fIDACS_ACS\fR argument may not be specified more than once\&. It is not always possible to escape this argument (see \m[blue]\fB\fB\-invisible\fR\fR\m[]\&\s-2\u[62]\d\s+2)\&. .PP The following flags are recognized: .PP \fB\-check_only\fR .RS 4 The presence of this flag tells \fBdacs_acs\fR not to actually execute the web service or return the resource, but to merely return the access control decision\&. This flag and the \fB\-check_fail\fR flag are mutually exclusive\&. .sp If the access check was performed, HTTP status code \fB200\fR (OK) will be returned; any other result indicates that the check could not be executed (e\&.g\&., due to an \fBApache\fR configuration problem or a \fBDACS\fR error)\&. If the check is performed, a DACS\-Status\-Line HTTP extension header is included in the response by default (see below)\&. .sp 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, .sp .if n \{\ .RS 4 .\} .nf 797 Access denied 798 Access granted 799 Access error .fi .if n \{\ .RE .\} .sp Inspecting the result code is sufficient to obtain the outcome of the check\&. Any \fBApache\fR \m[blue]\fBErrorDocument\fR\m[]\&\s-2\u[63]\d\s+2 directive for "error\-code" 200 is overridden\&. The \fB\-format\fR flag (see below) can be used to select a different output format\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br The service or resource in question does not have to exist for \fBdacs_acs\fR 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)\&. .sp 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\&. \fBdacs_acs\fR defines the variable \fI${DACS::ACS}\fR only during the testing mode of operation so that, if necessary, rules can be written to differentiate between testing mode and normal operation\&. .sp .5v .RE .RE .PP \fB\-check_fail\fR .RS 4 This flag is like the \fB\-check_only\fR flag, except if access is granted the request is allowed to proceed\&. If access is not granted and HTTP status code \fB200\fR is returned, a DACS\-Status\-Line HTTP extension header is included in the response by default (see below)\&. The \fB\-check_fail\fR flag is useful in situations where a \fB\-check_only\fR test that indicates that access would be granted is always immediately followed by the actual request\&. This flag and the \fB\-check_only\fR flag are mutually exclusive\&. .RE .PP \fB\-format\fR \fIfmt\fR .RS 4 By default, the \fB\-check_only\fR flag (and in the case where access is denied, also the \fB\-check_fail\fR flag) results in a single line of text being output (equivalent to "\fB\-format text\fR")\&. If more detail is required, an XML description can be produced by specifying any of the XML output formats\&. Refer to \m[blue]\fBXML Output\fR\m[]\&\s-2\u[64]\d\s+2, the \m[blue]\fB\fIFORMAT\fR CGI argument\fR\m[]\&\s-2\u[65]\d\s+2, and the \m[blue]\fB\fB\-format\fR\fR\m[]\&\s-2\u[66]\d\s+2 command line argument\&. .RE .PP \fB\-rname\fR \fIrname\fR .RS 4 The string \fIrname\fR, which is assumed to be the name of an Rlink, is made available available as \fI${Args::RNAME}\fR during evaluation of \m[blue]\fBACS_PRE_AUTH\fR\m[]\&\s-2\u[67]\d\s+2 directive expressions\&. .RE .PP \fB\-status_line\fR .br \fB\-no\-status_line\fR .RS 4 The \fB\-status_line\fR flag enables the \m[blue]\fBDACS\-Status\-Line\fR\m[]\&\s-2\u[68]\d\s+2 header, overriding the setting of the \m[blue]\fBSTATUS_LINE\fR\m[]\&\s-2\u[69]\d\s+2 configuration directive\&. The \fB\-no_status_line\fR flag \fIalways\fR suppresses this header, regardless of the \m[blue]\fBSTATUS_LINE\fR\m[]\&\s-2\u[69]\d\s+2 directive and the \fB\-check_only\fR and \fB\-check_fail\fR flags\&. .RE .PP \fB\-visible\fR .br \fB\-invisible\fR .RS 4 If the \fIDACS_ACS\fR 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 \fB\-invisible\fR flag and disabled by the \fB\-visible\fR flag\&. If \fIDACS_ACS\fR is not deleted, it will be passed to an invoked program and might affect subsequent processing\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBImportant\fR .ps -1 .br Deletion of the \fIDACS_ACS\fR argument is currently possible only if it is passed as a query argument\&. .sp .5v .RE For example, consider the hypothetical URL: .sp .if n \{\ .RS 4 .\} .nf https://example\&.com/cgi\-bin/myprog?DACS_ACS=\-check_fail+\-visible&foo=baz .fi .if n \{\ .RE .\} .sp If the CGI program \fBmyprog\fR 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 \fBmyprog\fR processes it\&. .sp All \fBDACS\fR web services ignore a \fIDACS_ACS\fR argument, however, so its presence will not affect them\&. .RE .PP 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 \fIDACS_ACS\fR argument is invalid, the initial, valid part will still be effective; e\&.g\&., if the initial part is \fB\-format\fR XML, the output format will be XML\&. .PP \fBdacs_acs\fR removes the \fIDACS_ACS\fR argument from the rule\-processing environment so as not to disturb access control processing\&. \fBDACS\fR credentials may accompany the service request just as they would a real request and are incorporated into the check\&. .PP Assuming the target resource is \fBDACS\fR\-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: .sp .if n \{\ .RS 4 .\} .nf % dacshttp \-v \-v \e \*(Aqhttps://dacs\&.dss\&.ca/cgi\-bin/dacs/dacs_version?DACS_ACS=\-check_only%20\-format+xml\*(Aq .fi .if n \{\ .RE .\} .sp .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBThe DACS-Status-Line header\fR .RS 4 .PP When the \fBDACS_ACS=\-check_only\fR argument is present, the response from \fBDACS\fR includes an extension header named DACS\-Status\-Line\&. The format of this extension header follows that of the HTTP Status\-Line (\m[blue]\fBRFC 2616\fR\m[]\&\s-2\u[32]\d\s+2, section 6\&.1): .sp .if n \{\ .RS 4 .\} .nf DACS\-Status\-Line = "DACS\-Status\-Line" ":" \fIDACS\-Version\fR SP \fIACS\-Status\-Code\fR SP \fIReason\-Phrase\fR CRLF .fi .if n \{\ .RE .\} .sp Where: .sp .if n \{\ .RS 4 .\} .nf \fIDACS\-Version\fR = "DACS\-" \fIVersion\fR .fi .if n \{\ .RE .\} .sp and \fIVersion\fR is the \fBDACS_VERSION_RELEASE\fR string (e\&.g\&., 1\&.4\&.8b), and where: .sp .if n \{\ .RS 4 .\} .nf \fIACS\-Status\-Code\fR = "797" | "798" | "799" .fi .if n \{\ .RE .\} .sp The status code \fB797\fR means that \fBDACS\fR denies access, \fB798\fR means that it grants access, and \fB799\fR means that an error occurred during processing\&. .PP Here are some examples: .sp .if n \{\ .RS 4 .\} .nf 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 .fi .if n \{\ .RE .\} .sp The reason phrases in the examples are only recommendations; they may be replaced by local equivalents without affecting the protocol\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .PP The reason phrase may include additional information, such as an audit identifier that can be used to track the request in the \fBDACS\fR logs: .sp .if n \{\ .RS 4 .\} .nf DACS\-Status\-Line: DACS\-1\&.4\&.10 798 Access granted, unauth user (j10OXL2Z) .fi .if n \{\ .RE .\} .sp .5v .RE .PP This header is also returned when \fB\-check_fail\fR is requested, but only if access is not granted\&. .RE .sp .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBThe DACS_APPROVAL environment variable\fR .RS 4 .PP If enabled by the \m[blue]\fBACS_EMIT_APPROVAL\fR\m[]\&\s-2\u[70]\d\s+2 directive, the \fBDACS_APPROVAL\fR environment variable will be passed to a \fBDACS\fR\-wrapped program\&. If the program cares to verify that its execution has been authorized, it may validate the approval\*(Aqs 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\&. .PP With proper configuration, this feature can be used by a web\-based program that is not \fBDACS\fR\-wrapped but for which authorization has been obtained indirectly\&. For example, when \m[blue]\fBdacs_uproxy(8)\fR\m[]\&\s-2\u[71]\d\s+2, invokes a program, \fBdacs_uproxy\fR will forward the value of \fBDACS_APPROVAL\fR (when available) to the invoked program, which can obtain the value in its \fBHTTP_DACS_UPROXY_APPROVAL\fR environment variable\&. If it is able to validate the value (or can trust it), the invoked program knows that its execution was authorized by \fBDACS\fR, even though \fBDACS\fR may not be configured or even installed on the host where the invoked program runs\&. .PP A jurisdiction\*(Aqs cryptographic keys, identified by the virtual filestore item type jurisdiction_keys, must be configured so that the approval can be digitally signed\&. .PP The value of \fBDACS_APPROVAL\fR has the following format: .sp .if n \{\ .RS 4 .\} .nf a="\fIdacs64\-approval\-message\fR", s="\fIdacs64\-signature\fR" .fi .if n \{\ .RE .\} .sp The \fIdacs64\-approval\-message\fR is a \m[blue]\fBdacs64\fR\m[]\&\s-2\u[35]\d\s+2 encoded string, described below\&. The \fIdacs64\-signature\fR is the dacs64 encoded RSA signature of the approval message, which is the unencoded \fIdacs64\-approval\-message\fR\&. .PP An approval message has the following format: .sp .if n \{\ .RS 4 .\} .nf j="\fIjurisdiction\-name\fR" h="\fIdigest\-name\fR" s="\fIstamp\fR" u="\fIuri\fR" m="\fImethod\fR" i="\fIident\fR" .fi .if n \{\ .RE .\} .sp Here, \fIjurisdiction\-name\fR 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 \fIdigest\-name\fR\&. The unique stamp is \fIstamp\fR (as generated by \m[blue]\fBustamp()\fR\m[]\&\s-2\u[72]\d\s+2) and the URI, including any query component, is \fIuri\fR\&. The HTTP method is \fImethod\fR\&. The \fBDACS\fR identity of the user for which access was granted is \fIident\fR (or "unauth", if none)\&. The \fIstamp\fR and \fImethod\fR are mapped to lowercase\&. Here is an example of an approval message: .sp .if n \{\ .RS 4 .\} .nf 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" .fi .if n \{\ .RE .\} .PP The RSA signature is computed using the jurisdiction\*(Aqs private key and SHA\-1 (by default) over the approval message\&. A different message digest algorithm can be used by setting the configuration variable \fI${Conf::dacs_approval_digest_name}\fR (see \m[blue]\fBdigest()\fR\m[]\&\s-2\u[73]\d\s+2 for information about message digest algorithms): .sp .if n \{\ .RS 4 .\} .nf EVAL ${Conf::dacs_approval_digest_name} = "SHA256" .fi .if n \{\ .RE .\} .sp .RE .SH "DIAGNOSTICS" .PP The program exits 0 if everything was fine, 1 if an error occurred\&. .SH "NOTES" .PP 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 \fB\-check_only\fR\&. .SH "SEE ALSO" .PP \m[blue]\fBdacsacl(1)\fR\m[]\&\s-2\u[45]\d\s+2, \m[blue]\fBdacscheck(1)\fR\m[]\&\s-2\u[2]\d\s+2, \m[blue]\fBdacs\&.acls(5)\fR\m[]\&\s-2\u[4]\d\s+2, \m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[49]\d\s+2, \m[blue]\fBdacs_admin(8)\fR\m[]\&\s-2\u[46]\d\s+2 .SH "BUGS" .PP While the \fIDACS_ACS\fR mechanism can be useful, it is still a kludge, .SH "AUTHOR" .PP Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[74]\d\s+2) .SH "COPYING" .PP Copyright \(co 2003\-2018 Distributed Systems Software\&. See the \m[blue]\fBLICENSE\fR\m[]\&\s-2\u[75]\d\s+2 file that accompanies the distribution for licensing information\&. .SH "NOTES" .IP " 1." 4 dacsoptions .RS 4 \%http://dacs.dss.ca/man/dacs.1.html#dacsoptions .RE .IP " 2." 4 dacscheck(1) .RS 4 \%http://dacs.dss.ca/man/dacscheck.1.html .RE .IP " 3." 4 mod_auth_dacs .RS 4 \%http://dacs.dss.ca/man/mod_auth_dacs.html .RE .IP " 4." 4 dacs.acls(5) .RS 4 \%http://dacs.dss.ca/man/dacs.acls.5.html .RE .IP " 5." 4 logging .RS 4 \%http://dacs.dss.ca/man/dacs.1.html#logging .RE .IP " 6." 4 LOG_LEVEL .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#LOG_LEVEL .RE .IP " 7." 4 LOG_FILTER .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#LOG_FILTER .RE .IP " 8." 4 AddDACSAuth .RS 4 \%http://dacs.dss.ca/man/mod_auth_dacs.html#AddDACSAuth .RE .IP " 9." 4 DACS_HOME .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#var_dacs_home .RE .IP "10." 4 pipe(2) .RS 4 \%https://www.freebsd.org/cgi/man.cgi?query=pipe&apropos=0&sektion=2&manpath=FreeBSD+10.3-RELEASE&format=html .RE .IP "11." 4 Variables Available To Rules .RS 4 \%http://dacs.dss.ca/man/#vars_in_rules .RE .IP "12." 4 mod_auth_dacs .RS 4 \%http://dacs.dss.ca/man/mod_auth_dacs.html#SetDACSAuthPostBuffer .RE .IP "13." 4 COOKIE_NAME_TERMINATORS .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#COOKIE_NAME_TERMINATORS .RE .IP "14." 4 ALLOW_HTTP_COOKIE .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#ALLOW_HTTP_COOKIE .RE .IP "15." 4 RFC 2617 .RS 4 \%http://www.rfc-editor.org/rfc/rfc2617.txt .RE .IP "16." 4 dacs_authenticate(8) .RS 4 \%http://dacs.dss.ca/man/dacs_authenticate.8.html#credentials .RE .IP "17." 4 dacsrlink(1) .RS 4 \%http://dacs.dss.ca/man/dacsrlink.1.html .RE .IP "18." 4 redirect() .RS 4 \%http://dacs.dss.ca/man/dacs.exprs.5.html#redirect .RE .IP "19." 4 RLINK .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#RLINK .RE .IP "20." 4 the one used for normal rules .RS 4 \%http://dacs.dss.ca/man/dacs.acls.5.html#acl_files .RE .IP "21." 4 concise user identity .RS 4 \%http://dacs.dss.ca/man/dacs.1.html#concise_user_syntax .RE .IP "22." 4 identity element .RS 4 \%http://dacs.dss.ca/man/dacs.acls.5.html#elements .RE .IP "23." 4 DACS_ACS argument .RS 4 \%http://dacs.dss.ca/man/#dacs_acs_argument .RE .IP "24." 4 autologin(8) .RS 4 \%http://dacs.dss.ca/man/autologin.8.html .RE .IP "25." 4 HTTP_AUTH_ENABLE .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#HTTP_AUTH_ENABLE .RE .IP "26." 4 HTTP_AUTH .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#HTTP_AUTH .RE .IP "27." 4 Auth clause directives .RS 4 \%http://dacs.dss.ca/man/dacs_authenticate.8.html#auth_clause .RE .IP "28." 4 local_apache_authenticate .RS 4 \%http://dacs.dss.ca/man/dacs_authenticate.8.html#local_apache_authenticate .RE .IP "29." 4 ACS_ERROR_HANDLER .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#ACS_ERROR_HANDLER .RE .IP "30." 4 AUTH_SUCCESS_HANDLER .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_SUCCESS_HANDLER .RE .IP "31." 4 AUTH_ERROR_HANDLER .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_ERROR_HANDLER .RE .IP "32." 4 RFC 2616 .RS 4 \%http://www.rfc-editor.org/rfc/rfc2616.txt .RE .IP "33." 4 dacshttp(1) .RS 4 \%http://dacs.dss.ca/man/dacshttp.1.html .RE .IP "34." 4 passed using this request-header .RS 4 \%http://dacs.dss.ca/man/#http_authentication .RE .IP "35." 4 dacs.exprs(5) .RS 4 \%http://dacs.dss.ca/man/dacs.exprs.5.html#encode .RE .IP "36." 4 COOKIE_PATH .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#COOKIE_PATH .RE .IP "37." 4 COOKIE_NO_DOMAIN .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#COOKIE_NO_DOMAIN .RE .IP "38." 4 COOKIE_HTTP_ONLY .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#COOKIE_HTTP_ONLY .RE .IP "39." 4 dacs.install(7) .RS 4 \%http://dacs.dss.ca/man/dacs.install.7.html#configure_options .RE .IP "40." 4 ACS_ACCESS_TOKEN_ENABLE .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#ACS_ACCESS_TOKEN_ENABLE .RE .IP "41." 4 ACS_ACCESS_TOKEN_LIFETIME_LIMIT .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#ACS_ACCESS_TOKEN_LIFETIME_LIMIT .RE .IP "42." 4 ACS_ACCESS_TOKEN_LIFETIME_SECS .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#ACS_ACCESS_TOKEN_LIFETIME_SECS .RE .IP "43." 4 dacs.acls(5) .RS 4 \%http://dacs.dss.ca/man/dacs.acls.5.html#acl_syntax .RE .IP "44." 4 tail matching .RS 4 \%http://dacs.dss.ca/man/dacs.acls.5.html#tail_matching .RE .IP "45." 4 dacsacl(1) .RS 4 \%http://dacs.dss.ca/man/dacsacl.1.html .RE .IP "46." 4 dacs_admin(8) .RS 4 \%http://dacs.dss.ca/man/dacs_admin.8.html .RE .IP "47." 4 revocation list .RS 4 \%http://dacs.dss.ca/man/dacs.acls.5.html#revocation_list .RE .IP "48." 4 dacs_acs.dtd .RS 4 \%http://dacs.dss.ca/man/../dtd-xsd/dacs_acs.dtd .RE .IP "49." 4 dacs.conf(5) .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html .RE .IP "50." 4 dacs_notices(8) .RS 4 \%http://dacs.dss.ca/man/dacs_notices.8.html .RE .IP "51." 4 dacs.exprs(5) .RS 4 \%http://dacs.dss.ca/man/dacs.exprs.5.html#variables .RE .IP "52." 4 RFC 1867 .RS 4 \%http://www.rfc-editor.org/rfc/rfc1867.txt .RE .IP "53." 4 RFC 2388 .RS 4 \%http://www.rfc-editor.org/rfc/rfc2388.txt .RE .IP "54." 4 HTML 4 .RS 4 \%http://www.w3.org/TR/html4 .RE .IP "55." 4 ACS_POST_EXCEPTION_MODE .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#ACS_POST_EXCEPTION_MODE .RE .IP "56." 4 Rlinks .RS 4 \%http://dacs.dss.ca/man/#rlinks .RE .IP "57." 4 PHP .RS 4 \%http://www.php.net .RE .IP "58." 4 dacs_prenv(8) .RS 4 \%http://dacs.dss.ca/man/dacs_prenv.8.html .RE .IP "59." 4 dacs_acs(8) .RS 4 \%http://dacs.dss.ca/man/dacs_acs.8.html#dacs_approval .RE .IP "60." 4 mod_jk .RS 4 \%http://tomcat.apache.org/connectors-doc/generic_howto/quick.html .RE .IP "61." 4 Tomcat .RS 4 \%http://jakarta.apache.org .RE .IP "62." 4 \fB-invisible\fR .RS 4 \%http://dacs.dss.ca/man/#invisible_flag .RE .IP "63." 4 ErrorDocument .RS 4 \%http://httpd.apache.org/docs/2.4/mod/core.html#errordocument .RE .IP "64." 4 XML Output .RS 4 \%http://dacs.dss.ca/man/#XML-output .RE .IP "65." 4 \fIFORMAT\fR CGI argument .RS 4 \%http://dacs.dss.ca/man/dacs.1.html#FORMAT .RE .IP "66." 4 \fB-format\fR .RS 4 \%http://dacs.dss.ca/man/dacs.1.html#format-arg .RE .IP "67." 4 ACS_PRE_AUTH .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#ACS_PRE_AUTH .RE .IP "68." 4 DACS-Status-Line .RS 4 \%http://dacs.dss.ca/man/dacs_acs.8.html#dacs_status_line .RE .IP "69." 4 STATUS_LINE .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#STATUS_LINE .RE .IP "70." 4 ACS_EMIT_APPROVAL .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#ACS_EMIT_APPROVAL .RE .IP "71." 4 dacs_uproxy(8) .RS 4 \%http://dacs.dss.ca/man/dacs_uproxy.8.html .RE .IP "72." 4 ustamp() .RS 4 \%http://dacs.dss.ca/man/dacs.exprs.5.html#ustamp .RE .IP "73." 4 digest() .RS 4 \%http://dacs.dss.ca/man/dacs.exprs.5.html#digest .RE .IP "74." 4 www.dss.ca .RS 4 \%http://www.dss.ca .RE .IP "75." 4 LICENSE .RS 4 \%http://dacs.dss.ca/man/../misc/LICENSE .RE