.\" 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.conf
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 08/23/2020
.\" Manual: DACS Formats Manual
.\" Source: DACS 1.4.40
.\" Language: English
.\"
.TH "DACS\&.CONF" "5" "08/23/2020" "DACS 1.4.40" "DACS Formats 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.conf \- \fBDACS\fR configuration files and directives
.SH "DESCRIPTION"
.PP
These files are part of the
\fBDACS\fR
suite\&.
.PP
Nearly all
\fBDACS\fR
services and utilities consult a configuration file when they start up\&. Such things as the per\-jurisdiction locations of access control files and log files, authentication processing, error handling, and run\-time limits are specified in the configuration file\&. The recommended name for this file is
dacs\&.conf
and the
\fBDACS\fR
documentation will generally refer to it by that name\&. Site\-wide configuration, which is optional, is typically put in a file named
site\&.conf\&. Both files are XML documents, and consist of various
sections,
clauses, and
directives, not unlike the
httpd\&.conf
configuration file used by
\fBApache\fR\&. Different federations and jurisdictions running on the same host may share these files or each might have its own separate configuration file; the former is more common since it reduces duplication and helps to prevent inconsistencies\&.
.PP
Federations, jurisdictions, and other important concepts are discussed in
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[1]\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
Unlike the "passive" configuration files found in most systems, the
\fBDACS\fR
configuration files are "active"; that is, configuration directives are evaluated as expressions within a run\-time context that includes information related to the current request, web server, operating system, and
\fBDACS\fR
itself\&. By specifying the value of a directive as an expression rather than a simple string, the configuration under which a request is processed can adapt to, or depend on, the context in which it is made\&. Administrators do not need to use this capability, but it is available when flexibility is needed\&.
.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
\fBNote\fR
.ps -1
.br
.PP
Each configuration file is completely read and processed once, each time a
\fBDACS\fR
web service or utility is executed\&. Changes to the files take effect the next time the files are read; no recompilation or special action needs to be taken, and neither
\fBApache\fR
nor any other server needs to be restarted\&. It is usually safe to make minor updates to the configuration files while
\fBDACS\fR
is operational, but it is better to temporarily deny all access if the web server is busy and more complicated changes are being made\&. Because
\fBDACS\fR
components abort if they encounter a configuration error (e\&.g\&., leading to all access to be denied, all authentication to fail, or a utility to become non\-operational), temporarily introducing a configuration error will not usually cause any serious problems\&. Under heavy load or if complex authentication methods have been configured, however, it is prudent to stop the web server briefly while the old configuration files are replaced with the new ones\&.
.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
While it may at first seem that
\fBDACS\fR
is difficult to configure, in practice the default configuration that comes with the
\fBDACS\fR
distribution is sufficient in many cases, and leaves only a few straightforward, site\-dependent directives to be specified\&. Many administrators will never need to use the more advanced configuration features\&.
.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
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The
\fBDACS\fR
distribution includes a prototype version of
site\&.conf, found in
conf/site\&.conf\-std, which establishes reasonable defaults based on
\fBDACS\fR
build\-time arguments\&. It may need some customization for the local environment\&. By default,
\fBDACS\fR
looks for the site configuration file in
federations/site\&.conf, relative to the
\fBDACS\fR
installation directory;
conf/site\&.conf\-std
can be copied there and any necessary customizations made\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A command to validate and display configuration,
\m[blue]\fBdacsconf(1)\fR\m[]\&\s-2\u[2]\d\s+2
is available, as is a simple web service,
\m[blue]\fBdacs_conf(8)\fR\m[]\&\s-2\u[3]\d\s+2\&. Until you become comfortable with configuration files, consider running one of them after making changes\&. A fatal configuration error will prevent
\fBDACS\fR
from running and access to all
\fBDACS\fR\-wrapped resources will be denied\&.
.RE
.sp .5v
.RE
.SS "Locating dacs\&.conf and site\&.conf"
.PP
The locations of
dacs\&.conf
and
site\&.conf
may be specified with the web server configuration, in an environment variable, through a command line flag, or at compile time\&. A single configuration file can provide directives for multiple
\fBDACS\fR
jurisdictions\&. For example, if a machine is hosting more than one
\fBDACS\fR
jurisdiction, they can each use the same
\fBDACS\fR
binaries\&.
.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
Most
\fBDACS\fR
commands and web services require the
dacs\&.conf
file to exist; the exceptions are a few "standalone" programs, such as
\m[blue]\fBdacshttp(1)\fR\m[]\&\s-2\u[4]\d\s+2\&. The
site\&.conf
file is not required; if a location has been configured and the file exists, however, it must be readable and by convention should contain default values appropriate for the installed release\&.
.sp .5v
.RE
.PP
Command line flags common to many
\fBDACS\fR
programs are described in
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[5]\d\s+2\&.
.PP
So that
\m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[6]\d\s+2
(which is invoked by the
\m[blue]\fBmod_auth_dacs\fR\m[]\&\s-2\u[7]\d\s+2
module) can find its configuration, the location of
dacs\&.conf
can be specified in
\fBApache\*(Aqs\fR
httpd\&.conf
file using the
SetDACSAuthConf
directive\&. It may instead, however, be specified through the
\fBDACS_CONF\fR
environment variable, on the command line, or using a build\-time default\&. Similarly, the location of
site\&.conf
can be specified in
\fBApache\*(Aqs\fR
httpd\&.conf
file using the
SetDACSAuthSiteConf
directive, through the
\fBDACS_SITE_CONF\fR
environment variable, on the command line, or using a build\-time default\&.
.PP
If the location of
dacs\&.conf
(site\&.conf) is not given at run\-time, a compile\-time value of the symbol
DACS_CONF
(DACS_SITE_CONF) will be used if possible\&. This is the usual case for programs other than
\fBdacs_acs\fR\&. It is a fatal error if a
\fBDACS\fR
service can\*(Aqt locate
dacs\&.conf\&.
.PP
Regardless of how the location of
dacs\&.conf
is specified,
\fBDACS\fR
performs string interpolation on the pathname\&. If interpolation fails,
\fBDACS\fR
will encounter a fatal error because it will not be able to locate its configuration file\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBPath Interpolation\fR
.RS 4
.PP
Path interpolation is available using a syntax and method similar to
\fBApache\*(Aqs\fR
\m[blue]\fB\fBmod_vhost_alias\fR\fR\m[]\&\s-2\u[8]\d\s+2
module\&. Interpolation is always performed to determine the locations of several resources used by
\fBDACS\fR, such as
dacs\&.conf
and
site\&.conf, and with
\fBDACS\*(Aqs\fR
\m[blue]\fBLOG_FILE\fR\m[]\&\s-2\u[9]\d\s+2
directive, regardless of the manner in which the location is provided to
\fBDACS\fR\&. It is applied whether the location of
dacs\&.conf
is specified using the
\fB\-u\fR
command line flag or the
\fBApache\fR
(\fBmod_auth_dacs\fR)
SetDACSAuthConf
directive, for instance\&.
.PP
The functionality can also be accessed using the
\m[blue]\fBpathname()\fR\m[]\&\s-2\u[10]\d\s+2
function\&.
.PP
The strings that may be interpolated into the pathname are obtained from the execution environment, in particular the URI authority information (based on
\fBApache\fR\*(Aqs
\fBSERVER_NAME\fR
and
\fBSERVER_PORT\fR
environment variables), the URI service path (described below), build\-time configuration, and the applicable
Jurisdiction
section\*(Aqs distinguishing URI\&.
.PP
Interpolation is controlled by
\fBprintf\fR\-like format specifiers, as follows:
.PP
%%
.RS 4
Insert a literal percent character
.RE
.PP
%a
.RS 4
Insert the application name, which is obtained from the filename component of the program\*(Aqs
\fIargv[0]\fR
argument
.RE
.PP
%bA
.RS 4
Insert the absolute pathname of the root of the Apache installation directory, specified at build\-time (\fIAPACHE_HOME\fR)
.RE
.PP
%bD
.RS 4
Insert the absolute pathname of the root of the
\fBDACS\fR
installation directory, specified at build\-time (\fIDACS_HOME\fR)
.RE
.PP
%p
.RS 4
Insert the port number of the virtual host (\fBSERVER_PORT\fR)
.RE
.PP
%\fIN\fR\&.\fIM\fR
.RS 4
Insert one or more components of the name, or a substring of those subcomponents\&.
\fIN\fR
and
\fIM\fR
are numbers used to select part of the
\fBSERVER_NAME\fR
string (a domain name or IP address)\&.
\fIN\fR
selects from the dot\-separated components of
\fBSERVER_NAME\fR, while
\fIM\fR
selects characters within whatever
\fIN\fR
has selected\&.
\fIM\fR
is optional and defaults to zero if it isn\*(Aqt present\&. The dot must be present if and only if
\fIM\fR
is also present\&. If
\fIN\fR
or
\fIM\fR
are greater than the number of parts available, a single underscore is interpolated\&. The numbers are interpreted as follows:
.PP
0 or 1+ or \-1+
.RS 4
the whole name
.RE
.PP
1
.RS 4
the first part
.RE
.PP
2
.RS 4
the second name
.RE
.PP
\-1
.RS 4
the last part
.RE
.PP
\-2
.RS 4
the next\-to\-last part
.RE
.PP
2+
.RS 4
the second and all following parts
.RE
.PP
\-2+
.RS 4
the next\-to\-last and all preceding parts
.RE
.sp
.RE
.PP
%s[\fIN\fR\&.\fIM\fR]
.RS 4
This is a synonym for
%\fIN\fR\&.\fIM\fR, with
%s
being equivalent to
%0\&.
.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
In cases where the character following
%s
should not be interpreted as part of the format, it must be escaped (e\&.g\&.,
%s%2)\&.
.sp .5v
.RE
.RE
.PP
%u[\fIN\fR\&.\fIM\fR]
.RS 4
This functions like the
%s
specifier except that it is applied to the URI service path (described below) for the current request, which has slash\-separated components\&.
%u
is equivalent to
%u0\&. For example, if the URI service path is "example\&.com/metalogic",
%u1
would be "example\&.com",
%u2
would be "metalogic", and
%u0
(and
%u
and
%u1+) would be "example\&.com/metalogic"\&.
.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
In cases where the character following
%u
should be interpolated verbatim and not interpreted as part of the specifier, it must be escaped (e\&.g\&.,
%u%2)\&.
.sp .5v
.RE
.RE
.PP
%U[\fIN\fR\&.\fIM\fR]
.RS 4
This functions like the
%u
specifier except that it is applied to the applicable
\m[blue]\fBJurisdiction section\*(Aqs\fR\m[]\&\s-2\u[11]\d\s+2
distinguishing URI (described below)\&.
%U
is equivalent to
%U0\&.
.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
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Because the applicable
Jurisdiction
section is not known until after configuration processing has started, this specifier cannot be used to describe the location of configuration files\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
In cases where the character following
%U
should be interpolated verbatim and not interpreted as part of the specifier, it must be escaped (e\&.g\&.,
%U%2)\&.
.RE
.sp .5v
.RE
.RE
.PP
Other format specifiers
.RS 4
If a
%
is followed by an unrecognized specifier, that character is inserted verbatim\&.
.RE
.PP
Other characters
.RS 4
All other characters are inserted verbatim
.RE
.PP
For example, if
\fBSERVER_NAME\fR
is
dss\&.example\&.com
and
\fBSERVER_PORT\fR
is
8080, then the
\fBApache\fR
directive:
.sp
.if n \{\
.RS 4
.\}
.nf
SetDACSAuthConf dacs\-acs "/usr/local/apache2/conf/dacs/%2+/dacs\&.conf"
.fi
.if n \{\
.RE
.\}
.sp
will expand the path to
/usr/local/apache2/conf/dacs/example\&.com/dacs\&.conf\&. The command line flag:
.sp
.if n \{\
.RS 4
.\}
.nf
\-c /usr/local/dacs/%1%\&.%p/dacs\&.conf
.fi
.if n \{\
.RE
.\}
.sp
specifies the location of the configuration file to be
/usr/local/dacs/dss\&.8080/dacs\&.conf\&.
.PP
The
%u
specifier interpolates the URI service path, or portions thereof, which is the string
\fBHTTP_HOST\fR/\fBREQUEST_URI\fR
(without a query component)\&. When a
\fBDACS\fR
service is invoked as a CGI, this will be the usual case; the URI service path is undefined if either of those environment variables is unavailable, however\&.
.RE
.SS "File Format"
.PP
dacs\&.conf
is an XML document that conforms to
\m[blue]\fBConfiguration\&.dtd\fR\m[]\&\s-2\u[12]\d\s+2\&.
.PP
A
dacs\&.conf
file consists of an optional
Default
section followed by zero or more
Jurisdiction
sections\&. Either type of section consists of
\fBDACS\fR
directives or XML elements, called
clauses, that contain
\fBDACS\fR
directives\&. There are three kinds of clauses:
Auth
clauses,
Roles
clauses, and
Transfer
clauses\&.
.PP
Just to give its flavour, here\*(Aqs an incomplete
dacs\&.conf
file:
.sp
.if n \{\
.RS 4
.\}
.nf
LOG_FILE "${Conf::DACS_HOME}/logs/logfile"
FEDERATION_DOMAIN "example\&.com"
FEDERATION_NAME "ROOT"
LOG_LEVEL "notice"
SSL_PROG "/usr/local/dacs/bin/sslclient"
JURISDICTION_NAME "DSS"
URL "https://dss\&.example\&.com/cgi\-bin/dacs/local_unix_authenticate"
STYLE "pass"
CONTROL "sufficient"
JURISDICTION_NAME "FOO"
JURISDICTION_NAME "METALOGIC"
.fi
.if n \{\
.RE
.\}
.PP
The structure of
site\&.conf
is only slightly different\&. The
Default
section is mandatory in
site\&.conf
and no
Jurisdiction
sections are allowed\&.
.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 the configuration files are XML documents, characters special to XML must be properly escaped\&. In particular, an ampersand character must always be written as
&
and a
<
character must be written as
<\&.
.sp .5v
.RE
.PP
Although the XML format of the
\fBDACS\fR
configuration files is easily understood and fairly readable, and they can be modified using any text editor, there is nothing to prevent a special\-purpose tool from being used\&.
.SS "The Default Section"
.PP
The purpose of the
Default
section in
dacs\&.conf
is to establish default values for directives that tend to be shared amongst all of the
Jurisdiction
sections that appear in
dacs\&.conf\&. The
Default
section is optional; if present, it must appear before any
Jurisdiction
section in
dacs\&.conf\&.
.PP
The
site\&.conf
file, if it exists, consists of only a
Default
section\&. Directives that are common to all of a site\*(Aqs
dacs\&.conf
files might be put in
site\&.conf\&.
.PP
Any configuration directive or clause may appear in the
Default
section\&.
.SS "The Jurisdiction Section"
.PP
Each
Jurisdiction
section contains configuration directives that are associated with a particular jurisdiction\&. These directives override those found anywhere else, as described below\&.
.SS "Section Merging and Directive Evaluation"
.PP
The three types of configuration sections are merged as follows\&. First, directives and clauses that appear in the
site\&.conf
Default
section are overridden by those that appear in the
dacs\&.conf
Default
section\&. The resulting directives and clauses are in turn overridden by those that appear in the selected
Jurisdiction
section\&. Usually,
site\&.conf
will contain the standard default directives that come with the installed release of
\fBDACS\fR, the
dacs\&.conf
Default
section will contain directives common to all of the jurisdictions defined on the host that are in the same federation, and each
Jurisdiction
section will contain directives specific to that jurisdiction\&.
.PP
The exception to this merging procedure is directives in the
\m[blue]\fBStack category\fR\m[]\&\s-2\u[13]\d\s+2\&. Instead of overriding, these directives accumulate\&.
.PP
The order in which directives (but not clauses) appear within a section is not significant, even with respect to references to variables in the
\fIConf\fR
\m[blue]\fBnamespace\fR\m[]\&\s-2\u[14]\d\s+2, with the exception of the
\m[blue]\fBEVAL directive\fR\m[]\&\s-2\u[15]\d\s+2\&.
.PP
Only after directives in the three sections are merged are their right\-hand sides evaluated (again, with the exception of
\m[blue]\fBEVAL\fR\m[]\&\s-2\u[15]\d\s+2) to determine the value of each directive\&. Therefore, if a directive appears in both the
Default
section and the
Jurisdiction
section, the instances in the
Default
section will not have their directive values evaluated; they will simply be discarded (with the exception of the
Stack
directive category)\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBThe undef() directive\fR
.RS 4
.PP
As a special case, if a directive is given the special value returned by
\m[blue]\fBundef()\fR\m[]\&\s-2\u[16]\d\s+2, the instance of the directive is deleted\&. This provides a way to conditionally include or exclude a directive depending on the execution environment\&. For example, this directive increases the debugging level for
\fBDACS\fR
web services but not for commands:
.sp
.if n \{\
.RS 4
.\}
.nf
LOG_LEVEL ${Env::REMOTE_ADDR:e} ? "TRACE" : undef()
.fi
.if n \{\
.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
\fBNote\fR
.ps -1
.br
.PP
Because of the way configuration files are currently processed, the check for directive category satisfaction happens
\fIbefore\fR
right\-hand side evaluation\&. This means that in any particular section only one instance of a given directive in the
Required1
category may appear (see
\m[blue]\fBDirective Categories\fR\m[]\&\s-2\u[13]\d\s+2), even if just one would be included after the evaluation step\&.
.sp .5v
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBFatal errors\fR
.RS 4
.PP
It is a fatal error to reference an undefined variable unless the
e
or
?
\m[blue]\fBmodifier flag\fR\m[]\&\s-2\u[17]\d\s+2
is used in the variable reference\&. Recursive variable references are detected and result in a fatal error\&. If a directive ends up not being evaluated, it does not matter whether its right\-hand side is invalid (or would be if evaluated)\&.
.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
When a fatal error occurs during configuration processing, a
\fBDACS\fR
web service tries to terminate gracefully\&. But because directives (including error handling directives) may not have been processed correctly, or even at all, there is no guarantee that an error handler (such as one defined by the
\m[blue]\fBACS_ERROR_HANDLER\fR\m[]\&\s-2\u[18]\d\s+2
directive) will be invoked or a requested output format will be honoured during abnormal termination\&. A non\-zero exit process status is always returned\&.
.sp .5v
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAn example\fR
.RS 4
.PP
Consider the following configuration excerpts:
.sp
.if n \{\
.RS 4
.\}
.nf
# In site\&.conf:
LOG_LEVEL "debug"
# In the dacs\&.conf Default section:
LOG_LEVEL "notice"
# In the dacs\&.conf Jurisdiction section:
LOG_LEVEL "trace"
.fi
.if n \{\
.RE
.\}
.sp
After configuration processing, the directive
LOG_LEVEL
will be set to "trace", and the variable
\fI${Conf::LOG_LEVEL}\fR
will have that value during configuration processing\&.
.PP
Here are some excerpts from a
dacs\&.conf
file:
.sp
.if n \{\
.RS 4
.\}
.nf
# In the Default section:
FEDERATION_DOMAIN "example\&.com"
FEDERATION_NAME "EXAMPLE"
# In the Jurisdiction section:
JURISDICTION_NAME "DEMO"
VFS "[abc]dacs\-fs:${Conf::FEDERATIONS_ROOT}/${Conf::FEDERATION_DOMAIN}\e
/${Conf::JURISDICTION_NAME}/abc"
.fi
.if n \{\
.RE
.\}
.sp
When computing the
VFS
directive\*(Aqs value in the example above, the values of the
\fIFEDERATIONS_ROOT\fR
variable (determined at build\-time) and the
FEDERATION_DOMAIN
and
JURISDICTION_NAME
configuration directives are interpolated\&. Directives in
site\&.conf
may reference configuration variables that are defined in
dacs\&.conf\&.
.PP
Given the configuration:
.sp
.if n \{\
.RS 4
.\}
.nf
# In site\&.conf:
VFS "[dtds]dacs\-fs:/usr/local/dacs/www/dtd\-xsd"
# In the dacs\&.conf Default section:
VFS "[dtds]dacs\-fs:/usr/local/dacs/dtd\-xsd"
# In the dacs\&.conf Jurisdiction section:
VFS "[dtds]dacs\-fs:/export/dacs/dtd\-xsd"
VFS "[xxx]dacs\-fs:/export/dacs/xxx"
.fi
.if n \{\
.RE
.\}
.sp
All four
VFS
directives will be in effect, but they will be ordered such that the first one in the
Jurisdiction
section is at the top of the stack, the second one in that section is next on the stack, the directive in the
dacs\&.conf
Default
section follows, and the one from
site\&.conf
is last\&.
.RE
.SS "Jurisdiction Section Selection"
.PP
\fBDACS\fR
web services and commands do not have any federation or jurisdiction information compiled into them, so that a single set of
\fBDACS\fR
binaries can be shared by many jurisdictions (e\&.g\&., by multiple real or virtual web servers on the same host, or using NFS or some other file sharing mechanism)\&. But it means that (most) web services and commands need a run\-time mechanism to determine "who they are" \- which federation and jurisdiction are they acting on behalf of? For web services, this usually depends on the server name, hostname, port, scheme, URI path, some other context associated with the request, or a combination of these things\&. But it is sometimes most convenient to specify a jurisdiction name and have
\fBDACS\fR
work out what the request URIs to that jurisdiction look like, if it needs to\&.
.PP
Most
\fBDACS\fR
web services and commands need to obtain run\-time configuration information for the jurisdiction they represent\&. Because
dacs\&.conf
may specify the configuration of more than one jurisdiction, how do they know which
Jurisdiction
section they should use? In cases where
\fBDACS\fR
does not know the jurisdiction name, it searches for the correct
Jurisdiction
section and then determines the name of the jurisdiction; in cases where it is given the jurisdiction name, it searches
Jurisdiction
sections to find one with a directive that identifies the jurisdiction that it was given\&.
.PP
The applicable
Jurisdiction
section to use for a particular web service request or command can be determined in a variety of ways, using:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
the
\fB\-u\fR
command line flag to specify a
\fIconfig\-uri\fR
that is matched against
\m[blue]\fBeffective jurisdictional URIs\fR\m[]\&\s-2\u[19]\d\s+2;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
the
\fB\-uj\fR
command line flag to specify a
\fIjurisdiction\-name\fR
that is matched against
Jurisdiction
sections\*(Aq
JURISDICTION_NAME
directive;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
the
\fB\-us\fR
command line flag to indicate that there is only a single
Jurisdiction
section, so that section should be selected; or
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
by matching a request URI against
\m[blue]\fBeffective jurisdictional URIs\fR\m[]\&\s-2\u[19]\d\s+2\&.
.RE
.PP
Command line flags are described in
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[5]\d\s+2, as is the
\fBDEFAULT_JURISDICTION\fR
environment variable\&.
.PP
These methods will be described individually shortly\&.
.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
Because selection of the applicable
Jurisdiction
section is quite flexible, it may seem complicated\&. In practice, however, it is often rather simple, and particularly so if only one jurisdiction is being configured\&. It may be sufficient to read this section and skip the detail presented in the remainder of the discussion on how the
Jurisdiction
section is selected\&.
.sp .5v
.RE
.PP
If there is only one jurisdiction, its
uri
attribute value can simply be the domain name associated with the jurisdiction\&. Any of the command line flags could then be used (or none)\&. If the jurisdiction\*(Aqs domain name is
foo\&.example\&.com, for instance, the
Jurisdiction
section in
dacs\&.conf
might look like:
.sp
.if n \{\
.RS 4
.\}
.nf
JURISDICTION_NAME "FOO"
FEDERATION_DOMAIN "example\&.com"
# And so on\&.\&.\&.
.fi
.if n \{\
.RE
.\}
.PP
In the
\fBApache\fR
configuration file (httpd\&.conf), one might specify:
.sp
.if n \{\
.RS 4
.\}
.nf
AddDACSAuth dacs\-acs /usr/local/dacs/bin/dacs_acs "\-u foo\&.example\&.com"
.fi
.if n \{\
.RE
.\}
.sp
(which tells
\fBDACS\fR
that all web service requests from the web server or virtual host to which this directive applies should be associated with the domain
foo\&.example\&.com
for configuration purposes), or
.sp
.if n \{\
.RS 4
.\}
.nf
AddDACSAuth dacs\-acs /usr/local/dacs/bin/dacs_acs "\-us"
.fi
.if n \{\
.RE
.\}
.sp
(telling
\fBDACS\fR
that all web service requests from the web server or virtual host to which this directive applies should be associated with the only jurisdiction described in the configuration file, whatever that jurisdiction may be), or
.sp
.if n \{\
.RS 4
.\}
.nf
AddDACSAuth dacs\-acs /usr/local/dacs/bin/dacs_acs "\-uj FOO"
.fi
.if n \{\
.RE
.\}
.sp
(telling
\fBDACS\fR
that all web service requests from the web server or virtual host to which this directive applies should be associated with jurisdiction
FOO), or simply
.sp
.if n \{\
.RS 4
.\}
.nf
AddDACSAuth dacs\-acs /usr/local/dacs/bin/dacs_acs
.fi
.if n \{\
.RE
.\}
.sp
In the last case,
\fBDACS\fR
will match the request URI (which presumably looks like
https://foo\&.example\&.com/\&.\&.\&.) against
foo\&.example\&.com\&.
.PP
Multiple jurisdictions that are identified by distinct domain names are also easily configured once a
\fBDACS\fR
administrator decides how he would like request URIs to identify them\&. This is usually done much like this:
.sp
.if n \{\
.RS 4
.\}
.nf
JURISDICTION_NAME "FOO"
FEDERATION_DOMAIN "example\&.com"
# And so on\&.\&.\&.
JURISDICTION_NAME "BAZ"
FEDERATION_DOMAIN "example\&.com"
# And so on\&.\&.\&.
.fi
.if n \{\
.RE
.\}
.sp
And so that the domain name in the request URI is matched against the jurisdiction\*(Aqs effective URI, one would use:
.sp
.if n \{\
.RS 4
.\}
.nf
AddDACSAuth dacs\-acs /usr/local/dacs/bin/dacs_acs
.fi
.if n \{\
.RE
.\}
.PP
Multiple jurisdictions that share a domain name but are distinguished by a portion of the request URI pathname component, are often configured something like:
.sp
.if n \{\
.RS 4
.\}
.nf
JURISDICTION_NAME "FOO"
FEDERATION_DOMAIN "example\&.com"
# And so on\&.\&.\&.
JURISDICTION_NAME "BAZ"
FEDERATION_DOMAIN "example\&.com"
# And so on\&.\&.\&.
.fi
.if n \{\
.RE
.\}
.sp
And again using:
.sp
.if n \{\
.RS 4
.\}
.nf
AddDACSAuth dacs\-acs /usr/local/dacs/bin/dacs_acs
.fi
.if n \{\
.RE
.\}
.sp
With this style of configuration, a request for
https://example\&.com/foo/cgi\-bin/dacs/blah
would be directed to the configuration for the
FOO
jurisdiction\&.
.PP
Similarly, port numbers can also be used for
Jurisdiction
section selection:
.sp
.if n \{\
.RS 4
.\}
.nf
JURISDICTION_NAME "FOO"
FEDERATION_DOMAIN "example\&.com"
# And so on\&.\&.\&.
JURISDICTION_NAME "BAZ"
FEDERATION_DOMAIN "example\&.com"
# And so on\&.\&.\&.
.fi
.if n \{\
.RE
.\}
.PP
Lastly, a hostname wildcard syntax can be useful:
.sp
.if n \{\
.RS 4
.\}
.nf
JURISDICTION_NAME "FOO"
FEDERATION_DOMAIN "example\&.com"
# And so on\&.\&.\&.
JURISDICTION_NAME "BAZ"
FEDERATION_DOMAIN "example\&.com"
# And so on\&.\&.\&.
.fi
.if n \{\
.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
No check is made to ensure that the jurisdiction sections are unique\&. This is sometimes a useful feature but can also cause unexpected behaviour\&. It is probably best for all but the most advanced administrators to make sure that the same
JURISDICTION_NAME
directive doesn\*(Aqt appear in multiple
Jurisdiction
sections and that each section has a different effective jurisdictional URI\&.
.sp .5v
.RE
.PP
If your particular requirement has been covered, it is probably safe to skip the detail that follows\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBThe Effective Jurisdictional URI\fR
.RS 4
.PP
A
Jurisdiction
element must have either a
uri
attribute or a
uri_expr
attribute, but not both\&. If the latter is given, it specifies an
\m[blue]\fBexpression\fR\m[]\&\s-2\u[20]\d\s+2
that is evaluated at configuration processing time\&. The
effective jurisdictional URI
(or the jurisdiction\*(Aqs
effective URI) is either the value of the
uri
attribute or the value obtained by evaluating the
uri_expr
attribute\&. The effective jurisdictional URI can be matched against a request\*(Aqs URI or the
\fB\-u\fR
flag\*(Aqs
\fIconfig\-uri\fR
to find the applicable
Jurisdiction
section\&.
.PP
The standard set of
\m[blue]\fBconfiguration variables\fR\m[]\&\s-2\u[21]\d\s+2
in the
\fIConf\fR
and
\fIEnv\fR
\m[blue]\fBnamespace\fR\m[]\&\s-2\u[14]\d\s+2
(\fIbut no others\fR) are accessible during evaluation of
uri_expr\&. Consider this partial configuration:
.sp
.if n \{\
.RS 4
.\}
.nf
.fi
.if n \{\
.RE
.\}
.sp
Here, the effective jurisdictional URI is the value of the
\fBSERVER_NAME\fR
environment variable\&.
.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
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The environment established for a
\fBDACS\fR
web service and the environment of a
\fBDACS\fR
command are typically different, so programs run from the command line may fail if
uri_expr
references an undefined variable\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Any error that occurs during evaluation of
uri_expr
is fatal\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
One application of the
uri_expr
attribute is constructing a generic or "template"
Jurisdiction
section\&. For example, if multiple domain names need to map to the same jurisdiction, a
uri_expr
like the following can be used:
.sp
.if n \{\
.RS 4
.\}
.nf
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp .5v
.RE
.PP
The effective jurisdictional URI has the following syntax:
.sp
.if n \{\
.RS 4
.\}
.nf
uri \-> [scheme\-spec] [domain\-spec] [":" port\-spec] [path\-spec]
scheme\-spec \-> "http://" | "https://"
domain\-spec \-> domain\-name | "*\&." domain\-name | IP\-address
port\-spec \-> positive\-integer | positive\-integer "," port\-spec
path\-spec \-> "/" path\-segment | "/" path\-segment path\-spec
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBJurisdiction Selection by URI\fR
.RS 4
.PP
Whether the
Jurisdiction
section is selected based on the
\fB\-u\fR
flag\*(Aqs explicit
\fIconfig\-uri\fR
or the request URI provided to
\fBDACS\fR
through environment variables, the effective jurisdictional URIs are matched against the provided URI\&.
.PP
An effective jurisdictional URI has the following semantics for matching against the provided URI:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
If
uri
specifies the
http
scheme, the provided UR must not have used SSL/TLS; if
uri
specifies the
https
scheme, the provided URI must have used SSL/TLS; if neither scheme is specified, the scheme is immaterial\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The optional
\fIdomain\-spec\fR
specifies a domain name to match (case\-insensitively) against the provided URI\&. If the initial component of
\fIdomain\-spec\fR
is "*\&.", then only the components that follow it in
\fIdomain\-spec\fR
need to match the domain name in the provided URI\&. For example,
*\&.example\&.com
matches
example\&.com
and
foo\&.baz\&.example\&.com\&. If the
\fIdomain\-spec\fR
is omitted, the domain name in the provided URI is immaterial\&.
.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 matching algorithm does not consider domain names that map to the same IP address (i\&.e\&., aliases) to be equivalent\&.
.sp .5v
.RE
.sp
The
\fIdomain\-spec\fR
can be an IP address, but in this case the provided URI must also use an IP address for the two to match\&. That is, no mapping between IP addresses and domain names is performed\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The optional
\fIport\-spec\fR
consists of one or more port numbers, any one of which must match the one specified
\fIexplicitly\fR
(i\&.e\&., not by default) in the provided URI\&. If the provided URI does not contain a port, it will not match any
\fIport\-spec\fR\&. Port numbers are separated by a comma (with no embedded whitespace)\&. If the
\fIport\-spec\fR
is omitted, the port number in the provided URI is immaterial\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The optional
\fIpath\-spec\fR
must match the prefix of the provided URI\*(Aqs path component\&. Matching is case\-sensitive and is performed on corresponding
\fIpath\-segment\fR
elements\&.
.RE
.PP
The matching algorithm first rejects any
Jurisdiction
section having an effective jurisdictional URI that does not satisfy the
\fIscheme\-spec\fR
or the
\fIdomain\-spec\fR\&. It looks for the section that contains a matching
\fIport\-spec\fR
and that has the longest matching
\fIpath\-spec\fR; the first such section will be selected\&. If no such section is found, however, it looks for the section that does not contain a
\fIport\-spec\fR
and that has the longest matching
\fIpath\-spec\fR; the first such section will be selected\&. It is a fatal error if no section can be selected\&.
.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
While configuration of the
uri
attribute may appear to be complex, its value will typically be a simple hostname, or a simple hostname followed by a jurisdiction\-distinguishing initial path element, as in the example above\&. The flexible syntax allows jurisdictions to be associated with requests based on port numbers, use of SSL/TLS, etc\&. and lets dissimilar requests map to the same jurisdiction\&.
.sp .5v
.RE
.PP
For example, given the
\m[blue]\fBexample configuration\fR\m[]\&\s-2\u[22]\d\s+2
above, if the request URL is:
.sp
.if n \{\
.RS 4
.\}
.nf
https://dss\&.example\&.com/foo/cgi\-bin/dacs_authenticate
.fi
.if n \{\
.RE
.\}
.sp
then the second
Jurisdiction
section will be used\&.
.PP
If the request URL is:
.sp
.if n \{\
.RS 4
.\}
.nf
https://dss\&.example\&.com/cgi\-bin/dacs_authenticate
.fi
.if n \{\
.RE
.\}
.sp
then the first
Jurisdiction
section will be used\&.
.PP
If a
\fBDACS\fR
utility is invoked with the command line flag
\fB\-u\fR
metalogic\&.example\&.com, the third
Jurisdiction
section will be used\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBJurisdiction Selection by Jurisdiction Name\fR
.RS 4
.PP
The applicable
Jurisdiction
section can be selected by providing the jurisdiction\*(Aqs name\&. The
\fB\-uj\fR
flag\*(Aqs
\fIjurisdiction\-name\fR
argument is compared against the
\fIunevaluated\fR
value of each section\*(Aqs
JURISDICTION_NAME
directive until the first exact string match is found; the section containing the directive will be selected\&.
.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 the unevaluated value of the directive is used, if the value of a
JURISDICTION_NAME
is not a simple string, this option will not work unless
\fIjurisdiction\-name\fR
is that expression, not its value\&. Appropriate quotes are implied around
\fIjurisdiction\-name\fR, so they should be omitted on the command line\&.
.PP
For example, given the (partial) configuration file entry:
.sp
.if n \{\
.RS 4
.\}
.nf
JURISDICTION_NAME "DEMO"
\&.\&.\&.
.fi
.if n \{\
.RE
.\}
.sp
the command line argument "\fB\-uj\fR
DEMO" would select that jurisdiction section\&. If instead
JURISDICTION_NAME
were an expression that
\fIevaluated\fR
to the string
DEMO, the argument would not select that jurisdiction section\&.
.sp .5v
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBJurisdiction Selection by Default\fR
.RS 4
.PP
If
dacs\&.conf
contains a single
Jurisdiction
section, the
\fB\-us\fR
flag can be used to select it without regard to the jurisdiction\*(Aqs name or effective jurisdictional URI\&. This can be particularly useful during testing\&.
.PP
Should there be more than one
Jurisdiction
section when this flag is used, a fatal error will occur\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBThe Distinguishing URI\fR
.RS 4
.PP
Regardless of how the
Jurisdiction
section is selected, that section\*(Aqs effective jurisdictional URI is matched against the
\fB\-u\fR
flag\*(Aqs
\fIconfig\-uri\fR, if given, or the request URI according to the method described for
\m[blue]\fBJurisdiction Selection by URI\fR\m[]\&\s-2\u[23]\d\s+2\&. The resulting string is called the
distinguishing URI\&. This string is another way of identifying the selected
Jurisdiction
section and can be used for
\m[blue]\fBstring interpolation\fR\m[]\&\s-2\u[24]\d\s+2\&. It is also related to the
shared
attribute used in
\m[blue]\fBaccess control rules\fR\m[]\&\s-2\u[25]\d\s+2\&.
.PP
For example, if the request URI is
http://foo\&.example\&.com/a/b/c
and the matching effective jurisdictional URI is
*\&.example\&.com/a/b, then the distinguishing URI is
foo\&.example\&.com/a/b\&.
.RE
.SS "Directives"
.PP
Each directive consists of a directive name, followed by whitespace (spaces and/or tabs), followed by its value\&. Directive names are case\-sensitive and comprised of printable characters, except the space character, and are upper case\&.
.PP
A directive value is an expression or sequence of expressions (\m[blue]\fBdacs\&.exprs(5)\fR\m[]\&\s-2\u[20]\d\s+2) that is evaluated at run time during configuration processing\&. Here are some directives that are equivalent (on a Saturday):
.sp
.if n \{\
.RS 4
.\}
.nf
AUTH_FAIL_DELAY_SECS 2
AUTH_FAIL_DELAY_SECS "2"
AUTH_FAIL_DELAY_SECS 1 + 1
AUTH_FAIL_DELAY_SECS strftime("%a") eq:i "Sat" ? 2 : 17
.fi
.if n \{\
.RE
.\}
.PP
Blank lines, leading white space, and lines whose first non\-white space character is a
#
character (i\&.e\&., comments) are ignored\&.
.PP
Any directive line may be split over physical lines by escaping the newline character, for example:
.sp
.if n \{\
.RS 4
.\}
.nf
ACS_ERROR_HANDLER "902 \*(AqAccess denied, \e
user not authenticated\*(Aq"
.fi
.if n \{\
.RE
.\}
.PP
Processing an unrecognized directive name causes a fatal error, as does an error encountered during expression evaluation\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBEvaluated Directives\fR
.RS 4
.PP
Some directive names end with a
*
character\&. By convention, this means that the directive\*(Aqs value will be evaluated a second time, in the context of a particular module or service request, but only if the directive value is actually needed\&. This allows a configuration directive to reference a variable that cannot be instantiated until normal configuration file processing has been performed, for instance\&. The values of these directives usually appear within single quotes so that they initially evaluate to the string between the quotes\&.
.PP
Consider this
\m[blue]\fBINIT*\fR\m[]\&\s-2\u[26]\d\s+2
directive, which might appear within an
\m[blue]\fBAuth clause\fR\m[]\&\s-2\u[27]\d\s+2:
.sp
.if n \{\
.RS 4
.\}
.nf
INIT* \*(Aq${Auth::CURRENT_USERNAME} = "goa\e\e" \&. ${Auth::CURRENT_USERNAME}\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
Because the directive\*(Aqs value appears within single quotes, the quoted expression is not evaluated during the first scan of the directive (or more accurately, it evaluates to an unquoted expression); this is as it should be because the value of the referenced variable is not known at that time, nor has it been determined whether the directive will even be needed\&. Later, if the
Auth
clause containing this directive is used, the variable\*(Aqs value is presumably known and the formerly quoted expression is evaluated, yielding a final value for the directive\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBDirective Categories\fR
.RS 4
.PP
After
\m[blue]\fBsection merging\fR\m[]\&\s-2\u[28]\d\s+2
is performed, some directives must be specified while others are optional\&. Some may appear at most once and others may be repeated\&. The following labels are used to categorize directives:
.PP
Required1:
.RS 4
Directives of this category must be defined and must appear only once after merging\&.
.RE
.PP
Required1\-C:
.RS 4
Under certain conditions, these directives must be defined and appear only once after merging, otherwise they need not appear\&. For example, some directives are required if and only if the module that requires them is configured\&.
.RE
.PP
Required:
.RS 4
These directives must always be specified at least once after merging, and may be repeated\&.
.RE
.PP
Optional1:
.RS 4
These directives may appear at most once after merging\&.
.RE
.PP
Optional:
.RS 4
These directives may appear zero or more times after merging\&.
.RE
.PP
Stack:
.RS 4
This is like the
Optional
type, in that the directive may appear multiple times in any section, except the usual section merging algorithm is not used\&. Instead, all occurrences of the directive in the
Jurisdiction
section, then in the
Default
section of
dacs\&.conf, and then in
site\&.conf
will be "stacked", in the order in which they appear in each section\&. Selection is dependent on the particular directive, which will effectively search the directives in the
Jurisdiction
section first to find an applicable directive, then search the directives in the
Default
section of
dacs\&.conf
if necessary, and finally search
site\&.conf
if necessary\&.
.RE
.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 directive marked
Deprecated
will be removed in a future version and should not be used\&.
.sp .5v
.RE
.PP
Some directives have more complicated constraints on their usage; they might be allowed only in certain contexts or are required only in certain situations (e\&.g\&., directives associated with proxied operation are only required if that mode of operation is being used)\&.
.PP
Required directives must be present and assigned a valid value, although the validity of a value is only checked if the directive is actually used\&. It is okay to define directives that are not used; for example, directives related to InfoCards may appear in a configuration file even if InfoCard support is not enabled at the time
\fBDACS\fR
is built\&. Some configuration directives may appear multiple times, others only once\&. The order in which configuration directives appear within a section is not usually significant, although it may be in cases where the directive is repeated (e\&.g\&.,
ACS_ERROR_HANDLER) and for clauses (e\&.g\&., the
Auth
clause)\&.
.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
Directives that expect to be assigned a value of
yes,
no,
on, or
off
recognize these keywords case\-insensitively\&.
.sp .5v
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBGeneral Directives\fR
.RS 4
.PP
The following general directives are provided\&. If present, they must appear within any
Default
section or
Jurisdiction
section, but outside of any clauses\&.
.PP
\fBDirective Index:\fR
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
ACCEPT_ALIEN_CREDENTIALS (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
ACS_ACCESS_TOKEN_ENABLE (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
ACS_ACCESS_TOKEN_LIFETIME_LIMIT (Required1\-C)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
ACS_ACCESS_TOKEN_LIFETIME_SECS (Required1\-C)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
ACS_AUTHENTICATED_ONLY (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 6." 4.2
.\}
ACS_CREDENTIALS_LIMIT (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 7.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 7." 4.2
.\}
ACS_EMIT_APPROVAL (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 8.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 8." 4.2
.\}
ACS_ERROR_HANDLER (Stack)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 9.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 9." 4.2
.\}
ACS_FAIL (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'10.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "10." 4.2
.\}
ACS_INACTIVITY_LIMIT_SECS (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'11.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "11." 4.2
.\}
ACS_POST_BUFFER_LIMIT (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'12.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "12." 4.2
.\}
ACS_POST_EXCEPTION_MODE (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'13.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "13." 4.2
.\}
ACS_PRE_AUTH (Optional)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'14.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "14." 4.2
.\}
ACS_SUCCESS (Optional)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'15.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "15." 4.2
.\}
ACS_TRACK_ACTIVITY (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'16.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "16." 4.2
.\}
ADMIN_IDENTITY (Optional)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'17.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "17." 4.2
.\}
ALLOW_HTTP_COOKIE (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'18.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "18." 4.2
.\}
AUTH_AGENT_ALLOW_ADMIN_IDENTITY (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'19.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "19." 4.2
.\}
AUTH_CREDENTIALS_ADMIN_LIFETIME_SECS (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'20.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "20." 4.2
.\}
AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS (Required1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'21.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "21." 4.2
.\}
AUTH_ERROR_HANDLER (Stack)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'22.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "22." 4.2
.\}
AUTH_FAIL (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'23.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "23." 4.2
.\}
AUTH_FAIL_DELAY_SECS (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'24.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "24." 4.2
.\}
AUTH_SINGLE_COOKIE (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'25.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "25." 4.2
.\}
AUTH_SUCCESS (Optional)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'26.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "26." 4.2
.\}
AUTH_SUCCESS_HANDLER (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'27.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "27." 4.2
.\}
AUTH_TRANSFER_EXPORT (Optional)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'28.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "28." 4.2
.\}
AUTH_TRANSFER_TOKEN_LIFETIME_SECS (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'29.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "29." 4.2
.\}
COMPAT_MODE (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'30.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "30." 4.2
.\}
COOKIE_HTTPONLY (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'31.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "31." 4.2
.\}
COOKIE_NAME_TERMINATORS (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'32.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "32." 4.2
.\}
COOKIE_NO_DOMAIN (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'33.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "33." 4.2
.\}
COOKIE_PATH (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'34.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "34." 4.2
.\}
CSS_PATH (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'35.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "35." 4.2
.\}
DTD_BASE_URL (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'36.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "36." 4.2
.\}
EVAL (Optional)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'37.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "37." 4.2
.\}
FEDERATION_DOMAIN (Required1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'38.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "38." 4.2
.\}
FEDERATION_NAME (Required1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'39.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "39." 4.2
.\}
HTTP_AUTH (Stack)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'40.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "40." 4.2
.\}
HTTP_AUTH_ENABLE (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'41.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "41." 4.2
.\}
HTTP_PROG (Required1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'42.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "42." 4.2
.\}
INFOCARD_AUDIENCE (Optional)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'43.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "43." 4.2
.\}
INFOCARD_AUDIENCE_RESTRICTION (Optional)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'44.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "44." 4.2
.\}
INFOCARD_CARD_DEFS_URL (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'45.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "45." 4.2
.\}
INFOCARD_CARD_FILL_URL (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'46.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "46." 4.2
.\}
INFOCARD_CARD_IMAGE_BASE_URL (Required1\-C)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'47.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "47." 4.2
.\}
INFOCARD_CARD_LIFETIME_SECS (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'48.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "48." 4.2
.\}
INFOCARD_CARD_OUTPUTDIR (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'49.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "49." 4.2
.\}
INFOCARD_CARD_VERSION (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'50.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "50." 4.2
.\}
INFOCARD_CARDID_BASE_URL (Required1\-C)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'51.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "51." 4.2
.\}
INFOCARD_CARDID_SUFFIX (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'52.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "52." 4.2
.\}
INFOCARD_CARD_DATETIME_EXPIRES (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'53.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "53." 4.2
.\}
INFOCARD_DIGEST (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'54.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "54." 4.2
.\}
INFOCARD_IP_PRIVACY_URL (Required1\-C)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'55.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "55." 4.2
.\}
INFOCARD_IP_PRIVACY_VERSION (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'56.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "56." 4.2
.\}
INFOCARD_ISSUER_INFO_ENTRY (Optional)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'57.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "57." 4.2
.\}
INFOCARD_MEX_URL (Required1\-C)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'58.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "58." 4.2
.\}
INFOCARD_REQUIRE_APPLIES_TO (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'59.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "59." 4.2
.\}
INFOCARD_STRONG_RP_IDENTITY (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'60.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "60." 4.2
.\}
INFOCARD_STS_AUTH_TYPE (Required1\-C)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'61.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "61." 4.2
.\}
INFOCARD_STS_CACERTFILE (Required1\-C)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'62.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "62." 4.2
.\}
INFOCARD_STS_CERTFILE (Required1\-C)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'63.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "63." 4.2
.\}
INFOCARD_STS_KEYFILE (Required1\-C)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'64.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "64." 4.2
.\}
INFOCARD_STS_KEYFILE_PASSWORD (Required1\-C)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'65.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "65." 4.2
.\}
INFOCARD_STS_PASSWORD_METHOD (Required1\-C)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'66.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "66." 4.2
.\}
INFOCARD_STS_RP_ENDPOINT (Optional)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'67.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "67." 4.2
.\}
INFOCARD_TOKEN_DRIFT_SECS (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'68.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "68." 4.2
.\}
INFOCARD_TOKEN_ISSUER (Required1\-C)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'69.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "69." 4.2
.\}
INFOCARD_TOKEN_LIFETIME_SECS (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'70.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "70." 4.2
.\}
INFOCARD_TOKEN_MAX_LENGTH (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'71.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "71." 4.2
.\}
INFOCARD_USERNAME_SELECTOR (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'72.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "72." 4.2
.\}
JURISDICTION_NAME (Required1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'73.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "73." 4.2
.\}
LOGINGEN_FILE (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'74.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "74." 4.2
.\}
LOGINGEN_PROG (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'75.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "75." 4.2
.\}
LOG_FILE (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'76.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "76." 4.2
.\}
LOG_FILTER (Stack)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'77.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "77." 4.2
.\}
LOG_FORMAT (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'78.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "78." 4.2
.\}
LOG_LEVEL (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'79.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "79." 4.2
.\}
LOG_SENSITIVE (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'80.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "80." 4.2
.\}
NAME_COMPARE (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'81.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "81." 4.2
.\}
NOTICES_ACCEPT_HANDLER (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'82.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "82." 4.2
.\}
NOTICES_ACK_HANDLER (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'83.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "83." 4.2
.\}
NOTICES_DECLINE_HANDLER (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'84.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "84." 4.2
.\}
NOTICES_NAT_NAME_PREFIX (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'85.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "85." 4.2
.\}
NOTICES_SECURE_HANDLER (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'86.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "86." 4.2
.\}
NOTICES_WORKFLOW_LIFETIME_SECS (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'87.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "87." 4.2
.\}
PAMD_HOST (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'88.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "88." 4.2
.\}
PAMD_PORT (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'89.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "89." 4.2
.\}
PASSWORD_CONSTRAINTS (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'90.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "90." 4.2
.\}
PASSWORD_DIGEST (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'91.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "91." 4.2
.\}
PASSWORD_OPS_NEED_PASSWORD (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'92.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "92." 4.2
.\}
PASSWORD_SALT_PREFIX (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'93.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "93." 4.2
.\}
PERMIT_CHAINING (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'94.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "94." 4.2
.\}
PROXY_EXEC_DOCUMENT_ROOT (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'95.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "95." 4.2
.\}
PROXY_EXEC_MAPPER_DEFAULT_ACTION (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'96.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "96." 4.2
.\}
PROXY_EXEC_MAPPER_LOGGING (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'97.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "97." 4.2
.\}
PROXY_EXEC_MAPPER_LOG_FILE (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'98.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "98." 4.2
.\}
PROXY_EXEC_MAPPER_RULES_FILE (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'99.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "99." 4.2
.\}
PROXY_EXEC_PROG_URI (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'100.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "100." 4.2
.\}
RLINK (Optional)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'101.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "101." 4.2
.\}
ROLE_STRING_MAX_LENGTH (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'102.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "102." 4.2
.\}
SECURE_MODE (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'103.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "103." 4.2
.\}
SIGNOUT_HANDLER (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'104.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "104." 4.2
.\}
SSL_PROG (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'105.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "105." 4.2
.\}
SSL_PROG_ARGS (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'106.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "106." 4.2
.\}
SSL_PROG_CA_CRT (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'107.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "107." 4.2
.\}
SSL_PROG_CLIENT_CRT (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'108.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "108." 4.2
.\}
STATUS_LINE (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'109.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "109." 4.2
.\}
TEMP_DIRECTORY (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'110.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "110." 4.2
.\}
TOKEN_REQUIRES_PIN (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'111.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "111." 4.2
.\}
TOKEN_HOTP_ACCEPT_WINDOW (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'112.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "112." 4.2
.\}
TRACE_LEVEL (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'113.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "113." 4.2
.\}
UNAUTH_ROLES (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'114.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "114." 4.2
.\}
UPROXY_APPROVED (Stack)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'115.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "115." 4.2
.\}
VERBOSE_LEVEL (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'116.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "116." 4.2
.\}
VERIFY_IP (Required1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'117.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "117." 4.2
.\}
VERIFY_UA (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'118.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "118." 4.2
.\}
VFS (Stack)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'119.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "119." 4.2
.\}
XSD_BASE_URL (Optional1)
.RE
.PP
ACCEPT_ALIEN_CREDENTIALS (Optional1)
.RS 4
If "yes",
\fBDACS\fR
will honour credentials imported (by any means) from a different federation\&. As a security precaution, such credentials are not used by default\&.
.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
In federations where
\m[blue]\fBdacs_auth_transfer(8)\fR\m[]\&\s-2\u[29]\d\s+2
is used, jurisdictions will likely enable this capability\&.
.sp .5v
.RE
.RE
.PP
ACS_ACCESS_TOKEN_ENABLE (Optional1)
.RS 4
If "yes",
\fBACS\fR\*(Aqs access token mechanism will be enabled\&. By default, this feature is disabled\&. Please see
\m[blue]\fBAuthorization Caching\fR\m[]\&\s-2\u[30]\d\s+2
for details\&.
.RE
.PP
ACS_ACCESS_TOKEN_LIFETIME_LIMIT (Required1\-C)
.RS 4
If
\fBACS\fR\*(Aqs access token mechanism has been enabled, this is the number of times that an access token may be used\&. It must be an integer greater than zero\&. There is no default value\&. This value,
ACS_ACCESS_TOKEN_LIFETIME_SECS, or both must be configured properly if the mechanism is enabled\&. Because it requires updating a database entry, this method of enforcing a limit on the lifetime of an access token is inherently less efficient than using
ACS_ACCESS_TOKEN_LIFETIME_SECS\&. Changes to this limit do not affect access tokens that have already been issued\&. Please see
\m[blue]\fBAuthorization Caching\fR\m[]\&\s-2\u[30]\d\s+2
for details\&.
.RE
.PP
ACS_ACCESS_TOKEN_LIFETIME_SECS (Required1\-C)
.RS 4
If
\fBACS\fR\*(Aqs access token mechanism has been enabled, this is the lifetime in seconds of an access token, and must be an integer greater than zero\&. There is no default value\&. This value,
ACS_ACCESS_TOKEN_LIFETIME_LIMIT, or both must be configured properly if the mechanism is enabled\&. Please see
\m[blue]\fBAuthorization Caching\fR\m[]\&\s-2\u[30]\d\s+2
for details\&.
.RE
.PP
ACS_AUTHENTICATED_ONLY (Optional1)
.RS 4
If "yes",
\fBACS\fR
will deny all requests that are not accompanied by valid credentials, regardless of any access control rules or other directives\&.
.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
Since this restriction also applies to
\fBDACS\fR
services, if this mode is enabled an unauthenticated user will not be able to access
\fBDACS\fR
services by which he might authenticate himself\&. Users must therefore have authenticated before this directive is enabled, authenticate using an off\-line method (such as
\m[blue]\fBdacscookie(1)\fR\m[]\&\s-2\u[31]\d\s+2
or
\m[blue]\fBdacsauth(1)\fR\m[]\&\s-2\u[32]\d\s+2), or authenticate at some other jurisdiction\&.
.sp .5v
.RE
.RE
.PP
ACS_CREDENTIALS_LIMIT (Optional1)
.RS 4
The value of this directive is either an unsigned integer greater than zero, or the keyword "none" (case insensitive)\&. In the former case, if a request is submitted with more than this number of valid credentials, the request will be denied with the
REVOKED
error (equivalent to error code
\fB903\fR)\&.
.sp
Probably the most common application of this directive is to limit each request to being associated with at most one identity\&. The standard site configuration sets
ACS_CREDENTIALS_LIMIT
to one\&. This eliminates confusion about which identity invoked a web service (i\&.e\&., which identity
\fBREMOTE_USER\fR
should be set to, for instance) and ambiguity regarding the semantics of rules, and in some cases may simplify access control rules and log file audits\&.
.sp
A user denied access at a jurisdiction due to this directive will be denied access to
\m[blue]\fBdacs_signout(8)\fR\m[]\&\s-2\u[33]\d\s+2
at the jurisdiction\&. To regain access to the jurisdiction, the user will either need to signout from a different jurisdiction or delete one or more sets of credentials (cookies) from his browser, either using the browser\*(Aqs cookie manager or by terminating the browser session\&.
.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
It is possible for a user that is not denied access at a jurisdiction due to this directive to successfully authenticate, after which he will have "too many" credentials and subsequently be denied access\&. Similarly, a
\fBDACS\fR
administrator may reduce the limit at any time, potentially causing access to be denied to users holding a number of credentials in excess of the limit\&.
.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
\fBSecurity\fR
.ps -1
.br
This directive only limits the number of credentials associated with a single request\&. It does not prevent the same individual from sending different requests, from the same browser or different browsers, each associated with a different identity\&. Also, it does not limit the number of concurrent logins of the same identity (such as by different individuals sharing the same account)\&.
.sp
\fBDACS\fR
does not limit a user\*(Aqs number of concurrent logins or the number of concurrent logins of the same identity because of the inherent drawbacks of a general implementation of such a feature\&. In simple cases, however, an administrator may be able to add a custom solution to
\fBDACS\fR\&.
.sp .5v
.RE
.RE
.PP
ACS_EMIT_APPROVAL (Optional1)
.RS 4
If "yes",
\fBDACS\fR
will generate a
\fBDACS_APPROVAL\fR
environment variable that can be inspected by an invoked program to verify that its use in the current context was authorized by
\fBDACS\fR\&. Before this feature is enabled, additional configuration is necessary; see
\m[blue]\fBThe DACS_APPROVAL environment variable\fR\m[]\&\s-2\u[34]\d\s+2
for details\&.
.RE
.PP
ACS_ERROR_HANDLER (Stack)
.RS 4
If
\fBDACS\fR
denies a service request, the web server\*(Aqs
\fBDACS\fR
module will be so informed and will return a
\fB403\fR
("Forbidden") status code to the web server\&. By using
\fBApache\*(Aqs\fR
ErrorDocument
directive, the resulting action taken by
\fBApache\fR
can be customized\&.
.sp
In some situations following denial of a request, however, it is desirable to initiate an action that depends on the reason for denial\&. For example, if access is denied because the user is not authenticated, the
\fBDACS\fR
administrator might want users to be redirected to a login page; if access is denied because an access control rule denies access although the user is authenticated, the administrator might want users to be redirected to a page that displays a custom error message\&. It is sometimes useful for the action to depend on the resource being requested\&.
.sp
The
ACS_ERROR_HANDLER
directive defines (or overrides)
\fBApache\fR\*(Aqs behaviour with respect to an
ErrorDocument
directive for
\fB403\fR
errors if
\fBDACS\fR
denies a service request\&. The syntax and meaning of this directive are similar to that of
\fBApache\fR\*(Aqs
ErrorDocument
directive\&. Please refer to the
\fBApache\fR
documentation for a
\m[blue]\fBdescription of the ErrorDocument directive\fR\m[]\&\s-2\u[35]\d\s+2\&.
.sp
Also refer to the description of the
\m[blue]\fBredirect()\fR\m[]\&\s-2\u[36]\d\s+2
function\&.
.sp
The syntax of the directive is:
.sp
.if n \{\
.RS 4
.\}
.nf
[\fIurl_pattern\fR] \fIerror\-code\fR [\fIhandler\-type\fR] [\fIerror\-action\fR]
.fi
.if n \{\
.RE
.\}
.sp
The optional
\fIurl_pattern\fR
is a URI path component that is matched against the request for which access was denied\&. It must begin with a \*(Aq/\*(Aq\&. It is like the
\fIurl_pattern\fR
used in
\m[blue]\fBaccess control rules\fR\m[]\&\s-2\u[37]\d\s+2
in that it can require an exact match or end in "/*"; no query argument component is allowed\&. If it is absent, the
\fIurl_pattern\fR
defaults to "/*", which matches any path\&.
.sp
The
\fIerror\-code\fR
is either a numeric error code, an equivalent case\-insensitive
\fIerror\-name\fR, or the special symbol "*", which means the directive applies to any
\fBDACS\fR
error code for which there is no explicit directive\&.
.sp
The following
\fIerror\-name\fR
and
\fIerror\-code\fR
values are defined:
.PP
NO_RULE (\fB900\fR)
.br
Access denied, no applicable rule
.RS 4
All rules were examined but no rule applies to the service request\&.
.RE
.PP
BY_RULE (\fB901\fR)
.br
Access denied, forbidden by rule
.RS 4
The closest matching rule does not grant the service request\&.
.RE
.PP
NO_AUTH (\fB902\fR)
.br
Access denied, user not authenticated
.RS 4
No valid credentials were provided and either a) no rule applies or b) the rule does not grant the service request\&.
.RE
.PP
REVOKED (\fB903\fR)
.br
Access denied, user access revoked
.RS 4
Credentials were explicitly revoked\&.
.RE
.PP
BY_REDIRECT (\fB904\fR)
.br
Access denied, redirect
.RS 4
A rule has explicitly redirected the user\&.
.RE
.PP
ACK_NEEDED (\fB905\fR)
.br
Access denied, acknowledgement needed
.RS 4
One or more notices associated with the request must be acknowledged\&.
.RE
.PP
LOW_AUTH (\fB906\fR)
.br
Access denied, low authentication level
.RS 4
Although valid credentials were provided, they were obtained by an authentication method not strong enough for the requested resource\&.
.RE
.PP
BY_SIMPLE_REDIRECT (\fB907\fR)
.br
Access denied, simple redirect
.RS 4
A rule has explicitly redirected the user; do not append
\fBDACS\fR
query arguments\&.
.RE
.PP
CREDENTIALS_LIMIT (\fB908\fR)
.br
Access denied, too many credentials were submitted
.RS 4
Too many selected credentials accompanied the request\&.
.RE
.PP
INACTIVITY (\fB909\fR)
.br
Access denied, inactivity timeout
.RS 4
No authenticated requests were made within a designated time interval\&.
.RE
.PP
ADMIN_REQUIRED (\fB910\fR)
.br
Access denied, administrator credentials required
.RS 4
Access was denied because credentials that satisfy
\m[blue]\fBdacs_admin()\fR\m[]\&\s-2\u[38]\d\s+2
were not sent with the request\&. Although this may not be the sole reason for access to be denied, it should be taken as a hint that the request is likely to succeed if it is retried with administrator credentials\&. Also see
\m[blue]\fBADMIN_IDENTITY\fR\m[]\&\s-2\u[39]\d\s+2\&.
.RE
.PP
UNKNOWN (\fB998\fR)
.br
Access denied, reason unknown
.RS 4
An error occurred during processing but no additional information is available\&.
.RE
.PP
DEFAULT (*)
.br
Control symbol
.RS 4
Not an error name, but a keyword used with
ACS_ERROR_HANDLER
to configure a handler to invoke if no handler is explicitly configured for the event\&.
.RE
.sp
No blanks may precede the code, any number of blanks may follow it\&. The descriptive\-text consists only of printable characters (e\&.g\&., no tabs or newlines) and may not contain a colon\&. The descriptive\-text is subject to change, but the meaning of the code number is fixed\&. When
\fBDACS\fR
returns a numeric error code, a program only needs to examine the three digit code to determine why access was denied\&. Optionally, the standard text may be followed by a single space, a colon, at least one space, and a more detailed error message\&.
.sp
If a
\fIhandler\-type\fR
keyword appears, it selects the action the handler should take and disables the heuristics that would otherwise be used to decide the type based on the syntax of the
\fIerror\-action\fR\&. The
reason
and
default
keywords are the only
\fIhandler\-type\fR
keyword that are not followed by an
\fIerror\-action\fR\&.
.sp
The following
\fIhandler\-type\fR
keywords and
\fIerror\-action\fR
arguments are recognized:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
reason
.sp
\fBDACS\fR
will cause
\fBApache\fR
to display the
\fBDACS\fR
error code that identifies the reason for denying access followed by the corresponding textual message\&.
\fBApache\fR
might display messages like the following:
.sp
.if n \{\
.RS 4
.\}
.nf
900 Access denied, no applicable access control rule
998 Access denied, internal error: Cookie parse error
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
default
.sp
This form instructs
\fBDACS\fR
not to alter
\fBApache\*(Aqs\fR
behaviour (as if there was no
ACS_ERROR_HANDLER
specified at all)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
[url]
\fIURL\fR
.sp
This form will cause
\fBApache\fR
to redirect the client to
\fIURL\fR
using the
GET
method\&. If the
url
keyword is absent,
\fIURL\fR
must begin with the four characters "http"\&. An invalid
\fIURL\fR
may be rejected by Apache and treated as a message\&. The
\fIURL\fR
may contain a properly escaped query string;
\fBDACS\fR
will append the following parameters, in the order given, to
\fIURL\fR
(unless the error name is
BY_SIMPLE_REDIRECT, in which case none of these parameters is passed):
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
\fIDACS_ERROR_CODE\fR, the
\fBDACS\fR
error code\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
\fIDACS_VERSION\fR, the version number of
\fBDACS\fR
(e\&.g\&., "1\&.4")\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
\fIDACS_FEDERATION\fR, the federation that received the service request, if available\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
\fIDACS_JURISDICTION\fR, the jurisdiction that received the service request, if available\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
\fIDACS_HOSTNAME\fR, the domain name of the host that received the service request, if available\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 6." 4.2
.\}
\fIDACS_USER_AGENT\fR, if provided by the user agent, this is an identifying string, such as:
.sp
.if n \{\
.RS 4
.\}
.nf
Mozilla/3\&.01 (X11; U; Linux 2\&.4\&.2 i386)
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 7.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 7." 4.2
.\}
\fIDACS_REQUEST_METHOD\fR, the method used to invoke the service request, if available\&. For example, "GET" or "POST"\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 8.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 8." 4.2
.\}
\fIDACS_ERROR_URL\fR, the service request URL, including any query string component\&. The values of these parameters are URL encoded\&.
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
[localurl]
/\fIlocal\-URL\fR
.sp
This form is similar to the absolute URL form except that redirection is to a local URL\-path\&. The
\fIerror\-action\fR
must begin with a slash\&. The URL may contain a properly escaped query string;
\fBDACS\fR
will append additional parameters as in the absolute URL form\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
[message] \e"\fIa message\fR\e"
.sp
This form causes
\fBApache\fR
to emit the given string as the error document\&. If the
message
keyword is absent, the string must be surrounded by double quote characters (the quotes do not appear in the final output message)\&.
.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
Apache always sets the
Content\-Type
for this message to
text/html\&. Although reported quite some time ago,
\m[blue]\fBBug 3641\fR\m[]\&\s-2\u[40]\d\s+2
is still open\&. There may be a bug in Apache 2\&.X that prevents the initial double quote in the message from being stripped; see
\m[blue]\fBBug 42430\fR\m[]\&\s-2\u[41]\d\s+2\&.
.sp .5v
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 6." 4.2
.\}
expr
\fIexpression\fR
.sp
The
expr
keyword, which cannot be omitted, indicates that the
\fIerror\-action\fR
is an expression\&. The
\fIexpression\fR
is evaluated and its value (a string) is used as the Apache error response\&. If an error occurs during evaluation, the Apache
ErrorDocument
or default behaviour will be used\&.
.RE
.sp
This directive may appear multiple times\&. Because these directives are stacked, during handler processing directives are examined "backwards", starting from the last one that appears in the relevant jurisdiction section through to the first one that appears in the default section of
dacs\&.conf
and backwards through
site\&.conf\&. The first directive having a
\fIurl_pattern\fR
\fIand\fR
\fIerror\-code\fR
that match the error condition exactly is used\&. Otherwise, if no such exact match if found, the first directive encountered having the closest
\fIurl_pattern\fR
match and exact
\fIerror\-code\fR
match is used; failing that, the first directive with the closest
\fIurl_pattern\fR
match and default ("*")
\fIerror\-code\fR
match is used\&.
.sp
Consider these example directives:
.sp
.if n \{\
.RS 4
.\}
.nf
ACS_ERROR_HANDLER "* reason"
ACS_ERROR_HANDLER \*(Aq903 "Your access has been revoked"\*(Aq
ACS_ERROR_HANDLER "/foo/* * /cgi\-bin/dacs/foohandler"
ACS_ERROR_HANDLER "/foo/foo\&.html NO_AUTH /cgi\-bin/foo\-login\&.cgi"
.fi
.if n \{\
.RE
.\}
.sp
A request for
/foo/foo\&.html
that is denied because the user is not authenticated will cause a redirect to
/cgi\-bin/foo\-login\&.cgi\&. If the request is denied for a different reason, the third directive will be used, causing a redirect to
/cgi\-bin/dacs/foohandler\&. A request for something not located under
/foo
that is denied because access is revoked will cause the message specified in the second directive to be displayed to the user, while any other type of error will cause an appropriate explanatory message to be displayed\&.
.sp
Here is an example of the
expr
handler form:
.sp
.if n \{\
.RS 4
.\}
.nf
ACS_ERROR_HANDLER "* expr \*(Aq\e"<em>Today is</em> \e" \&. strftime(\e"%D\e")\*(Aq"
.fi
.if n \{\
.RE
.\}
.sp
If triggered, this directive will emit a message similar to the following as Apache\*(Aqs custom error response:
.sp
.if n \{\
.RS 4
.\}
.nf
Today is 05/16/07
.fi
.if n \{\
.RE
.\}
.sp
As with all such messages, Apache forces the
Content\-Type
to be
text/html\&.
.sp
These two directives are equivalent:
.sp
.if n \{\
.RS 4
.\}
.nf
ACS_ERROR_HANDLER "* message \*(AqHello world\&.\*(Aq"
ACS_ERROR_HANDLER "* \e"Hello world\&.\e""
.fi
.if n \{\
.RE
.\}
.sp
The error response returned by Apache will be:
.sp
.if n \{\
.RS 4
.\}
.nf
Hello world\&.
.fi
.if n \{\
.RE
.\}
.sp
Any invalid directive will result in
\fBApache\fR
following its configured behaviour\&. A directive with a syntactically valid but undefined
\fIerror\-code\fR
is ignored, however\&.
.sp
In the case where the service request was issued by
\fBInternet Explorer\fR, if the length of the error response by the server isn\*(Aqt greater than some magic value and
\fBIE\fR\*(Aqs "Show friendly HTTP error messages" is enabled, which it is by default, then
\fBIE\fR
will ignore the custom message\&. When the "message" and "reason" handler types are used,
\fBDACS\fR
adds some padding to thwart
\fBIE\fR\*(Aqs "cleverness"\&. For other handler types, the administrator is responsible for working around this problem\&.
.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
Care must be taken to avoid improper operation (such as a potentially infinite regress) if a CGI program invoked to handle an error is itself protected by
\fBDACS\fR\&. One example is the situation where a user\*(Aqs access has been revoked and is therefore unable to access any
\fBDACS\fR\-protected resource\&. If an error occurs while
\fBDACS\fR
is processing a request for a handler,
\fBDACS\fR
will fall back to
\fBApache\fR\*(Aqs default behaviour, ignoring any normally applicable
ACS_ERROR_HANDLER
directives\&.
.sp .5v
.RE
.RE
.PP
ACS_FAIL (Optional1)
.RS 4
If
\fBdacs_acs\fR
denies access, the given expression is evaluated just before the
\m[blue]\fBACS_ERROR_HANDLER\fR\m[]\&\s-2\u[18]\d\s+2
directive, if any, is processed\&. This directive provides a hook for post\-authorization actions to be performed\&. The namespaces in effect during authorization processing are accessible to the expression\&. The value of the expression is discarded and any errors are ignored\&.
.RE
.PP
ACS_INACTIVITY_LIMIT_SECS (Optional1)
.RS 4
This directive enables inactivity detection if it is set to a non\-zero unsigned integer\&. Inactivity detection is applicable only when valid selected credentials accompany a request (i\&.e\&., at least one identity is associated with the request \- see
\m[blue]\fBdacs_select_credentials(8)\fR\m[]\&\s-2\u[42]\d\s+2)\&.
.sp
There are two cases\&. If an activity tracking cookie is not sent with the current request (see
\m[blue]\fBACS_TRACK_ACTIVITY\fR\m[]\&\s-2\u[43]\d\s+2), the user is deemed to be inactive if the newest credentials are older than
ACS_INACTIVITY_LIMIT_SECS
seconds\&. If an activity tracking cookie is received, the user is deemed to be inactive if the date/time that it asserts is older than
ACS_INACTIVITY_LIMIT_SECS
seconds\&. If inactivity is detected by
\m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[6]\d\s+2, access is denied and an
INACTIVITY
error (\fB909\fR) is raised; see
\m[blue]\fBACS_ERROR_HANDLER\fR\m[]\&\s-2\u[18]\d\s+2\&. At present, the only way for a user to continue after an inactivity error is to explicitly delete
\fBDACS\fR
cookies or implicitly delete them by restarting the browser\&. A non\-\fBDACS\fR\-wrapped web page or CGI program might be invoked as an error handler to assist\&.
.sp
Different jurisdictions may independently configure different inactivity thresholds, disable inactivity detection, or disable activity tracking \- the degree to which this feature improves security or is annoying to users depends on thoughtful cooperation amongst jurisdictions and adequate clock synchronization\&.
.RE
.PP
ACS_POST_BUFFER_LIMIT (Optional1)
.RS 4
This is the counterpart to the
\m[blue]\fBSetDACSAuthPostBuffer\fR\m[]\&\s-2\u[44]\d\s+2
directive of
\fBDACS\*(Aqs\fR
\m[blue]\fBmod_auth_dacs\fR\m[]\&\s-2\u[7]\d\s+2
\fBApache\fR
module\&. It establishes the maximum number of bytes of environment and
POST
stream that
\fBDACS\fR
should read from
\m[blue]\fBmod_auth_dacs\fR\m[]\&\s-2\u[7]\d\s+2, overriding the compile\-time default\&. To allow for encoding overhead when serializing the message body,
ACS_POST_BUFFER_LIMIT
should be at least 50% larger than the
SetDACSAuthPostBuffer
size\&. A value of zero imposes no limit\&. (Ideally, only one of these values would need to be configured but you must currently ensure that both of them are set to reasonable values\&.)
.RE
.PP
ACS_POST_EXCEPTION_MODE (Optional1)
.RS 4
In the event that the web server has not made all of the request\*(Aqs arguments available to
\fBDACS\fR
for access control processing (see
\m[blue]\fBSERVICE_ARGS_TRUNCATED\fR\m[]\&\s-2\u[45]\d\s+2), this directive tells
\m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[6]\d\s+2
what to do\&. The following keywords are recognized values:
.PP
abort
.RS 4
Access control processing stops and access is denied\&.
.RE
.PP
default
.RS 4
This is equivalent to
discard\&.
.RE
.PP
discard
.RS 4
Processing continues, but all web service arguments are ignored and none will be available to access control rules\&.
.RE
.PP
proceed
.RS 4
Continue processing, even though one or more arguments may be corrupted or missing\&. This may result in a segmentation fault or other unrecoverable error\&.
.RE
.PP
query
.RS 4
Continue processing, discarding all POST arguments but including any arguments that were passed in the request URI\*(Aqs query component\&.
.RE
.sp
.RE
.PP
ACS_PRE_AUTH (Optional)
.RS 4
Similar to the pre\-authorization authentication feature configured through the
\m[blue]\fBHTTP_AUTH\fR\m[]\&\s-2\u[46]\d\s+2
directive, this directive provides a way to authenticate \- or identify \- a user at access control time\&. Rather than involving HTTP Basic or Digest authentication, however, the value of the directive is an expression that is evaluated\&. If the result is a
\m[blue]\fBsyntactically valid username\fR\m[]\&\s-2\u[47]\d\s+2, credentials are created that (normally) exist only for the duration of the authorization check and which are associated with the
\m[blue]\fBcurrent jurisdiction\fR\m[]\&\s-2\u[48]\d\s+2\&. This directive provides a hook for associating an identity with a request
\fIbased on the request itself\fR
(such as the request URI, its arguments, and other context)\&.
.sp
As a simple example, the following directive checks if the request includes a
\fIUSERNAME\fR
argument, and if so, just uses it:
.sp
.if n \{\
.RS 4
.\}
.nf
ACS_PRE_AUTH \*(Aq${Args::USERNAME:e} ? ${Args::USERNAME} : ""\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
Note the single quotes around the expression so that it is evaluated at access control time instead of configuration processing time\&.
.sp
The
ACS_PRE_AUTH
directives are processed if a request is received that does not include valid credentials and if not disabled by
\m[blue]\fBACS_AUTHENTICATED_ONLY\fR\m[]\&\s-2\u[49]\d\s+2\&. If more than one
ACS_PRE_AUTH
directive is given, they are evaluated in the order in which they appear until one returns a valid username\&. If that expression sets the variable
\fI${Auth::ROLES}\fR
to a valid role string, it will be included in the credentials (see
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[50]\d\s+2)\&. Evaluation errors are ignored\&. If no expression returns a valid username, access control processing continues\&.
.sp
These directives are processed before any
HTTP_AUTH
directives; if a
ACS_PRE_AUTH
directive is successful, the user will effectively be authenticated and so no
HTTP_AUTH
directives will be processed\&.
.sp
If the request includes a
\fB\-rname\fR
flag with the
\m[blue]\fBDACS_ACS\fR\m[]\&\s-2\u[51]\d\s+2
argument, its value is
\fI${Args::RNAME}\fR\&.
.sp
Unlike when authentication is done through
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[52]\d\s+2,
\fIcredentials are not returned to the client\fR\&. This means that no
\fBDACS\fR
session state exists outside of
\fBdacs_acs\fR
and therefore some
\fBDACS\fR
web services may be unavailable or may not operate in the same way they would if credentials were provided by the client\&. This mechanism may also be less efficient than one that returns credentials because authentication will be performed each and every time the client makes a request that triggers it\&.
.RE
.PP
ACS_SUCCESS (Optional)
.RS 4
If
\fBdacs_acs\fR
grants access, immediately before it terminates it evaluates the given expression\&. This directive provides a hook for post\-authorization actions to be performed, which can be user\-specific\&. The namespaces in effect during authorization processing are accessible to the expression\&. The value of the expression is discarded and any errors are ignored\&.
.sp
Also see the
\m[blue]\fBon_success()\fR\m[]\&\s-2\u[53]\d\s+2
function\&.
.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
While it is typically true that if
\fBDACS\fR
grants a request, the web server will go on to process the request (and eventually return a web page to the user agent, execute a program, etc\&.), it is not necessarily so\&. For example, access may still be denied by the web server for other reasons, or an error can occur during subsequent processing\&. This may be relevant in situations where
ACS_SUCCESS
is used to decrement a
\m[blue]\fBcounter\fR\m[]\&\s-2\u[54]\d\s+2, for instance, because it is possible that the user may not actually see a successful result, in which case the counter value should not have been changed and so corrective action would be required\&.
.sp .5v
.RE
.RE
.PP
ACS_TRACK_ACTIVITY (Optional1)
.RS 4
This directive is associated with the inactivity timeout feature whereby an authenticated user is denied access (at any jurisdiction where it is enabled within the
\m[blue]\fBcurrent federation\fR\m[]\&\s-2\u[55]\d\s+2) if no web service request is made within a certain time period (also at any jurisdiction where it is enabled within the
\m[blue]\fBcurrent federation\fR\m[]\&\s-2\u[55]\d\s+2)\&. See
\m[blue]\fBACS_INACTIVITY_LIMIT_SECS\fR\m[]\&\s-2\u[56]\d\s+2\&. This feature is disabled by default\&. It is enabled on a per\-jurisdiction basis, and in the usual configuration all jurisdictions within a federation will enable the feature if it is required\&.
.sp
If the directive\*(Aqs value is "yes",
\m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[6]\d\s+2
emits a federation\-wide HTTP cookie that notes the jurisdiction and date/time at which each
\fBDACS\fR\-wrapped service request is processed\&. The cookie is emitted regardless of whether access was granted, although some error conditions may prevent a cookie from being sent\&. No cookie is set for an effectively unauthenticated request\&.
.sp
The name of the activity tracking cookie has the following format:
.sp
.if n \{\
.RS 4
.\}
.nf
DACS:\fIfederation\-name\fR::::ACTIVITY
.fi
.if n \{\
.RE
.\}
.sp
where
\fIfederation\-name\fR
is the official name assigned to the federation for which the cookie is valid (\m[blue]\fBFEDERATION_NAME\fR\m[]\&\s-2\u[57]\d\s+2)\&. Activity tracking may be enabled without enabling inactivity detection (via
\m[blue]\fBACS_INACTIVITY_LIMIT_SECS\fR\m[]\&\s-2\u[56]\d\s+2)\&. This feature depends on an appropriate level of clock synchronization at all participating jurisdictions\&.
.RE
.PP
ADMIN_IDENTITY (Optional)
.RS 4
This repeatable directive specifies a
\fBDACS\fR
identity (group names are currently not allowed) that
\fBDACS\fR
grants special privileges\&. If omitted, the
\m[blue]\fBcurrent federation and jurisdiction\fR\m[]\&\s-2\u[55]\d\s+2
are implied\&. The usernames "unauth" and "unauthenticated" are disallowed, whether qualified with a jurisdiction or not\&. The function
\m[blue]\fBdacs_admin()\fR\m[]\&\s-2\u[38]\d\s+2
tests whether the user making a service request has any credentials that match any
ADMIN_IDENTITY\&. This enables boilerplate access control rules to be written that need to restrict access to an administrator \- the rules need only invoke
\fBdacs_admin()\fR\&. Changes to the list of
\fBDACS\fR
administrators take effect immediately\&. Comparison of these identities with credentials is controlled by the
\m[blue]\fBNAME_COMPARE\fR\m[]\&\s-2\u[58]\d\s+2
directive\&.
.sp
Some
\fBDACS\fR
services call an internal version of this function to ensure certain operations are limited to a
\fBDACS\fR
administrator\&.
.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
Consider requiring more secure authentication for administrator identities, such as using a two\-factor authentication method or combining two different authentication methods\&.
.sp .5v
.RE
.RE
.PP
ALLOW_HTTP_COOKIE (Optional1)
.RS 4
If "yes",
\fBDACS\fR
components will allow the environment variable
\fBHTTP_COOKIE\fR
to be used to pass
\fBDACS\fR
credentials\&. This is currently necessary when
\fBDACS\fR
components are invoked through IIS (except in conjunction with
\fBDACS\fR
proxied operation)\&. On secure systems, this method of passing credentials may be acceptable, but in general it is not secure and must not be allowed because environment variables are essentially public on some systems\&. If undefined or not "yes",
\fBDACS\fR
components will fail if
\fBHTTP_COOKIE\fR
is present\&.
.RE
.PP
AUTH_AGENT_ALLOW_ADMIN_IDENTITY (Optional1)
.RS 4
Unless this directive has the value "yes",
\fBdacs_auth_agent\fR
will not return credentials that have been designated as an
ADMIN_IDENTITY\&.
.RE
.PP
AUTH_CREDENTIALS_ADMIN_LIFETIME_SECS (Optional1)
.RS 4
The lifetime, in seconds, of all credentials created by this jurisdiction for internal use\&. These credentials are used in certain internal transactions, such as when
\fBdacs_authenticate\fR
sends an HTTP request to an authentication or roles module\&. Although they are only supposed to be held by trusted components, because these credentials can convey special privileges their lifetime should not be much longer than required\&. It is sometimes necessary to increase this lifetime when debugging or if a recipient server is slow\&.
.RE
.PP
AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS (Required1)
.RS 4
The default lifetime, in seconds, of all credentials created by this jurisdiction for users\&. The jurisdiction\*(Aqs authentication services may override this value on a case\-by\-case basis, either through an authentication module (see
\m[blue]\fBauth_reply\&.dtd\fR\m[]\&\s-2\u[59]\d\s+2) or by setting
\fI${Auth::CREDENTIALS_LIFETIME_SECS}\fR
(see
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[52]\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
\fBSecurity\fR
.ps -1
.br
The lifetime should be chosen such that it strikes a balance between security and user convenience that is appropriate for the jurisdiction and federation\&.
.sp .5v
.RE
.RE
.PP
AUTH_ERROR_HANDLER (Stack)
.RS 4
If
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[52]\d\s+2
is not able to successfully authenticate a user, the resulting action can be customized in ways that depend on the reason for the failure\&. This provides a way for the system administrator to display a custom error message or redirect the user\*(Aqs browser\&.
.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
This feature is activated only if
\fBdacs_authenticate\fR
is passed an
\fIENABLE_AUTH_HANDLERS\fR
parameter that has a value of
1\&.
.sp .5v
.RE
The following error code numbers and corresponding descriptive text are defined:
.sp
.if n \{\
.RS 4
.\}
.nf
800 Authentication failed, invalid authenticating information
801 Authentication failed, invalid argument
802 Authentication failed, internal error
899 Authentication failed, reason unknown
.fi
.if n \{\
.RE
.\}
.sp
When this type of response is returned, a program needs to only examine the three digit code to determine why access was denied\&. No blanks may precede the code, any number of blanks may follow it\&. The descriptive\-text consists only of printable characters (e\&.g\&., no tabs or newlines) and may not contain a colon\&. The descriptive\-text is subject to change, but the meaning of the code number is fixed\&. Optionally, the standard text may be followed by a single space, a colon, at least one space, and a more detailed error message\&.
.sp
The
\fBdacs_authenticate\fR
service recognizes a
\fIFORMAT\fR
argument that is used to select between an XML\-aware user agent (FORMAT=XML) and an HTML capable user agent (\fIFORMAT\fR
is not specified or is not XML)\&. In the case of an XML result,
\m[blue]\fBdacs_auth_reply\&.dtd\fR\m[]\&\s-2\u[60]\d\s+2
is used\&. The behaviour of this directive with respect to
\fIFORMAT\fR
is described below on a case\-by\-case basis\&.
.sp
The following directives are supported:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
AUTH_ERROR_HANDLER "\fIAUTH\-error\-code\fR reason"
.sp
\fBDACS\fR
will return an HTML (or XML, if
FORMAT=XML) document that describes why authentication failed, such as the following:
.sp
.if n \{\
.RS 4
.\}
.nf
800 Authentication failed, invalid authenticating information
.fi
.if n \{\
.RE
.\}
.sp
This is the default behaviour\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
AUTH_ERROR_HANDLER "\fIAUTH\-error\-code\fR [url] \fIURL\fR"
.sp
This form causes
\fBDACS\fR
to redirect the client to the specified URL, which may be a relative or absolute URL\&. If the keyword
url
is absent,
\fIURL\fR
must begin with the four characters
http\&. The
GET
method will be used\&. The URL may contain a properly escaped query string;
\fBDACS\fR
will append the following parameters, in the order given, to the URL:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
\fIDACS_ERROR_CODE\fR, the AUTH\-error\-code that identifies the failure\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
\fIDACS_VERSION\fR, the version number of
\fBDACS\fR
(e\&.g\&., "1\&.4")\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
\fIDACS_FEDERATION\fR, the federation that received the service request, if available\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
\fIDACS_JURISDICTION\fR
The jurisdiction that received the service request, if available\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
\fIFORMAT\fR, the value of this parameter will be either HTML or XML, as determined by the value of the parameter of the same name passed to
\fBdacs_authenticate\fR
or the default (HTML if
\fIFORMAT\fR
was not specified)\&.
.RE
.sp
The values of these parameters are URL encoded\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
AUTH_ERROR_HANDLER "\fIAUTH\-error\-code\fR [file] \fIfull\-pathname\fR"
.sp
This form causes the contents of the file named by
\fIfull\-pathname\fR
to be returned without regard to the presence of a
\fIFORMAT\fR
argument\&.
.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 file must include any header lines it requires, such as a
Content\-Type
line, a header\-terminating blank line, and then the document content\&. Note also that the "full\-pathname" usage differs from the "local\-URL" usage of the
ACS_ERROR_HANDLER
directive, though both elements begin with a slash character; the former specifies the absolute pathname of a file, while the latter specifies a URL local to the receiving web server\&.
.sp .5v
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
AUTH_ERROR_HANDLER "\fIAUTH\-error\-code\fR [message] \e"\fImessage\fR\e""
.sp
This form causes the given message, surrounded by escaped double quote characters, to be returned as HTML (or XML if
FORMAT=XML)\&.
.RE
.sp
The optional keywords are treated case\-insensitively\&.
.sp
The
\fIAUTH\-error\-code\fR
is either a defined authentication error code (listed above) or the special symbol "*", which means the directive applies to any authentication error code for which there is no explicit directive\&.
.sp
This directive may appear multiple times, although multiple directives for the same
\fIAUTH\-error\-code\fR
are not allowed\&. Any invalid directive will generally be treated as a fatal error\&. A directive with a syntactically valid but undefined
\fIAUTH\-error\-code\fR
is ignored, however\&.
.RE
.PP
AUTH_FAIL (Optional1)
.RS 4
If
\fBdacs_authenticate\fR
fails to authenticates a user, the given expression is evaluated just before the
\m[blue]\fBAUTH_ERROR_HANDLER\fR\m[]\&\s-2\u[61]\d\s+2
directive, if any, is processed\&. This directive provides a hook for post\-authentication actions to be performed\&. The namespaces in effect during authentication processing are accessible to the expression\&. The value of the expression is discarded and any errors are ignored\&. Note that since authentication failed, only the user\*(Aqs purported identity may be available (\fI${Args::USERNAME}\fR), or if the user was previously authenticated successfully, as
\fI${Env::REMOTE_USER}\fR\&.
.RE
.PP
AUTH_FAIL_DELAY_SECS (Optional1)
.RS 4
If assigned a positive integer value, a particular user (ordinarily the one identified by the
\fIUSERNAME\fR
argument to
\fBdacs_authenticate\fR) will not be allowed to reauthenticate following a failed attempt within this many seconds\&. If assigned the value of zero seconds, this feature is disabled\&. If this directive is absent or assigned an illegal value, a compile\-time value is used instead\&. Authentication modules may indirectly impose their own delays following unsuccessful authentication; this is system dependent and not under the control of
\fBDACS\fR\&.
.RE
.PP
AUTH_SINGLE_COOKIE (Optional1)
.RS 4
By default, each set of credentials that is returned in an HTTP cookie is assigned a
\m[blue]\fBcookie name\fR\m[]\&\s-2\u[62]\d\s+2
that corresponds to the identity represented by the credentials\&. If a user authenticates as two different identities through
\fBdacs_authenticate\fR, for example, he will be given two cookies with different names\&. Because in some situations multiple credentials can be problematic, this directive provides a way to effectively limit a request to a single set of credentials by using one cookie name for all credentials\&. When an already\-authenticated user authenticates again, either at the same jurisdiction or any jurisdiction, the user\*(Aqs browser will replace the previous cookie with the new one\&.
.sp
This directive also controls cookie names associated with credentials generated by
\m[blue]\fBdacscookie(1)\fR\m[]\&\s-2\u[31]\d\s+2,
\m[blue]\fBdacs_auth_agent(8)\fR\m[]\&\s-2\u[63]\d\s+2, and
\m[blue]\fBdacs_auth_transfer(8)\fR\m[]\&\s-2\u[29]\d\s+2\&. Also see
\m[blue]\fBACS_CREDENTIALS_LIMIT\fR\m[]\&\s-2\u[64]\d\s+2\&.
.sp
By setting
AUTH_SINGLE_COOKIE
to "jurisdiction" (case insensitive), the username component of an authentication cookie issued by the jurisdiction is suppressed\&. This means that every authentication cookie it creates will have the same name\&. By setting it to "federation" (case insensitive), the jurisdiction and username components of an authentication cookie issued by the jurisdiction are suppressed\&. This means that every authentication cookie that it creates will have the same name, but also that any two jurisdictions that use this configuration will create cookies with the same name\&. Any other value results in the default behaviour, which is to include both the jurisdiction name and the username in the names of authentication cookies\&. The directive has no effect on the name of the identity encapsulated within an HTTP cookie\&.
.sp
If an authentication cookie is received that was created by the jurisdiction and has a cookie name with a component that it has been configured to suppress, the cookie is ignored\&. A cookie issued by a different jurisdiction with a suppressed cookie name component is acceptable regardless of how this directive is configured at this jurisdiction\&.
\fBDACS\fR
will reject all credentials if a request includes more than one cookie with the same cookie name\&.
.sp
In typical use, each jurisdiction that performs authentication will configure this directive identically\&. To limit each user to associating a single identity with their request, simply set
AUTH_SINGLE_COOKIE
to "federation" at each jurisdiction in the federation\&.
.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
This directive indirectly limits the number of credentials that can be associated with a single request\&. It does not prevent the same individual from sending different requests, from the same browser or different browsers, each associated with a different identity\&. Also, it does not limit the number of concurrent logins of the same identity (such as by different individuals sharing the same account)\&.
.sp
Changing this directive\*(Aqs value may render existing credentials invalid at this jurisdiction\&. For example, after changing the directive it is possible for a user to obtain two authentication cookies with different names for the same identity\&.
\fBDACS\fR
does not allow a request to include multiple credentials for the same identity\&.
.sp .5v
.RE
.RE
.PP
AUTH_SUCCESS (Optional)
.RS 4
If
\fBdacs_authenticate\fR
successfully authenticates a user, the given expression is evaluated just before the
\m[blue]\fBAUTH_SUCCESS_HANDLER\fR\m[]\&\s-2\u[65]\d\s+2
directive, if any, is processed\&. This directive provides a hook for post\-authentication actions to be performed, which can be user\-specific\&. The namespaces in effect during authentication processing are accessible to the expression\&. The value of the expression is discarded and any errors are ignored\&.
.sp
Also see the
\m[blue]\fBon_success()\fR\m[]\&\s-2\u[53]\d\s+2
function\&.
.sp
As an example, the following directive will run a web service after every successful login:
.sp
.if n \{\
.RS 4
.\}
.nf
AUTH_SUCCESS \*(Aqhttps://internal\&.example\&.com/cgi\-bin/userlogin?USERNAME=${Auth::IDENTITY}\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
AUTH_SUCCESS_HANDLER (Optional1)
.RS 4
If
\fBdacs_authenticate\fR
successfully authenticates a user, the resulting action can be customized\&. This provides a way for the
\fBDACS\fR
administrator to redirect a user\*(Aqs browser after login\&.
.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
This feature is enabled only if
\fBdacs_authenticate\fR
is passed an
\fIENABLE_AUTH_HANDLERS\fR
parameter that has a value of
1\&.
.sp .5v
.RE
The
\fBdacs_authenticate\fR
service recognizes a
\fIFORMAT\fR
argument that is used to select between an XML\-aware user agent (FORMAT=XML) and an HTML capable user agent (\fIFORMAT\fR
is not specified or is not XML)\&. In the case of an XML result,
\m[blue]\fBdacs_auth_reply\&.dtd\fR\m[]\&\s-2\u[60]\d\s+2
is used\&. The behaviour of this directive with respect to
\fIFORMAT\fR
is described below on a case\-by\-case basis\&.
.sp
The following syntaxes are supported:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
AUTH_SUCCESS_HANDLER "[url] \fIURL\fR"
.sp
This form causes
\fBDACS\fR
to redirect the client to
\fIURL\fR, which may be a relative or absolute URL\&. If the keyword
url
is absent,
\fIURL\fR
must begin with the four characters
http\&. The
GET
method will be used\&. The URL may contain a properly escaped query string;
\fBDACS\fR
will append the following parameters, in the order given, to the URL:
.PP
\fIDACS_VERSION\fR
.RS 4
The version number of
\fBDACS\fR
(e\&.g\&., "1\&.4")\&.
.RE
.PP
\fIDACS_FEDERATION\fR
.RS 4
The federation that received the service request, if available\&.
.RE
.PP
\fIDACS_JURISDICTION\fR
.RS 4
The jurisdiction that received the service request, if available\&.
.RE
.PP
\fIDACS_USERNAME\fR
.RS 4
The username associated with the new credentials\&.
.RE
.PP
\fIFORMAT\fR
.RS 4
The value of this parameter will be either HTML or XML, as determined by the value of the parameter of the same name passed to
\fBdacs_authenticate\fR
or the default (HTML if
\fIFORMAT\fR
was not specified)\&.
.RE
.sp
The values of these parameters are URL encoded\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
AUTH_SUCCESS_HANDLER "[file] \fIfull\-pathname\fR"
.sp
This form causes the contents of the file named by
\fIfull\-pathname\fR
to be returned without regard to the presence of a
\fIFORMAT\fR
argument\&. The file must include any header lines it requires, such as a
Content\-Type
line, a header\-terminating blank line, and then the document content\&.
.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 "full\-pathname" usage differs from the "local\-URL" usage of the
ACS_ERROR_HANDLER
directive, though both elements begin with a slash character; the former specifies the absolute pathname of a file, while the latter specifies a URL local to the receiving web server\&. To specify a relative URL, use the
url
keyword\&.
.sp .5v
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
AUTH_SUCCESS_HANDLER "[message] \e"\fImessage\fR\e""
.sp
This form causes the given message, surrounded by escaped double quote characters, to be returned as HTML (or XML if
FORMAT=XML)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
AUTH_SUCCESS_HANDLER "credentials"
.sp
This form causes the user\*(Aqs credentials to be displayed, either as an HTML or XML (if
FORMAT=XML) document\&. This is the default behaviour\&.
.RE
.sp
The optional keywords are treated case\-insensitively\&.
.RE
.PP
AUTH_TRANSFER_EXPORT (Optional)
.RS 4
Each use of this directive identifies a target federation and the corresponding URL of a program to invoke the
TOKEN
operation phase of the protocol in that federation\&. The federation identifier is simply a label (case\-sensitive) that must be a syntactically valid federation name\&. Whitespace separates the federation name from the URL\&. Please refer to
\m[blue]\fBdacs_auth_transfer(8)\fR\m[]\&\s-2\u[29]\d\s+2
for details\&.
.RE
.PP
AUTH_TRANSFER_TOKEN_LIFETIME_SECS (Optional1)
.RS 4
This is the lifetime, in seconds, of a token produced by the
TOKEN
operation of
\m[blue]\fBdacs_auth_transfer(8)\fR\m[]\&\s-2\u[29]\d\s+2
and consumed by its
IMPORT
operation\&. That is, it is the time a user (or middleware) has to submit the token before it becomes invalid\&. It should be on the order of a few seconds\&.
.RE
.PP
COMPAT_MODE (Optional1)
.RS 4
This indicates that, to the extent possible, credentials issued by a different release of
\fBDACS\fR
should be accepted\&. At present, the only supported values are
off
(the default, which disables this mode) and
1\&.2\&.
.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
This directive is
\fInot\fR
intended to provide complete interoperability among
\fBDACS\fR
releases and in fact it does not in certain situations\&. Old releases of
\fBDACS\fR
may contain security\-related bugs, or may rely on third\-party software that contains security\-related bugs\&.
\fBDACS\fR
installations are urged to upgrade rather than to depend on the limited backward compatibility supplied by this directive\&.
\fIThere is no guarantee that any particular level of backward compatibility will be carried forward in subsequent releases of\fR
\fBDACS\fR\&.
.sp .5v
.RE
.RE
.PP
COOKIE_HTTPONLY (Optional1)
.RS 4
If "yes", the
HttpOnly
attribute will be included with cookies produced by
\fBDACS\fR\&. This attribute is a Microsoft extension that is used to "\m[blue]\fBmitigate the risk of information disclosure with a cross\-site scripting (XSS) attack\fR\m[]\&\s-2\u[66]\d\s+2"\&. This attribute is not recognized by all browsers but these browsers should ignore it\&. The default is "no"\&.
.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
Methods of defeating this attribute
\m[blue]\fBare known\fR\m[]\&\s-2\u[67]\d\s+2, so administrators may need to take additional precautions against XSS attacks\&.
.sp .5v
.RE
.RE
.PP
COOKIE_NAME_TERMINATORS (Optional1)
.RS 4
By default,
\fBDACS\fR
creates HTTP cookies with names having
\m[blue]\fBa particular syntax\fR\m[]\&\s-2\u[68]\d\s+2, using colon characters to separate components of the cookie\*(Aqs name: application name ("DACS"), federation name, jurisdiction name, and username\&. The strings that are used by default to terminate the first three components of the cookie name can be changed using this directive\&. If the directive\*(Aqs value is:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a single character, each occurrence of a colon in the default terminators is replaced by the character;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a string that does not contain a comma, each occurrence of a colon in the default terminators is replaced by the string; or
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a string that contains four commas, each terminator in the default format is replaced by the corresponding component in
COOKIE_NAME_TERMINATORS\&.
.RE
.sp
Any other directive value is rejected\&. It is not possible to escape a comma in the directive value\&. No terminator may be the null string\&. This directive is honoured in all contexts where
\fBDACS\fR
produces or parses an HTTP cookie name, such as by
\m[blue]\fBdacscookie(1)\fR\m[]\&\s-2\u[31]\d\s+2\&. See
\m[blue]\fBCOOKIE_SYNTAX\fR\m[]\&\s-2\u[69]\d\s+2
for additional information\&.
.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
No other validity checks are performed, so it is possible to configure a cookie name syntax that is non\-conformant, unacceptable to
\fBDACS\fR, or unacceptable to some clients\&. Changing the cookie name format will cause previously issued cookies to not be recognized by
\fBDACS\fR
until the format is switched back\&. Since the value of the directive can be determined at run\-time, however, considerable flexibility is possible\&. Jurisdictions will not recognize each other\*(Aqs HTTP cookies if they produce cookies with differently formatted names\&. Changing the cookie name format does not affect the similar syntax used to specify jurisdictions, users, and so on\&.
.sp .5v
.RE
Consider this directive:
.sp
.if n \{\
.RS 4
.\}
.nf
COOKIE_NAME_TERMINATORS "~"
.fi
.if n \{\
.RE
.\}
.sp
This will result in cookie names that look like:
.sp
.if n \{\
.RS 4
.\}
.nf
DACS~\fIfederation\-name\fR~~[\fIjurisdiction\-name\fR]~[\fIusername\fR][~\fIspecial\fR]
.fi
.if n \{\
.RE
.\}
.sp
Here is another example:
.sp
.if n \{\
.RS 4
.\}
.nf
COOKIE_NAME_TERMINATORS "~,::,~,:"
.fi
.if n \{\
.RE
.\}
.sp
This will result in cookie names that look like:
.sp
.if n \{\
.RS 4
.\}
.nf
DACS~\fIfederation\-name\fR::[\fIjurisdiction\-name\fR]~[\fIusername\fR][:\fIspecial\fR]
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
COOKIE_NO_DOMAIN (Optional1)
.RS 4
If "yes", no
domain
attribute will appear when
\fBDACS\fR
returns a cookie, such as after authenticating successfully from a browser\&. The browser will take the default action, which is to associate the cookie with the domain name or IP address of the request that returned the cookie\&. This will obviously limit
\fBDACS\*(Aqs\fR
single sign\-on feature since the cookie (credentials) will only be sent with requests made to that domain name or IP address\&.
.sp
This directive is sometimes useful when
\fBDACS\fR
is deployed in an environment where fully qualified domain names are not used\&. In this case,
FEDERATION_DOMAIN
must still be configured, although it will not be used in conjunction with the
domain
of cookies\&.
.sp
The default is "no"\&.
.RE
.PP
COOKIE_PATH (Optional1)
.RS 4
This allows the path component of a
Set\-Cookie
(and
Set\-Cookie2) HTTP response header to be specified for the jurisdiction\&. These headers are sent to a user agent after successful authentication or signout\&. Refer to the
\m[blue]\fBNetscape HTTP Cookies Specification\fR\m[]\&\s-2\u[70]\d\s+2,
\m[blue]\fBRFC 2965\fR\m[]\&\s-2\u[71]\d\s+2, and
\m[blue]\fBRFC 6265\fR\m[]\&\s-2\u[72]\d\s+2
for details\&.
.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
The default value is "/", which means that the cookie will be sent by a user agent along with
\fIevery\fR
request sent to the jurisdiction\*(Aqs host\&. The value should be set to the most specific URL path under which all
\fBDACS\fR\-wrapped services appear so that
\fBDACS\fR
credentials will only be sent with requests to those URLs\&. It is critical to do this if your server runs arbitrary user CGI programs because a malicious user might be able to cause a
\fBDACS\fR\-authenticated user to visit a service that is not
\fBDACS\fR\-wrapped and capture cookies that represent
\fBDACS\fR
identities\&. For example, if a jurisdiction segregated its
\fBDACS\fR\-wrapped static content under
/dacs/content
and its
\fBDACS\fR\-wrapped CGI programs under
/dacs/cgi\-bin, then
COOKIE_PATH
should have the value "/dacs"\&.
.sp .5v
.RE
.RE
.PP
CSS_PATH (Optional1)
.RS 4
This path is used as the value of the
href
attribute of the HTML
link
element used to specify the root location of style files used by HTML\-producing
\fBDACS\fR
web services and utilities\&. The mapping between this path and a local directory, if any, depends on
\fBApache\*(Aqs\fR
configuration; for example, if its value is "/css", the location of the corresponding directory will depend on the location of the server\*(Aqs document root and any applicable
Alias
directive\&.
.sp
If this directive is not used, a compile\-time default of "/css" is used, which assumes that an
\fBApache\fR
directive like this one is used:
.sp
.if n \{\
.RS 4
.\}
.nf
Alias /css "/usr/local/dacs/www/css/"
.fi
.if n \{\
.RE
.\}
.sp
Please refer to
\m[blue]\fBdacs\&.install(7)\fR\m[]\&\s-2\u[73]\d\s+2
for additional information about use of the
Alias
directive\&.
.RE
.PP
DTD_BASE_URL (Optional1)
.RS 4
When
\fBDACS\fR
services are asked to send an XML response (FORMAT=XML) and
DTD_BASE_URL
is configured, services will emit a
DOCTYPE
with the keyword
SYSTEM
followed by a value derived from
DTD_BASE_URL; e\&.g\&.,
.sp
.if n \{\
.RS 4
.\}
.nf
.fi
.if n \{\
.RE
.\}
.sp
If
DTD_BASE_URL
is not configured, an internal DTD will be emitted\&. Also see the description of the
\m[blue]\fB\fIFORMAT\fR web service argument\fR\m[]\&\s-2\u[74]\d\s+2\&.
.RE
.PP
EVAL (Optional)
.RS 4
The
EVAL
directive is special in that it may appear in any clause and because it is
\fIalways evaluated when it is first seen\fR
during processing of
site\&.conf, the
Default
section of
dacs\&.conf, or the applicable
Jurisdiction
section of
dacs\&.conf
(i\&.e\&., before any section merging occurs)\&. The purpose of the directive is purely for its side effect, such as initializing a configuration variable (see
\m[blue]\fBAdvanced Techniques\fR\m[]\&\s-2\u[75]\d\s+2)\&. Because these directives are scanned early during configuration processing, their right\-hand sides cannot reference directives as configuration variables because those directives have not yet been evaluated (so they cannot reference
\fI${Conf::FEDERATION_DOMAIN}\fR, for example)\&. Example:
.sp
.if n \{\
.RS 4
.\}
.nf
EVAL ${Conf::a_special_path} = "/my/path"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
FEDERATION_DOMAIN (Required1)
.RS 4
The suffix of the domain name (\m[blue]\fBRFC 1035\fR\m[]\&\s-2\u[76]\d\s+2
2\&.3\&.1) that is common to all jurisdictions in the federation\&. Note that the domain name associated with a jurisdiction is not explicitly configured (but see
dacs_url
in
\m[blue]\fBdacs\&.groups(5)\fR\m[]\&\s-2\u[77]\d\s+2), and that this is a one\-to\-many association (see
\m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[78]\d\s+2)\&. Example:
example\&.com
.RE
.PP
FEDERATION_NAME (Required1)
.RS 4
The name for the federation of jurisdictions\&. The syntax is the same as for
\m[blue]\fBJURISDICTION_NAME\fR\m[]\&\s-2\u[79]\d\s+2: an alphabetic followed by zero or more alphanumeric characters, \*(Aq\-\*(Aq, or \*(Aq_\*(Aq\&. By convention, this is in all\-caps, however\&. Please see
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[80]\d\s+2
for additional information\&. Example:
FEDROOT
.RE
.PP
HTTP_AUTH (Stack)
.RS 4
This directive is used to perform user authentication
\fIat access control time\fR
rather than in a separate sign\-on step\&. This mode of authentication is triggered through
\fBDACS\*(Aqs\fR
internal implementation of HTTP Basic or Digest authentication (see
\m[blue]\fBRFC 2617\fR\m[]\&\s-2\u[81]\d\s+2)\&. If prompting is enabled, the user will be asked for his username and password by the user agent\*(Aqs usual prompting method\&. If prompting is disabled, the user agent must know how to send an
Authorization
request header without first receiving a
WWW\-Authenticate
response header\&. The username and password obtained from the user can be directed to any suitable
\fBDACS\fR
authentication method for validation\&. By default, the resulting identity is associated with the
\m[blue]\fBcurrent jurisdiction\fR\m[]\&\s-2\u[48]\d\s+2\&.
.sp
Other than by placing the resource or resources specified by this directive under the control of
\fBDACS\fR, no additional
\fBApache\fR
configuration needs to be done to use this feature\&.
.sp
Please refer to the section on
\m[blue]\fBHTTP Authentication\fR\m[]\&\s-2\u[82]\d\s+2
for additional information about this feature and how it is used\&. Also refer to the
\m[blue]\fBHTTP_AUTH_ENABLE\fR\m[]\&\s-2\u[83]\d\s+2
directive\&.
.sp
Two different mechanisms are available:
\fIpre\-authorization\fR
testing and
\fIpost\-authorization\fR
testing\&. The
HTTP_AUTH_ENABLE
directive is used to enable one or both mechanisms\&.
.sp
The
\fIpre\-authorization\fR
testing mechanism is used if:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
a request is received that does not include valid credentials;
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
the feature is enabled by
HTTP_AUTH_ENABLE
(i\&.e\&., it is set to "pre_acs_only" or "both") and not disabled by
\m[blue]\fBACS_AUTHENTICATED_ONLY\fR\m[]\&\s-2\u[49]\d\s+2;
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
no
\m[blue]\fBACS_PRE_AUTH\fR\m[]\&\s-2\u[84]\d\s+2
directive is successful;
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
the applicable directive includes the
\fB\-pre\fR
flag (\m[blue]\fBsee below\fR\m[]\&\s-2\u[85]\d\s+2); and
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
either the request includes an
Authorization
request header or the return of an HTTP
WWW\-Authenticate
response header is enabled\&.
.RE
.sp
This mechanism can be useful with simple user agents that understand Basic authentication but cannot handle redirection or sometimes even the
WWW\-Authenticate
response header\&. It may also be appropriate in situations where a user agent cannot or will not handle HTTP cookies\&. If
\fBdacs_acs\fR
is allowed to respond with a
WWW\-Authenticate
response header, the configuration variable
\fI${Conf::http_auth_401}\fR
must be set to "yes"\&.
.sp
The
\fIpost\-authorization\fR
testing mechanism is used if:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
a request is denied because the user was not authenticated;
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
the feature is enabled by
HTTP_AUTH_ENABLE
(i\&.e\&., it is set to "post_acs_only" or "both") and not disabled by
ACS_AUTHENTICATED_ONLY;
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
the applicable directive does not include a
\fB\-pre\fR
flag (see below)\&.
.RE
.sp
One important difference between the two mechanisms is that while the post\-authorization mechanism works by redirecting the user to
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[52]\d\s+2
after authorization checking denies a request, the pre\-authorization mechanism does not involve any redirection and
\fBdacs_authenticate\fR
is not used\&. Instead,
\fBdacs_acs\fR
performs authentication internally (by calling
\fBdacsauth\fR
as a function) and
\fIcredentials are not returned to the client\fR; credentials are created that (normally) exist only for the duration of the authorization check, which means that no
\fBDACS\fR
session state exists outside of
\fBdacs_acs\fR
and therefore some
\fBDACS\fR
web services will either be unavailable or not operate in the same way they would if credentials were provided by the client\&. Pre\-authorization may also be less efficient than returning credentials because authentication will be performed each and every time the client makes a request that triggers it\&. Note that only authentication modules that implement the
password
or
expr
\m[blue]\fBauthentication styles\fR\m[]\&\s-2\u[86]\d\s+2
can be used by this mechanism, and only if no redirection of the client is necessary\&. Because web browsers only prompt for a username and password, if an
\fIAUXILIARY\fR
argument is also required it must be entered with either the username or password (i\&.e\&., combined in some way, perhaps separated by punctuation) and then parsed into an
\fIAUXILIARY\fR
argument using a run\-time configuration directive\&. With pre\-authorization, roles can be assigned to the temporary credentials (refer to the description of the
\fB\-r\fR
flag and the
\fIrole\-module\-spec\fR
in
\m[blue]\fBdacsauth(1)\fR\m[]\&\s-2\u[32]\d\s+2
for details)\&.
.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
Like
\fBdacsauth\fR
and
\fBdacs_authenticate\fR, if
\fBdacs_acs\fR
uses a built\-in module to perform authentication, it must run setuid or setgid (\m[blue]\fBchmod(2)\fR\m[]\&\s-2\u[87]\d\s+2)\&. to obtain sufficient privileges to access the required files; this is true for Unix password authentication, for example\&. Programs should run at the lowest level of authorization that is necessary, however, and it is generally preferable to only run authentication modules at a higher authorization level\&.
.sp .5v
.RE
.sp
The value of the
HTTP_AUTH
directive follows any one of the following three forms:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fIauth_scheme\fR \fIauth_realm\fR \fIurl_pattern\fR+
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\fIauth_scheme\fR \fIauth_realm\fR \fIurl_pattern\fR+ \-pre [[\-param] \fIparam\-string\fR]
{\-m \fIauth\-module\-spec\fR [\fIauth\-flag\fR]*}+ {\-r \fIroles\-module\-spec\fR}*
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
except \fIurl_pattern\fR+
.fi
.if n \{\
.RE
.\}
.RE
.sp
The first syntactical form is for the post\-authentication mechanism:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIauth_scheme\fR
is the (case\-insensitive) authentication scheme to use (e\&.g\&.,
Basic);
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIauth_realm\fR
is the (case\-sensitive) realm\-value string associated with the resource (see
\m[blue]\fBRFC 2617\fR\m[]\&\s-2\u[81]\d\s+2);
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIurl_pattern\fR+
is a list of one or more URI path components that are matched against the request for which access was denied to an unauthenticated user\&. Each of these components is like the
\fIurl_pattern\fR
attribute used in
\m[blue]\fBaccess control rules\fR\m[]\&\s-2\u[37]\d\s+2
in that it can either specify an exact match or, by ending in "/*", a wildcard match; no query argument component is allowed\&. Each
\fIurl_pattern\fR
begins with a
/
character\&.
.RE
.sp
The second syntactical form is for the pre\-authentication mechanism\&. Its first three components are like those for the first form, and must appear in the order specified above\&. The following components are then added, and may follow the three initial components in any order:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-pre\fR
selects the pre\-authorization testing mechanism; the default is to use post\-authorization testing\&. Because each
\fIurl_pattern\fR
begins with a
/
character, the
\fB\-pre\fR
flag implicitly ends the
\fIurl_pattern\fR
list\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIparam\-string\fR
is an optional string consisting of authentication parameters as per RFC 2617 (note: HTTP Basic authentication does not permit any optional parameters)\&. For clarity, or if
\fIparam\-string\fR
might be confused with another syntactic element, it can be preceded by a
\fB\-param\fR
flag\&. In the absence of the
\fB\-param\fR
flag, any non\-flag argument is assumed to be the
\fIparam\-string\fR\&. Only one
\fIparam\-string\fR
is allowed\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-m\fR
\fIauth\-module\-spec\fR
specifies an authentication module using the command\-line syntax of
\m[blue]\fBdacsauth(1)\fR\m[]\&\s-2\u[32]\d\s+2\&. This argument must occur at least once\&. Following the
\fIauth\-module\-spec\fR
can be zero or more
\fIauth\-flag\fR
arguments to apply to the module\*(Aqs authentication context\&. The
\fB\-D\fR\fB\fIdirective\fR\fR\fB=\fR\fB\fIvalue\fR\fR
flag,
\fB\-fj \fR\fB\fIjurname\fR\fR
flag, and the
\fB\-fn \fR\fB\fIfedname\fR\fR
flag are recognized and have the same semantics as when used by
\m[blue]\fBdacsauth(1)\fR\m[]\&\s-2\u[32]\d\s+2\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-r\fR
\fIroles\-module_spec\fR
specifies a roles module\&. This argument may occur zero or more times\&.
.RE
.sp
In the third syntactical form, the
except
keyword identifies portions of the URL space that should
\fInot\fR
trigger HTTP authentication\&.
.sp
The
HTTP_AUTH
directives "stack", like the
\m[blue]\fBACS_ERROR_HANDLER\fR\m[]\&\s-2\u[18]\d\s+2
directive\&.
\fBDACS\fR
will search for the first exact
\fIurl_pattern\fR
that matches or will select the closest wildcard
\fIurl_pattern\fR\&. Two or more directives with the same
\fIurl_pattern\fR
should not be configured\&.
.sp
The first of the two directives in the following example may trigger Basic authentication for the realm called "Info Realm" when either
/cgi\-bin/dacs/dacs_prenv
or
/cgi\-bin/dacs/dacs_version
(relative to the
\m[blue]\fBcurrent jurisdiction\fR\m[]\&\s-2\u[48]\d\s+2) is requested\&. The second directive may trigger Basic authentication for the realm called "CGI Realm" for any other resource subordinate to
/cgi\-bin/dacs\&. The first directive will override the second because an exact match overrides a wildcard match\&.
.sp
.if n \{\
.RS 4
.\}
.nf
HTTP_AUTH "basic \e"Info Realm\e" /cgi\-bin/dacs/dacs_prenv /cgi\-bin/dacs/dacs_version"
HTTP_AUTH "basic \e"CGI Realm\e" /cgi\-bin/dacs/*"
.fi
.if n \{\
.RE
.\}
.sp
In the next example, the two directives associate the Basic authentication scheme with everything under
/cgi\-bin/dacs/, except for
/cgi\-bin/dacs/dacs_prenv
(because the second directive is an exact match, which overrides the first directive):
.sp
.if n \{\
.RS 4
.\}
.nf
HTTP_AUTH "basic \e"CGI Realm\e" /cgi\-bin/dacs/*"
HTTP_AUTH "except /cgi\-bin/dacs/dacs_prenv"
.fi
.if n \{\
.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
\fBTip\fR
.ps -1
.br
An administrator can take advantage of
\fBDACS\*(Aqs\fR
active configuration processing to decide at run\-time which
\fIauth_scheme\fR,
\fIauth_realm\fR, or password file to use, for instance, perhaps depending on the request\*(Aqs arguments\&.
.sp .5v
.RE
As an example of pre\-authorization testing authentication, consider the following configuration directives:
.sp
.if n \{\
.RS 4
.\}
.nf
HTTP_AUTH_ENABLE "pre_acs_only"
EVAL ${Conf::http_auth_401} = "no"
HTTP_AUTH "basic \e"dacs_prenv Realm\e" /cgi\-bin/dacs/dacs_prenv \-m unix passwd suff"
.fi
.if n \{\
.RE
.\}
.sp
The first directive above enables this feature\&. The second directive disables responding with a
WWW\-Authenticate
header; changing its value to "yes" enables the response\&. The third directive associates the
\fBDACS\fR
\m[blue]\fBdacs_prenv(8)\fR\m[]\&\s-2\u[88]\d\s+2
service with the built\-in Basic authentication feature at pre\-authorization testing time\&. Given this configuration, if a client requests
\fBdacs_prenv\fR
but does not include credentials:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
if no
Authorization
header was sent and
\fI${Conf::http_auth_401}\fR
is "no", then execution will proceed as if the feature were disabled (i\&.e\&., the user will be unauthenticated)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
if no
Authorization
header was sent and
\fI${Conf::http_auth_401}\fR
is "yes", then
\fBDACS\fR
will respond with a
WWW\-Authenticate
response header and
\fB401\fR
status code
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
if an
Authorization
header was sent, the username and password will be validated using the built\-in Unix authentication module:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
if authentication succeeds, temporary credentials will be created and used for the request, but will not be returned to the client
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
if authentication fails, access will be denied
.RE
.sp
.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
\fBTip\fR
.ps -1
.br
You can create an
Authorization
header by constructing a string consisting of an account name, a colon, and the account\*(Aqs password\&. MIME encode the resulting string \- you can use
\m[blue]\fBdacsexpr(1)\fR\m[]\&\s-2\u[89]\d\s+2
and the
\m[blue]\fBencode()\fR\m[]\&\s-2\u[90]\d\s+2
function:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsexpr
> encode(mime, "guest:apassword")
"Z3Vlc3Q6YXBhc3N3b3Jk"
.fi
.if n \{\
.RE
.\}
.sp
The header for the example above would look like:
.sp
.if n \{\
.RS 4
.\}
.nf
Authorization: Basic Z3Vlc3Q6YXBhc3N3b3Jk
.fi
.if n \{\
.RE
.\}
.sp
And using
\m[blue]\fBdacshttp(1)\fR\m[]\&\s-2\u[4]\d\s+2, you could use the flag:
.sp
.if n \{\
.RS 4
.\}
.nf
\-header Authorization "Basic Z3Vlc3Q6YXBhc3N3b3Jk"
.fi
.if n \{\
.RE
.\}
.sp .5v
.RE
The example that follows shows how
\m[blue]\fBLDAP authentication\fR\m[]\&\s-2\u[91]\d\s+2
using the
direct
method might be configured\&. In an appropriate place in
dacs\&.conf, we might insert these directives:
.sp
.if n \{\
.RS 4
.\}
.nf
HTTP_AUTH_ENABLE "pre_acs_only"
HTTP_AUTH "basic \e"LDAP Login Using Your Common Name\e" /basic/* \-pre \e
\-m https://example\&.example\&.com/cgi\-bin/dacs/local_ldap_authenticate \e
password sufficient \-Of /usr/local/dacs/ldap/ldap_auth_options_direct"
.fi
.if n \{\
.RE
.\}
.sp
In the file
/usr/local/dacs/ldap/ldap_auth_options_direct
(which must be readable at run\-time by
\m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[6]\d\s+2), we might put:
.sp
.if n \{\
.RS 4
.\}
.nf
LDAP_BIND_METHOD=direct
LDAP_USERNAME_URL*="ldap://windex\&.example\&.com/CN=" \&. encode(url,${Args::USERNAME}) \&. ",CN=Users,DC=example,DC=com"
LDAP_USERNAME_EXPR*="${LDAP::sAMAccountName}"
.fi
.if n \{\
.RE
.\}
.sp
Note the use of the
LDAP_USERNAME_EXPR*
directive\&. Because authentication against the directory uses a
Common Name
attribute in the example, and a
Common Name
may not be a valid
\fBDACS\fR
username, it must be replaced by (or mapped to) an acceptable
\fBDACS\fR
username\&. The first time a user attempts to access a resource that matches the URL pattern
/basic/*, he will prompted by his web browser for a username (in this case, a
Common Name
must be provided) and password\&. The directory on
windex\&.example\&.com
will be used by the
\fBlocal_ldap_authenticate\fR
module to validate the information provided by the user\&.
.sp
To also obtain the user\*(Aqs roles from the directory, the
set_roles
style modifier and an
LDAP_ROLES_SELECTOR*
directive can be added to the configuration:
.sp
.if n \{\
.RS 4
.\}
.nf
HTTP_AUTH_ENABLE "pre_acs_only"
HTTP_AUTH "basic \e"LDAP Login Using Your Common Name\e" /basic/* \-pre \e
\-m https://example\&.example\&.com/cgi\-bin/dacs/local_ldap_authenticate \e
password,set_roles sufficient \-Of /usr/local/dacs/ldap/ldap_auth_options_direct"
.fi
.if n \{\
.RE
.\}
.sp
And to
/usr/local/dacs/ldap/ldap_auth_options_direct:
.sp
.if n \{\
.RS 4
.\}
.nf
LDAP_BIND_METHOD=direct
LDAP_USERNAME_URL*="ldap://windex\&.example\&.com/CN=" \&. encode(url,${Args::USERNAME}) \&. ",CN=Users,DC=example,DC=com"
LDAP_ROLES_SELECTOR*="${LDAP::attrname}" eq "memberOf" ? strtr(ldap(rdn_attrvalu
e, ldap(dn_index, "${LDAP::attrvalue}", 1)), " ", "_") : ""
LDAP_USERNAME_EXPR*="${LDAP::sAMAccountName}"
.fi
.if n \{\
.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
\fBTip\fR
.ps -1
.br
Since the pre\-authorization mechanism does not return
\fBDACS\fR
credentials to the user\*(Aqs web browser, a subsequent invocation of
\m[blue]\fBdacs_current_credentials(8)\fR\m[]\&\s-2\u[92]\d\s+2
will not display information that resulted from the authentication procedure\&. If the URL that triggers pre\-authorization is for a script or other program that is executable by
\fBApache\fR
with access permitted by
\fBDACS\fR, however, the program can display its environment, which will include
\fBDACS_USERNAME\fR,
\fBDACS_ROLES\fR, and so on\&. For example,
\m[blue]\fBdacs_prenv(8)\fR\m[]\&\s-2\u[88]\d\s+2
can be used for this, as can this simple PHP script (\fBphpinfo\&.php\fR):
.sp
.if n \{\
.RS 4
.\}
.nf
.fi
.if n \{\
.RE
.\}
.sp .5v
.RE
To authenticate against a Unix account and assign the user\*(Aqs group membership as roles, this configuration might be used:
.sp
.if n \{\
.RS 4
.\}
.nf
HTTP_AUTH_ENABLE "pre_acs_only"
HTTP_AUTH "basic \e"Login Using Your Unix Account\e" /basic/* \-pre \e
\-m https://example\&.example\&.com/cgi\-bin/dacs/local_unix_authenticate \e
password sufficient \-Of /usr/local/dacs/ldap/ldap_auth_options_direct \e
\-r https://example\&.example\&.com/cgi\-bin/dacs/local_unix_roles"
.fi
.if n \{\
.RE
.\}
.sp
Note that
\fBlocal_unix_authenticate\fR
must run with sufficient privileges to validate the username/password pair\&.
.RE
.PP
HTTP_AUTH_ENABLE (Optional1)
.RS 4
This directive\*(Aqs value must be one of:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
"post_acs_only", if only post\-authorization testing
\m[blue]\fBHTTP Authentication\fR\m[]\&\s-2\u[82]\d\s+2
may be used,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
"pre_acs_only", if only pre\-authorization testing HTTP authentication may be used, or
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
"yes" or "both" if either mechanism may be used\&.
.RE
.sp
Refer to
\m[blue]\fBHTTP_AUTH\fR\m[]\&\s-2\u[46]\d\s+2
for additional details\&.
.RE
.PP
HTTP_PROG (Required1)
.RS 4
The full pathname of the executable
\m[blue]\fBdacshttp(1)\fR\m[]\&\s-2\u[4]\d\s+2
program, a utility distributed with
\fBDACS\fR\&. This program is used by
\fBDACS\fR
components to invoke local services, optionally using SSL/TLS\&.
.RE
.PP
INFOCARD_AUDIENCE (Optional)
.RS 4
This directive must be configured for
\fBDACS\fR
to function as a Relying Party\&. When
\fBDACS\fR
acts as a Relying Party, each of these directives is applied to the value of an
Audience
element (a URI) in a secure token\*(Aqs
AudienceRestrictionCondition
element until a successful match is found\&. Several matching functions are available using the following syntax:
.sp
.if n \{\
.RS 4
.\}
.nf
\fIfunction\fR [\fIspace\fR+ \fIarg\-to\-match\-against\-Audience\fR]
.fi
.if n \{\
.RE
.\}
.sp
\fIfunction\fR
is case insensitive\&.
.PP
uri \fImatch\-URI\fR
.RS 4
The
\fImatch\-URI\fR
is compared with the entire
Audience
URI for an exact URI match\&. URI matching syntax is used, meaning that only the scheme and hostname components are case insensitive\&.
.sp
.if n \{\
.RS 4
.\}
.nf
INFOCARD_AUDIENCE "uri http://DACS\&.DSS\&.CA/infocard\-demo"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
any
.RS 4
Any
Audience
is acceptable\&.
.sp
.if n \{\
.RS 4
.\}
.nf
INFOCARD_AUDIENCE "any"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
regex \fImatch\-regex\fR
.br
regex/\fIflags\fR \fImatch\-regex\fR
.RS 4
In the first form, the regular expression
\fImatch\-regex\fR
is matched (unanchored) against the
Audience
URI\&. In the second form, one or more flags can precede the regular expression: \*(Aqi\*(Aq specifies case\-insensitive matching and \*(Aqe\*(Aq specifies "extended" regular expressions rather than the default "basic" regular expressions\&. IEEE Std 1003\&.2 ("POSIX\&.2") regular expressions are supported (\m[blue]\fBregex(3)\fR\m[]\&\s-2\u[93]\d\s+2)\&.
.sp
.if n \{\
.RS 4
.\}
.nf
INFOCARD_AUDIENCE "regex/i ^https://dacs\&.dss\&.ca:8443"
.fi
.if n \{\
.RE
.\}
.sp
The following directives are equivalent:
.sp
.if n \{\
.RS 4
.\}
.nf
INFOCARD_AUDIENCE "regex \&.*"
INFOCARD_AUDIENCE "any"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
host \fImatch\-hostname\fR
.RS 4
The
\fImatch\-hostname\fR, which may be a domain name or an IP address, is matched case\-insensitively against the host name in the
Audience
URI\&.
.sp
.if n \{\
.RS 4
.\}
.nf
INFOCARD_AUDIENCE "host dacs\&.dss\&.ca"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
prefix \fImatch\-URI\fR
.RS 4
The
\fImatch\-URI\fR
is matched against the
Audience
URI to test if the former is a prefix of the latter\&. The case\-sensitivity rules for URI components is respected (e\&.g\&., the scheme and host name components are treated case\-insensitively, but the path components are not)\&.
.sp
.if n \{\
.RS 4
.\}
.nf
INFOCARD_AUDIENCE "prefix https://dacs\&.dss\&.ca/infocards"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RE
.PP
INFOCARD_AUDIENCE_RESTRICTION (Optional)
.RS 4
Used by
\m[blue]\fBdacs_sts(8)\fR\m[]\&\s-2\u[94]\d\s+2, this optional directive specifies the value of an
Audience
element in an
AudienceRestrictionCondition\&.
.RE
.PP
INFOCARD_CARD_DATETIME_EXPIRES (Optional1)
.RS 4
This optional directive specifies the date and time of expiration for a managed InfoCard created by
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2\&. The XML Schema
\fBdateTime\fR
format must be used (see
\m[blue]\fBXML Schema Part 2: Datatypes Second Edition\fR\m[]\&\s-2\u[96]\d\s+2); e\&.g\&.,
.sp
.if n \{\
.RS 4
.\}
.nf
INFOCARD_CARD_DATETIME_EXPIRES "2010\-06\-15T09:46:31\-08:00"
.fi
.if n \{\
.RE
.\}
.sp
Also see
\m[blue]\fBINFOCARD_CARD_LIFETIME_SECS\fR\m[]\&\s-2\u[97]\d\s+2\&.
.RE
.PP
INFOCARD_CARD_DEFS_URL (Optional1)
.RS 4
This optional directive is used by
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2
to specify a web service that defines the claims supported by a new managed InfoCard\&. If it is not defined, the default claim
dacs_identity
is used\&. To prevent abuse, arbitrary compile\-time limits are imposed on the number of claims (20) and the lengths of various claim components: name (32 bytes), value (64 bytes), URI prefix (128 bytes), label (20 bytes), and description (40 bytes)\&. (These limits should be run\-time configurable\&.) The distribution\*(Aqs
infocard
directory includes an example program,
\fBdemo_card_defs\&.php\fR, which documents the program\*(Aqs arguments and output syntax\&.
.RE
.PP
INFOCARD_CARD_FILL_URL (Optional1)
.RS 4
This optional directive is used by
\m[blue]\fBdacs_sts(8)\fR\m[]\&\s-2\u[94]\d\s+2
to specify a web service that retrieves the values of claims requested by a Relying Party\&. If it is not defined, only the value of the default claim
dacs_identity
is available\&. Access to this web service must be appropriately restricted and secured, although it does not need to be
\fBDACS\fR\-wrapped\&. It is passed special
\fBDACS\fR
credentials (as an HTTP cookie)\&. The distribution\*(Aqs
infocard
directory includes an example program,
\fBdemo_fill_claims\&.php\fR, which documents the program\*(Aqs arguments and output syntax\&.
.RE
.PP
INFOCARD_CARD_IMAGE_BASE_URL (Required1\-C)
.RS 4
This directive is required by
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2\&. It is the initial part of a
\fBDACS\fR
\m[blue]\fBVFS URI\fR\m[]\&\s-2\u[98]\d\s+2
from which image files for managed InfoCards can be retrieved\&. The general idea is that the particular image associated with a card depends on the STS authentication credential that is used by the card\&. For example, the configuration variable
\fIinfocard_card_image_passwd\fR, if set, specifies the filename (relative to
INFOCARD_CARD_IMAGE_BASE_URL) of an image associated with InfoCards that use the username/password type of authentication between its owner and the STS; if unspecified, a compile\-time default (dacs_username_password_credential\&.png) is used\&. Similarly, the variables
\fIinfocard_card_image_cert\fR
(default value:
dacs_x509certificate_credential\&.png) and
\fIinfocard_card_image_card\fR
(default value:
dacs_selfissued_credential\&.png) specify filenames for images associated with the X\&.509 V3 certificate credential type and the self\-issued InfoCard credential type, respectively\&. The value of
INFOCARD_CARD_IMAGE_BASE_URL
is typically the absolute pathname of a directory containing the image files or the initial part of a URL to which a final path component will be appended\&. Also see the
\m[blue]\fBCARD_IMAGE_URL\fR\m[]\&\s-2\u[99]\d\s+2
argument to
\fBdacs_managed_infocard\fR\&.
.sp
An image should be in the range of 60 pixels wide by 45 pixels high and 200 pixels wide by 150 pixels high\&. Only certain image formats are allowed by the specification; the image format is deduced from the filename extension (case insensitively): "\&.png", "\&.gif", "\&.tiff" (or "\&.tif"), "\&.bmp", and "\&.jpeg" (or "\&.jpg")\&. If the format cannot be deduced,
PNG
is assumed\&.
.RE
.PP
INFOCARD_CARD_LIFETIME_SECS (Optional1)
.RS 4
If
INFOCARD_CARD_DATETIME_EXPIRES
is not defined, the expiration date and time of a managed InfoCard created by
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2
can be specified relative to the current time as this many seconds\&. If neither this directive nor
INFOCARD_CARD_DATETIME_EXPIRES
is defined, a compile\-time default lifetime is used (currently, 365 days)\&. Also see
\m[blue]\fBINFOCARD_CARD_DATETIME_EXPIRES\fR\m[]\&\s-2\u[100]\d\s+2\&.
.RE
.PP
INFOCARD_CARD_OUTPUTDIR (Optional1)
.RS 4
If a managed InfoCard generated by
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2
is stored in a file, it is written to this directory\&. The name of the file is of the form
\fIusername\fR_\fIrandom\fR\&.crd\&. See
\m[blue]\fBINFOCARD_CARDID_BASE_URL\fR\m[]\&\s-2\u[101]\d\s+2\&.
.RE
.PP
INFOCARD_CARD_VERSION (Optional1)
.RS 4
This directive is used by
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2
to provide a value for the
CardVersion
element in a managed InfoCard\&. The default is "1"\&.
.RE
.PP
INFOCARD_CARDID_BASE_URL (Required1\-C)
.RS 4
This directive is required by
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2\&. It is used as the base URL for the
CardId
of a new managed InfoCard\&. If this URL is set so that it points into the directory specified by
\m[blue]\fBINFOCARD_CARD_OUTPUTDIR\fR\m[]\&\s-2\u[102]\d\s+2, then the resulting
CardId
URLs can be used to fetch the card by its owner, assuming appropriate access control rules are also configured\&. Also see
\m[blue]\fBINFOCARD_CARDID_SUFFIX\fR\m[]\&\s-2\u[103]\d\s+2\&.
.RE
.PP
INFOCARD_CARDID_SUFFIX (Optional1)
.RS 4
This optional directive is used by
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2
and specifies a string to be appended as a final path element to the value of
\m[blue]\fBINFOCARD_CARDID_BASE_URL\fR\m[]\&\s-2\u[101]\d\s+2
to form a new card\*(Aqs
CardId\&. If the value of
INFOCARD_CARDID_SUFFIX
is:
.PP
identity
.RS 4
The specified or implied identity assigned to the card is interpolated; this is the default\&.
.RE
.PP
username
.RS 4
The specified or implied username assigned to the card is interpolated\&.
.RE
.PP
random
.RS 4
A safely\-encoded 20\-byte random string is interpolated\&.
.RE
.PP
default
.RS 4
The default is used ("identity")\&.
.RE
.sp
If the value of
INFOCARD_CARDID_SUFFIX
does not match (case\-insensitively) any of these strings, it is interpolated verbatim\&. Regardless of how it was derived, the result string must be a syntactically valid URI path segment (\m[blue]\fBRFC 2396\fR\m[]\&\s-2\u[104]\d\s+2)\&.
.RE
.PP
INFOCARD_DIGEST (Optional1)
.RS 4
The name of the hash algorithm to use in account files for self\-issued InfoCard\-based authentication (see
\m[blue]\fBdacs_infocard(8)\fR\m[]\&\s-2\u[105]\d\s+2)\&. The syntax is the same as for the
\m[blue]\fBPASSWORD_DIGEST\fR\m[]\&\s-2\u[106]\d\s+2
directive\&. The default is "SHA256"\&.
.RE
.PP
INFOCARD_IP_PRIVACY_URL (Required1\-C)
.RS 4
This directive is required by
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2
and specifies the URL of the Identity Provider\*(Aqs
PrivacyNotice\&. A default notice is configured\&.
.RE
.PP
INFOCARD_IP_PRIVACY_VERSION (Optional1)
.RS 4
This optional directive is used by
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2
and specifies an integer version number (greater than zero) of the document returned by the
\m[blue]\fBINFOCARD_IP_PRIVACY_URL\fR\m[]\&\s-2\u[107]\d\s+2\&. If it is set to the empty string, however, no version number will be specified for the
PrivacyNotice\&. The default is "1"\&.
.RE
.PP
INFOCARD_ISSUER_INFO_ENTRY (Optional)
.RS 4
This optional directive, which may be repeated, is used by
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2
to specify arbitrary descriptive information to be included in managed InfoCards\&. This information may be displayed by an Identity Selector\&. The value of the directive is a string of the form "\fIEntryName\fR:\fIEntryValue\fR"\&.
.RE
.PP
INFOCARD_MEX_URL (Required1\-C)
.RS 4
This directive, used by
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2, specifies the URL of the WS\-MetadataExchange responder for managed InfoCards\&. Also see
\m[blue]\fBdacs_mex(8)\fR\m[]\&\s-2\u[108]\d\s+2\&.
.RE
.PP
INFOCARD_REQUIRE_APPLIES_TO (Optional1)
.RS 4
Used optionally by
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2, this directive controls a managed InfoCard\*(Aqs
RequireAppliesTo
element, which by default is omitted\&. This element is used to control whether the card\*(Aqs Identity Provider (e\&.g\&.,
\m[blue]\fBdacs_sts(8)\fR\m[]\&\s-2\u[94]\d\s+2) will be informed as to the identity of the Relying Party via the
wsp:AppliesTo
element (when it is informed, it is called an
\fIauditing card\fR, which is used in
\fIauditing mode\fR)\&. Following the Identity Selector Interoperability Profile, this directive may have any of the following values:
.PP
no
.RS 4
The
RequireAppliesTo
element is omitted (called a
\fInon\-auditing card\fR)\&.
.RE
.PP
yes
.RS 4
RequireAppliesTo
is emitted, but with its optional attribute omitted (an
\fIauditing card\fR)\&.
.RE
.PP
true
.RS 4
RequireAppliesTo
is emitted with the attribute
Optional="true"
(called an
\fIauditing\-optional card\fR)\&.
.RE
.PP
false
.RS 4
RequireAppliesTo
is emitted with the attribute
Optional="false"
(an
\fIauditing card\fR)\&.
.RE
.sp
.RE
.PP
INFOCARD_STRONG_RP_IDENTITY (Optional1)
.RS 4
Used optionally by
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2, if the value of this directive is "yes"
RequireStrongRecipientIdentity
is present in new managed InfoCards, which indicates that a Relying Party must use a cryptographically protected identity; i\&.e\&., an X\&.509 server certificate\&.
.RE
.PP
INFOCARD_STS_AUTH_TYPE (Required1\-C)
.RS 4
This directive, required by
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2, specifies (case\-insensitively) the authentication credential type, which identifies an Identity Selector user to an IP/STS (see
\m[blue]\fBdacs_sts(8)\fR\m[]\&\s-2\u[94]\d\s+2)\&. The value of this directive is consulted when a new managed InfoCard is created; the type may be changed without affecting the authentication credential type assigned to InfoCards created before the change\&. Recognized values are:
.PP
password
.br
passwd
.RS 4
This is the username/password credential type\&. See
\m[blue]\fBINFOCARD_STS_PASSWORD_METHOD\fR\m[]\&\s-2\u[109]\d\s+2\&.
.RE
.PP
cert
.RS 4
This is the X\&.509 V3 certificate credential type\&. An SSL client certificate must be used with the request to
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2
for a managed InfoCard, and the same certificate must be used when the managed InfoCard is submitted to a Relying Party\&. A self\-signed certificate may be used\&.
.RE
.PP
card
.RS 4
This is the self\-issued credential type\&. A self\-issued InfoCard must be submitted with the request to
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2
for a managed InfoCard, and the same self\-issued InfoCard must be available to the user\*(Aqs Identity Selector when the managed InfoCard is submitted to a Relying Party\&. This self\-issued InfoCard does not need to be separately registered using
\m[blue]\fBdacs_infocard(8)\fR\m[]\&\s-2\u[105]\d\s+2\&.
.RE
.PP
kerberos
.RS 4
This is the Kerberos V5 credential type\&. This authentication credential type is currently unsupported\&.
.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
\fBNote\fR
.ps -1
.br
Although the specification allows an ordered list of STS endpoints to appear, at present only a single endpoint may be configured\&.
.sp .5v
.RE
.RE
.PP
INFOCARD_STS_CACERTFILE (Required1\-C)
.RS 4
This directive, which is required by
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2, specifies the filename of the certificate authority\*(Aqs PEM\-encoded X\&.509 certificate for
\m[blue]\fBINFOCARD_STS_CERTFILE\fR\m[]\&\s-2\u[110]\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
File permissions and ownership must be set appropriately to allow run\-time access\&.
.sp .5v
.RE
.RE
.PP
INFOCARD_STS_CERTFILE (Required1\-C)
.RS 4
This directive, which is required by
\m[blue]\fBdacsinfocard(1)\fR\m[]\&\s-2\u[111]\d\s+2,
\m[blue]\fBdacs_infocard(8)\fR\m[]\&\s-2\u[105]\d\s+2, and
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2, specifies the filename of the PEM\-encoded X\&.509 certificate for the Secure Token Service provided by
\m[blue]\fBdacs_sts(8)\fR\m[]\&\s-2\u[94]\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
File permissions and ownership must be set appropriately to allow run\-time access\&. If a self\-signed certificate is being used, the appropriate root certificate must be installed on the system that is running the Identity Selector\&.
.sp .5v
.RE
.RE
.PP
INFOCARD_STS_KEYFILE (Required1\-C)
.RS 4
This directive, which is required by
\m[blue]\fBdacsinfocard(1)\fR\m[]\&\s-2\u[111]\d\s+2,
\m[blue]\fBlocal_infocard_authenticate\fR\m[]\&\s-2\u[112]\d\s+2,
\m[blue]\fBdacs_infocard(8)\fR\m[]\&\s-2\u[105]\d\s+2,
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2, and
\m[blue]\fBdacs_sts(8)\fR\m[]\&\s-2\u[94]\d\s+2, specifies the filename of the key for the X\&.509 certificate specified by
INFOCARD_STS_CERTFILE\&. If this file is password protected,
\m[blue]\fBINFOCARD_STS_KEYFILE_PASSWORD\fR\m[]\&\s-2\u[113]\d\s+2
must be configured\&.
.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
File permissions and ownership must be set appropriately to allow run\-time access\&.
.sp .5v
.RE
.RE
.PP
INFOCARD_STS_KEYFILE_PASSWORD (Required1\-C)
.RS 4
If
\m[blue]\fBINFOCARD_STS_KEYFILE\fR\m[]\&\s-2\u[114]\d\s+2
is encrypted, this directive is required to specify the password\&.
.RE
.PP
INFOCARD_STS_PASSWORD_METHOD (Required1\-C)
.RS 4
If the username/password credential type is needed by a managed InfoCard,
\m[blue]\fBdacs_sts(8)\fR\m[]\&\s-2\u[94]\d\s+2
requires this directive to specify how the username and password are to be validated:
.PP
empty
.RS 4
The password is no password at all (i\&.e\&., the empty string)\&. If a password
\fIis\fR
given, authentication will fail\&.
.RE
.PP
ignore
.RS 4
Any password string, including no password at all (i\&.e\&., the empty string), is acceptable\&.
.RE
.PP
sts
.RS 4
The given password string must exactly match the authentication\-time value of the configuration variable
\fIinfocard_sts_password\fR\&.
.RE
.PP
account:\fIid\fR
.RS 4
The given username and password must be valid relative to the specified
\fBDACS\fR
authentication module identified by the
Auth
clause label
\fIid\fR, which must be enabled and configured as per
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[52]\d\s+2\&. (Note:
\fIThis form is currently unsupported\fR\&.)
.RE
.sp
.RE
.PP
INFOCARD_STS_RP_ENDPOINT (Optional)
.RS 4
This directive causes
\m[blue]\fBdacs_sts(8)\fR\m[]\&\s-2\u[94]\d\s+2
to issue security tokens only to selected identified Relying Parties; if the identity of a Relying Party, as provided by the
Address
endpoint appearing in the token request\*(Aqs
AppliesTo
element (apparently the URL of the Relying Party\*(Aqs web page) does not match any instance of this directive, a token will not be returned\&. A token will be returned if this directive is not used or if the Relying Party is not identified\&. Not all Relying Parties are identified; see
\m[blue]\fBINFOCARD_REQUIRE_APPLIES_TO\fR\m[]\&\s-2\u[115]\d\s+2\&. The syntax for this directive is identical to that of
\m[blue]\fBINFOCARD_AUDIENCE\fR\m[]\&\s-2\u[116]\d\s+2\&. Although the Relying Party\*(Aqs server certificate can be provided with the identification material in the token request, it is not currently accessible to this directive\&.
.RE
.PP
INFOCARD_STS_URL (Required1\-C)
.RS 4
This directive, used by
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2,
\m[blue]\fBdacs_mex(8)\fR\m[]\&\s-2\u[108]\d\s+2, and
\m[blue]\fBdacs_sts(8)\fR\m[]\&\s-2\u[94]\d\s+2, specifies the URL of the Secure Token Service for managed InfoCards\&.
.RE
.PP
INFOCARD_TOKEN_DRIFT_SECS (Optional1)
.RS 4
A security token (produced by
\m[blue]\fBdacs_sts(8)\fR\m[]\&\s-2\u[94]\d\s+2, for instance) bears a validity condition; a relying party may reject a token if its current system date/time lies outside of the time window prescribed by the token\&. Because the clock at the IP/STS (which issued the token) and the clock at the relying party may not be closely synchronized \- the relying party\*(Aqs clock may be faster or slower than the IP/STS\*(Aqs clock \- a relying party may be willing to permit a certain amount of "clock drift" before it rejects a token\&. This directive specifies the maximum number of seconds that the IP/STS\*(Aqs clock may be too fast or too slow\&. If the directive\*(Aqs value is zero, or if the directive is not configured, a compile time default value is used (currently, 300 seconds)\&. If the directive\*(Aqs value is "disable", the validity test is suppressed\&.
.RE
.PP
INFOCARD_TOKEN_ISSUER (Required1\-C)
.RS 4
This directive, used by
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[95]\d\s+2
and
\m[blue]\fBdacs_sts(8)\fR\m[]\&\s-2\u[94]\d\s+2, specifies the
Issuer
of a managed InfoCard as a URI\&. The value "self" can be used to represent the special URI identifying a self\-issued InfoCard\&.
.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
If your Identity Selector does not let you choose a managed InfoCard when you think that it ought to (i\&.e\&., the value of this directive in effect when the managed InfoCard was created matches the web page\*(Aqs
issuer
parameter), it seems that the
INFOCARD_TOKEN_ISSUER
is ignored by an Identity Selector in preference to the name in the Identity Provider\*(Aqs SSL certificate\&. It has been noted that if a Relying Party uses a
\m[blue]\fBwildcard certificate\fR\m[]\&\s-2\u[117]\d\s+2, an Identity Selector may have trouble matching the
\fIissuer\fR
parameter in an HTML
OBJECT
request with an InfoCard; it may be necessary for the Relying Party to specify the value of the
\fIissuer\fR
parameter as the empty string\&.
.sp .5v
.RE
.RE
.PP
INFOCARD_TOKEN_LIFETIME_SECS (Optional1)
.RS 4
This optional directive specifies the lifetime, in seconds, of a secure token created by
\m[blue]\fBdacs_sts(8)\fR\m[]\&\s-2\u[94]\d\s+2\&. If not provided, a compile\-time value is used\&. To reduce the window of vulnerability where a token might be captured and used by an attacker, this period should be relatively short (on the order of a few seconds)\&. Note that a Relying Party is free to account for inadequately synchronized clocks when deciding whether it should accept a token, so this lifetime is effectively a recommendation for the recipient of the token\&. If the clocks at the Identity Selector and token issuer are not sufficiently synchronized, the Identity Selector will reject a token if the token\*(Aqs validity window is outside of its clock\*(Aqs current value\&.
.RE
.PP
INFOCARD_TOKEN_MAX_LENGTH (Optional1)
.RS 4
A relying party can use this directive to specify the maximum size (in bytes) of a security token that it will accept\&. If this directive is not configured or is zero, a compile time default value is used (currently, 16384 bytes)\&.
.RE
.PP
INFOCARD_USERNAME_SELECTOR (Optional1)
.RS 4
This directive determines how the
\fBDACS\fR
username is selected for a self\-issued InfoCard during registration by
\m[blue]\fBdacs_infocard(8)\fR\m[]\&\s-2\u[105]\d\s+2\&. The resulting identity is relative to the
\m[blue]\fBcurrent jurisdiction\fR\m[]\&\s-2\u[48]\d\s+2; that is, if the InfoCard is used to sign on at a jurisdiction where it was registered, the jurisdiction will issue credentials for the username that was registered with the InfoCard\&. The following directive values are recognized:
.PP
credentials
.RS 4
The username is obtained from the identity in effect at registration time; there may only be one such set of credentials and they must have been issued by the jurisdiction at which registration is occurring\&. This is the default behaviour if the directive is not given\&.
.RE
.PP
email
.RS 4
The username is obtained from the email address field of the InfoCard; the email address must be a syntactically valid username (see
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[80]\d\s+2)\&.
.RE
.PP
webpage
.RS 4
The username is derived from the web page URL field of the InfoCard; this is not currently implemented\&. (see
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[80]\d\s+2)\&.
.RE
.sp
.RE
.PP
JURISDICTION_NAME (Required1)
.RS 4
The name of the jurisdiction\&. The syntax is the same as for
\m[blue]\fBFEDERATION_NAME\fR\m[]\&\s-2\u[57]\d\s+2: an alphabetic followed by zero or more alphanumerics, \*(Aq\-\*(Aq (hyphens), or \*(Aq_\*(Aq (underscores)\&. Note that periods are not permitted\&. By convention, this name is in all\-caps, Please see
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[80]\d\s+2
for additional information\&. Example:
METALOGIC
.RE
.PP
LOGINGEN_FILE (Optional1)
.RS 4
Reserved for future use\&. (Used with the
\fBDACS\fR
\fBlogingen\fR
utility, this directive gives the full pathname of the template file\&.)
.RE
.PP
LOGINGEN_PROG (Optional1)
.RS 4
Reserved for future use\&. (Used with the
\fBDACS\fR
\fBlogingen\fR
utility, this directive specifies a program which will read
LOGINGEN_FILE
on its
stdin
and write the filtered output to
stdout\&.)
.RE
.PP
LOG_FILE (Optional1)
.RS 4
\fBDACS\fR
uses the
LOG_FILE
directive to identify the primary file to which it should write log information\&.
\fBDACS\fR
performs directory name interpolation on the pathname string using a syntax and method similar to
\fBApache\*(Aqs\fR
\m[blue]\fB\fBmod_vhost_alias\fR\fR\m[]\&\s-2\u[118]\d\s+2
module (see
\m[blue]\fBString Interpolation\fR\m[]\&\s-2\u[24]\d\s+2)\&.
.sp
The result after interpolation must either be the absolute pathname of a file to write log information to, or the word "syslog"\&. In the latter case,
\m[blue]\fBsyslog(3)\fR\m[]\&\s-2\u[119]\d\s+2
is used, with an
\fIident\fR
argument of "dacs" and a facility of "user"\&. Each
\fBDACS\fR
logging level is mapped to the corresponding
\fBsyslog\fR
level, with the
trace
level mapped to
\fBsyslog\*(Aqs\fR
debug
level\&.
.sp
While
\fBDACS\fR
is starting and before it reads and processes its configuration files, this directive is not yet available to it; until
\fBDACS\fR
knows what
LOG_FILE
is, or should
LOG_FILE
not be writable, the value of
LOG_FILE
is obtained from the value of
DACS_LOG\&. A compile\-time specified value,
DACS_LOG
can be specified when
\fBDACS\fR
is built (the default is equivalent to
${Conf::DACS_HOME}/logs/error_log)\&. If
DACS_LOG
is unusable,
stderr
is used\&.
.RE
.PP
LOG_FILTER (Stack)
.RS 4
This directive configures a fine\-grained way of specifying which messages will be written compared to the
\m[blue]\fBLOG_LEVEL\fR\m[]\&\s-2\u[120]\d\s+2
directive\&. The directive, which may be repeated, selects the types of events that
\fBDACS\fR
\fIshould\fR
log; unselected events are not recorded in a log file\&. It also provides a way for different kinds of messages to be logged to different files\&.
.sp
Because this directive is in the
\m[blue]\fBStack category\fR\m[]\&\s-2\u[13]\d\s+2, "later" directives supercede earlier ones\&. When a directive is found that allows a message to be logged, no additional directives are examined for the message\&. If this directive is not given, the default filtering is done based on the
LOG_LEVEL
and
LOG_SENSITIVE
directives\&.
.sp
The syntax is one of:
.sp
.if n \{\
.RS 4
.\}
.nf
LOG_FILTER "\fItype\fR \fIflag\fR[,\fIflag\fR]* \fIlevel\fR \fIname\fR [[+|\-]\fIfile\fR]"
LOG_FILTER "any \fIflag\fR[,\fIflag\fR]* \fIlevel\fR [[+|\-]\fIfile\fR]"
.fi
.if n \{\
.RE
.\}
.sp
The
\fItype\fR, which is one of the keywords
program,
module,
filename, or
function
(case insensitive), specifies the type of the event source to which this filter applies; i\&.e\&., it indicates what
\fIname\fR
is to be matched against\&. If
\fItype\fR
is
filename, for instance, it means that for this filter to be applicable to a particular log message, the
\fIname\fR
must match the filename from which the log message is generated\&.
.sp
A list of comma\-separated, case\-insensitive modifier flags specifies how matching of
\fItype\fR
is done against
\fIname\fR\&. A
\fIflag\fR
can have the value
exact,
regex,
icase,
sensitive,
user,
audit, or
normal\&.
.sp
The
\fIname\fR
is matched against
\fItype\fR
case sensitively, unless the
icase
flag is present\&. Matching is performed using
\m[blue]\fBregex(3)\fR\m[]\&\s-2\u[121]\d\s+2
regular expression matching if the
regex
flag is present, or using a string comparison if the
exact
flag is present (these two flags are mutually exclusive)\&.
.sp
A message can have no attributes associated with it, or any combination of the attributes
sensitive,
user, and
audit\&. Messages with the
sensitive
attribute might include potentially private information, such as a password\&. Messages with the
audit
attribute include relatively high\-level events, such as successful and unsuccessful authentication results, signouts, and access control decisions\&. The
user
attribute is associated with messages produced by the
\m[blue]\fBprint()\fR\m[]\&\s-2\u[122]\d\s+2
and
\m[blue]\fBprintf()\fR\m[]\&\s-2\u[123]\d\s+2
functions\&.
.sp
Modifier flags are used to select (or deselect) messages to be logged\&. By default, only
normal
messages are logged; these are messages without any attributes\&. The
\m[blue]\fBLOG_SENSITIVE\fR\m[]\&\s-2\u[124]\d\s+2
directive can change the default to enable
sensitive
messages\&.
.sp
If the
audit
flag is given, a message is logged only if it has that attribute\&. Messages with the
sensitive
attribute are not logged unless the
sensitive
flag is given, and messages with the
user
attribute are not logged unless the
user
flag is given\&.
.sp
Assuming the
\fItype\fR
and
\fIlevel\fR
do not deselect the message, here are some example cases:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a message without any attributes will be logged provided the
audit
flag is not specified
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
a message with both the
audit
and
sensitive
attributes will be logged only if the filter specifies the
audit
flag, and either the
sensitive
flag is given or
LOG_SENSITIVE
is enabled
.RE
.sp
If the directive\*(Aqs value begins with the keyword
any, the filter matches any source, so there is no
\fIname\fR
and the modifier flags related to matching
\fIname\fR
are ignored\&.
.sp
In order of increasing importance and decreasing amount of detail,
\fIlevel\fR
is one of the following case\-insensitive keywords:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
trace
(or
tracing, least important messages)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
debug
(or
debugging)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
info
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
notice
(or
notices)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
warn
(or
warning
or
warnings)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
error
(or
errors)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
critical
(or
crit)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
alert
(or
alerts)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
emerg
(or
emergency, most important messages)
.RE
.sp
Any log message having a lower importance than
\fIlevel\fR
will not satisfy the filter\&. If the logging level is set to
info, for example, messages having a lower level (debug
and
trace) will not be recorded\&. These levels are intended to have semantics similar to those of the logging levels used by
\fBApache\fR
and
\m[blue]\fBsyslog(3)\fR\m[]\&\s-2\u[119]\d\s+2\&.
.sp
The
\fIfile\fR
field, which is optional, is used instead of (or in addition to)
LOG_FILE
and interpolation is performed in the same way\&. If
\fIfile\fR
is
syslog, all messages matching the filter will be written using
\fBsyslog(3)\fR
instead of to
LOG_FILE\&. If
\fIfile\fR
is prefixed with a \*(Aq+\*(Aq, output will be written to both
LOG_FILE
and the expansion of
\fIfile\fR; if it is prefixed with nothing or
\-, the default behaviour results; the initial character can be escaped using a backslash\&. In some situations, using
/dev/null
for
\fIfile\fR
is useful to discard unhelpful messages\&.
.sp
Without regard to how
LOG_LEVEL
and
LOG_SENSITIVE
are configured, this directive says that all messages generated by any function located within the
\fBDACS\fR
source file named
crypto\&.c
having a level of at least
debug, should be logged, including those marked as
sensitive:
.sp
.if n \{\
.RS 4
.\}
.nf
LOG_FILTER \*(Aqfilename exact,sensitive debug crypto\&.c\*(Aq
.fi
.if n \{\
.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
\fBTip\fR
.ps -1
.br
The directive:
.sp
.if n \{\
.RS 4
.\}
.nf
LOG_FILTER \*(Aqany audit trace +syslog\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
causes all log messages with the
audit
modifier having level
trace
or higher to be written to both
\fBsyslog(3)\fR
and
LOG_FILE\&. If you want to use the
syslog
feature in this way, you will need a section in the
\fBsyslog(3)\fR
configuration file (typically
/etc/syslog\&.conf) that looks something like the following, depending on the flavour of
\fBsyslog(3)\fR
that your system uses:
.sp
.if n \{\
.RS 4
.\}
.nf
!dacs
*\&.* /usr/local/dacs/logs/audit_log
.fi
.if n \{\
.RE
.\}
.sp
The following directive is similar except that it causes log messages classified as either
audit
or
sensitive
(or both) to be written to both
LOG_FILE
and the file
logs/Audit_log, relative to the root of the
\fBDACS\fR
installation directory:
.sp
.if n \{\
.RS 4
.\}
.nf
LOG_FILTER \*(Aqany audit,sensitive TRACE +%bD/logs/Audit_log\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
By removing the \*(Aq+\*(Aq character, the log messages would not be written to
LOG_FILE\&.
.sp .5v
.RE
Please refer to
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[125]\d\s+2
for general information about logging\&.
.RE
.PP
LOG_FORMAT (Optional1)
.RS 4
This directive is used to specify the format of the string that prefixes log messages produced by
\fBDACS\fR\&. Interpolation is controlled by
\fBprintf\fR\-like format specifiers, as follows:
.PP
%%
.RS 4
Insert a literal percent character
.RE
.PP
%a
.RS 4
Insert the application name, which is typically the basename of
\fIargv[0]\fR\&.
.RE
.PP
%c
.RS 4
Insert the value of a per\-process message counter, which is then incremented\&.
.RE
.PP
%F
.RS 4
Insert event descriptor flags, which indicate whether the message is an audit event ("A"), a potentially sensitive event ("S"), a user event ("U"), or a normal event ("\-")\&.
.RE
.PP
%fn
.RS 4
Interpolate the federation name\&.
.RE
.PP
%fd
.RS 4
Interpolate the federation domain\&.
.RE
.PP
%j
.RS 4
Interpolate the jurisdiction name\&.
.RE
.PP
%l
.RS 4
Interpolate the log level of the message\&.
.RE
.PP
%p
.RS 4
Interpolate the process id of the process generating the message\&.
.RE
.PP
%sF
.RS 4
Interpolate the name of the function generating the message\&.
.RE
.PP
%sf
.RS 4
Interpolate the name of the file generating the message\&.
.RE
.PP
%sl
.RS 4
Interpolate the line number within the file that is generating the message\&.
.RE
.PP
%sm
.RS 4
Interpolate the name of the module generating the message\&.
.RE
.PP
%sp
.RS 4
Interpolate the name of the program generating the message\&.
.RE
.PP
%t
.RS 4
Interpolate the current time and date\&.
.RE
.sp
If a
%
is followed by any other character, that character is printed\&. Other characters in the format specifier are interpolated verbatim\&. If a requested value is not available, nothing is interpolated\&.
.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
When debugging, it is often helpful to compare log messages produced when slightly different configurations are used to service a given request\&. With the default prefix, log messages tend to be unique\&. To make it easier to compare two sequences of log messages (e\&.g\&., using
\m[blue]\fBdiff(1)\fR\m[]\&\s-2\u[126]\d\s+2), append a special character (such as a tab) or a readily distinguished character string to the
LOG_FORMAT
format string\&. This will simplify stripping the prefix from log messages (e\&.g\&., using
\m[blue]\fBsed(1)\fR\m[]\&\s-2\u[127]\d\s+2)\&. Alternatively, set an empty prefix string, or write a conditional directive that eliminates the prefix only when debugging\&.
.sp .5v
.RE
.RE
.PP
LOG_LEVEL (Optional1)
.RS 4
This directive specifies the minimum default logging level in effect \- log messages less important than this will be discarded\&. For example, if
LOG_LEVEL
is
warn, only log message of that level or more important will be written and all others will be discarded\&. If there is an applicable
\m[blue]\fBLOG_FILTER\fR\m[]\&\s-2\u[128]\d\s+2
directive it overrides this behaviour, however\&.
.sp
Briefly, in order of increasing importance, the names of the levels are:
trace,
debug,
info,
notice,
warn,
error,
critical,
alert, and
emerg\&. The
trace
logging level emits the most detail and the
emerg
level emits the least\&. Refer to the
\m[blue]\fBLOG_FILTER\fR\m[]\&\s-2\u[128]\d\s+2
directive for additional information\&.
.sp
The
LOG_LEVEL
overrides the compile\-time default, which is obtained using the
LOG_DEFAULT_LEVEL
symbol\&.
.sp
By default, informational log messages are emitted almost immediately when most
\fBDACS\fR
web services begin execution\&. To suppress these messages, without regard to any other logging configuration, build
\fBDACS\fR
with
\m[blue]\fB\-\-enable\-hush\-startup\-logging\fR\m[]\&\s-2\u[129]\d\s+2\&.
.sp
The "verbose" command line flag (\fB\-v\fR) or the
VERBOSE_LEVEL
directive overrides this directive, which are in turn overridden by the
\fI\-t\fR
command line flag ("trace") or the
TRACE_LEVEL
directive\&. A verbose level of one is equivalent to the info level; a verbose level greater than one is equivalent to the debug level\&. Enabling a trace level, with any value, is equivalent to requesting the trace logging level\&.
.sp
Also see
\m[blue]\fBdebug_dacs\fR\m[]\&\s-2\u[130]\d\s+2\&.
.RE
.PP
LOG_SENSITIVE (Optional1)
.RS 4
This directive determines the default behaviour for logging messages with the
sensitive
attribute\&. It may have the values "yes" (to enable logging sensitive messages) or "no" (the default, which discards such messages)\&.
.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
Sensitive messages may include passwords and other authentication material that should remain private\&. This directive will not suppress potentially sensitive messages generated by third\-party support packages (e\&.g\&.,
\fBSamba\fR
or
\fBOpenLDAP\fR),
\fBApache\fR
(including
\fBmod_auth_dacs\fR), or the operating system\&. For example, requests for CGI programs invoked using the
GET
method will be logged in the
\fBApache\fR
Access Log, and the request\*(Aqs query string will typically be printed; password parameters may be present in the log (see
\m[blue]\fBmod_log_config\fR\m[]\&\s-2\u[131]\d\s+2
for details of how to change the log format\&. If sensitive messages are being logged, make doubly\-sure that log files have appropriate permissions\&. Also, unencrypted logging messages directed over a network (e\&.g\&., through
\m[blue]\fBsyslog(3)\fR\m[]\&\s-2\u[119]\d\s+2) may be visible to an attacker\&.
.sp .5v
.RE
.RE
.PP
NAME_COMPARE (Optional1)
.RS 4
This directive sets the default method used to compare
\fBDACS\fR
names in various contexts\&. Ordinarily, federation, jurisdiction, usernames, and group names are compared case\-sensitively\&. If the value of this directive is (case\-insensitively)
case, then case\-sensitive comparisons are used; if its value is
nocase, case\-insensitive comparisons are used; if its value is
default, then the application default (either
case
or the value selected by the application) is used\&. This directive can be overridden on a case\-by\-case basis (pun intended); refer to the
\fBuser()\fR
function (\m[blue]\fBdacs\&.exprs(5)\fR\m[]\&\s-2\u[20]\d\s+2) for details\&.
.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
The selected comparison method applies to
\fIall\fR
components of
\fBDACS\fR
names; if this is not desired, the
\fBstrtr()\fR
function might be helpful\&. Note that this directive does not alter the
\fBDACS\fR
name determined by authentication, only the way the name is compared\&. While it\*(Aqs unlikely (and bad practice) for federation names (or jurisdiction names) to differ only in their case, it is not unusual for usernames to be treated case\-insensitively for authentication purposes and for this reason this feature should be used with care\&. When case\-insensitive comparisons are used, the usernames
bob
and
BOB
will be considered to be equivalent, for example; sometimes this is useful but it can also be a security hole, depending on how authentication is configured\&.
.sp
Changing the comparison method from case\-insensitive back to case\-sensitive may have undesirable consequences; identities that were formerly equivalent might suddenly become distinct, which at the very least may confuse users\&.
.sp
The recommended practice is to not define
NAME_COMPARE
or set it to
case
because of its system\-wide effects\&. When needed, use the
\fBuser()\fR
function with an appropriate comparison method argument\&.
.sp .5v
.RE
.RE
.PP
NOTICES_ACCEPT_HANDLER (Optional1)
.RS 4
This directive provides a URL (absolute or relative) to which a user agent will be redirected by the notice acknowledgement handler after a positive acknowledgement to a notice has been received (i\&.e\&., when the notice or notices were "accepted"), but only if it is not possible to redirect the user agent to the request that initiated notice acknowledgement processing (e\&.g\&., if that request used the
POST
method)\&. If not provided, a default HTML page will be returned\&.
.RE
.PP
NOTICES_ACK_HANDLER (Optional1)
.RS 4
This directive provides the URL of the notice acknowledgement handler, which is the program that receives a user\*(Aqs response to a request to acknowledge one or more notices\&. If not provided or if it is the empty string, the notice presentation handler should assume that it must also act as the notice acknowledgement handler\&.
.RE
.PP
NOTICES_DECLINE_HANDLER (Optional1)
.RS 4
This directive provides a URL (absolute or relative) to which a user agent will be redirected by the notice acknowledgement handler after a negative acknowledgement to a notice has been received (i\&.e\&., when the notice or notices were "declined")\&. If not provided, a default HTML page will be returned\&.
.RE
.PP
NOTICES_NAT_NAME_PREFIX (Optional1)
.RS 4
The default prefix of the name of the HTTP cookie bearing a notice acknowledgement token is "NAT\-DACS"\&. This directive can be used to override the default\&.
.RE
.PP
NOTICES_SECURE_HANDLER (Optional1)
.RS 4
By default,
\m[blue]\fBdacs_notices(8)\fR\m[]\&\s-2\u[132]\d\s+2
takes steps to prevent attempts to simply ask for notice acknowledgement tokens (NATs), effectively bypassing having to see notices\&. If the value of this directive is "no", however, these steps will be disabled\&. Please refer to the description of
\fBdacs_notices\fR\*(Aq
\m[blue]\fBSecure Mode\fR\m[]\&\s-2\u[133]\d\s+2
of operation\&.
.RE
.PP
NOTICES_WORKFLOW_LIFETIME_SECS (Optional1)
.RS 4
By default, a secure notice acknowledgement workflow must complete within 120 seconds\&. This directive can be used to specify an unsigned integer value that will override the default\&.
.RE
.PP
PAMD_HOST (Optional1)
.RS 4
When
\m[blue]\fBlocal_pam_authenticate\fR\m[]\&\s-2\u[134]\d\s+2
is used, this directive is required to specify the domain name or IP address of the host where
\m[blue]\fBpamd(8)\fR\m[]\&\s-2\u[135]\d\s+2
is executed\&.
.RE
.PP
PAMD_PORT (Optional1)
.RS 4
When
\m[blue]\fBlocal_pam_authenticate\fR\m[]\&\s-2\u[134]\d\s+2
is used, this may be used to specify the port number or service name on
PAMD_HOST
where the
\m[blue]\fBpamd(8)\fR\m[]\&\s-2\u[135]\d\s+2
server accepts connections\&. This directive can be overridden on the
\fBpamd\fR
command line\&. If no value is explicitly specified, programs will use the compile\-time symbol
PAMD_SERVICE_NAME
(by default, "dacs\-pamd"), which assumes that
/etc/services
has been configured accordingly\&.
.RE
.PP
PASSWORD_CONSTRAINTS (Optional1)
.RS 4
This directive describes requirements that must be met by new passwords created by
\m[blue]\fBdacs_passwd(8)\fR\m[]\&\s-2\u[136]\d\s+2, other than when used by a
\fBDACS\fR
administrator\&. In other situations, where a
\fBDACS\fR
administrator must be running the program (such as with
\m[blue]\fBdacspasswd(1)\fR\m[]\&\s-2\u[137]\d\s+2
or
\m[blue]\fBdacstoken(1)\fR\m[]\&\s-2\u[138]\d\s+2), a warning message is produced if a new, non\-conforming password or PIN is set but the password can still be used\&.
.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
Each system usually imposes its own constraints on the characters that may be used in password, minimum and maximum password lengths, and so on\&. These constraints are external to
\fBDACS\fR\&. With respect to the
\fIPASSWORD\fR
parameter passed to
\fBDACS\fR
web services (e\&.g\&.,
\m[blue]\fBlocal_ldap_authenticate\fR\m[]\&\s-2\u[91]\d\s+2) and used with
\fBDACS\fR
accounts (e\&.g\&.,
\m[blue]\fBdacspasswd(1)\fR\m[]\&\s-2\u[137]\d\s+2), it is safest to stick to printable ASCII characters\&. A compile\-time maximum length of
\fB128\fR
characters is imposed on the
\fIPASSWORD\fR
parameter\&. Limits are also imposed on the
\fIUSERNAME\fR
and
\fIAUXILIARY\fR
parameters (see
\m[blue]\fBWeb Service Arguments\fR\m[]\&\s-2\u[139]\d\s+2)\&. These limits are more\-or\-less arbitrary but necessary\&.
.sp .5v
.RE
This directive\*(Aqs syntax is also used by the
\m[blue]\fBPASSWORD_AUDIT\fR\m[]\&\s-2\u[140]\d\s+2
directive, which may appear in an
Auth
clause\&.
.sp
The format of the constraint string is a set of zero or more comma\-separated terms\&. Each term consists of an unsigned integer (zero or greater) followed immediately by a single character (case sensitive) that indicates a
\fIconstraint type\fR:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
L
refers to the minimum length of a password, in characters;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
C
is the minimum number of characters
\fIfrom each case\fR
that must be present (e\&.g\&.,
3C
means a password must have at least three upper case characters
\fIand\fR
three lower case characters);
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
D
is the minimum number of digits (0\-9) that must be present;
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
and
P
is the minimum number of punctuation characters (see
\m[blue]\fBispunct(3)\fR\m[]\&\s-2\u[141]\d\s+2) that must be present\&.
.RE
.sp
A constraint type may not appear more than once\&. Not all constraint types need to be specified\&. If this directive is not given, or is the empty string, or the word "none" (case insensitive), a minimum password length of any six characters is used\&. If a constraint type is missing, a minimum of zero is used\&. In no event is a password of fewer than six characters allowed for a non\-administrator, however\&.
.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
No check is made for constraints that are impossible to satisfy\&.
.sp .5v
.RE
.sp
For example, the following directive says that passwords must be at least eight characters long and include at least one digit and one upper case and one lower case character, with no punctuation characters required:
.sp
.if n \{\
.RS 4
.\}
.nf
PASSWORD_CONSTRAINTS "8L,1D,1C,0P"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
PASSWORD_DIGEST (Optional1)
.RS 4
This directive specifies the cryptographic hash function or key derivation function used by
\m[blue]\fBdacspasswd(1)\fR\m[]\&\s-2\u[137]\d\s+2,
\m[blue]\fBdacs_passwd(8)\fR\m[]\&\s-2\u[136]\d\s+2,
\m[blue]\fBdacstoken(1)\fR\m[]\&\s-2\u[138]\d\s+2,
\m[blue]\fBdacs_token(8)\fR\m[]\&\s-2\u[142]\d\s+2, and
\m[blue]\fBdacs_admin(8)\fR\m[]\&\s-2\u[143]\d\s+2
for computing password digests\&. The same specification syntax described here is used in other contexts throughout
\fBDACS\fR
where a digest function needs to be parameterized\&. Not all digest functions can be used in all contexts, however (see
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[144]\d\s+2)\&. By default,
SHA\-512
is used\&. Prior to version
1\&.4\&.34, the default was
SHA\-1\&.
.sp
In most cases only the name of the function is required, but functions that are parameterized (e\&.g\&.,
SCRYPT) require
\fIall\fR
configurable variables to be provided \- there are no defaults\&.
.sp
The syntax for specifying a cryptographic digest is as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
\fIdigest\-descriptor\fR ::= \fIdn\fR \fIws\fR* [ \*(Aq[\*(Aq \fIarg\-list\fR \*(Aq]\*(Aq ]
\fIarg\-list\fR ::= \fIname\fR \*(Aq=\*(Aq \fIvalue\fR [, \fIarg\-list\fR ]
.fi
.if n \{\
.RE
.\}
.sp
A
\fIdigest\-descriptor\fR
is a digest name (\fIdn\fR), optionally followed by whitespace, optionally followed by an argument string (\fIarg\-list\fR) within square brackets\&. The argument string consists of one or more
name=value
pairs, separated by a comma\&. The order of the pairs is not significant\&. A
\fIname\fR
may not appear more than once and an unrecognized parameter name is not allowed\&. Nothing can follow the closing square bracket\&. Whitespace may precede a
\fIname\fR, but everything following the \*(Aq=\*(Aq is part of the value\&. The
\fIvalue\fR
ends at a comma or the closing bracket, so embedded whitespace is possible (but should be avoided)\&. Whitespace following a comma is ignored\&. A
\fIvalue\fR
may be surrounded by single or double quotes, but escaping is not allowed\&. Examples:
.sp
.if n \{\
.RS 4
.\}
.nf
PASSWORD_DIGEST "scrypt[N=1024, r=\*(Aq8\*(Aq, p=16, dklen=32]"
PASSWORD_DIGEST "sha512/t[t=72]"
PASSWORD_DIGEST "pbkdf2[a=sha256,count=4098, dklen=20]"
.fi
.if n \{\
.RE
.\}
.sp
The digest name is matched against available password digest functions case\-insensitively\&. Non\-consecutive hyphens, underscores, and slashes in the digest name are treated as equivalent separators\&. A separator may be omitted if doing so would not join two digits\&. An initial or trailing separator is disallowed\&. For example:
.sp
.if n \{\
.RS 4
.\}
.nf
"Sha224" matches "SHA\-224"
"SHA/512" matches "SHA\-512"
"pbkdf2sha512" matches "PBKDF2\-SHA512"
.fi
.if n \{\
.RE
.\}
.sp
Use the
digests
subcommand of
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[144]\d\s+2
to list available algorithms and
checkdigest
to validate a digest descriptor:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacs digests
% dacs checkdigest "pbkdf2[a=sha256,count=80000,dklen=32]"
.fi
.if n \{\
.RE
.\}
.sp
The following cryptographic digest algorithms are available:
.PP
CRYPT
.RS 4
for the Unix
\m[blue]\fBcrypt(3)\fR\m[]\&\s-2\u[145]\d\s+2
function
.RE
.PP
MD5
.RS 4
for the
\m[blue]\fBMD5 function\fR\m[]\&\s-2\u[146]\d\s+2
(deprecated)\&.
.RE
.PP
SHA\-1
.br
SHA\-224
.br
SHA\-256
.br
SHA\-384
.br
SHA\-512
.br
SHA\-512/224
.br
SHA\-512/256
.br
SHA\-512/t
.RS 4
,
,
,
,
for one of the variants of the Secure Hash Algorithm functions (\m[blue]\fBFIPS 180\-4\fR\m[]\&\s-2\u[147]\d\s+2)\&.
.RE
.PP
SHA3\-224
.br
SHA3\-256
.br
SHA3\-384
.br
SHA3\-512
.RS 4
,
,
,
for one of the variants of the Secure Hash Algorithm\-3 functions (\m[blue]\fBFIPS PUB 202, August/2015\fR\m[]\&\s-2\u[148]\d\s+2)\&.
.RE
.sp
The following password\-based key derivation algorithms are available:
.PP
ARGON2
.RS 4
for the
\m[blue]\fBArgon2\fR\m[]\&\s-2\u[149]\d\s+2
memory\-hard password\-based key derivation function\&. Required parameters with suggested minimum values:
.PP
y
.RS 4
The algorithm flavour, which must be "i" for
Argon2i
or "d" for
Argon2d
(suggested: "i")\&.
.RE
.PP
v
.RS 4
The version identifier, in decimal, which currently must be
\fB19\fR\&.
.RE
.PP
m
.RS 4
The memory requirement, in KB (suggested:
\fB32\fR)\&.
.RE
.PP
t
.RS 4
The iteration count (suggested:
\fB3\fR)\&.
.RE
.PP
p
.RS 4
The amount of requested parallelism, referred to as "lanes" (suggested:
\fB4\fR)\&.
.RE
.PP
T
.RS 4
The output length, in bytes (suggested:
\fB32\fR)\&.
.RE
.PP
X
.RS 4
The associated data, encoded as a hex string\&. Use the empty string if there is no associated data\&.
.RE
.PP
S
.RS 4
The salt, encoded as a hex string\&. In this context,
\fIthis must be the empty string\fR, because the salt is stored elsewhere in the password entry\&.
.RE
.sp
Example:
.sp
.if n \{\
.RS 4
.\}
.nf
PASSWORD_DIGEST "argon2[y=i,v=19,m=32,t=3,p=4,T=32,X=\*(Aq000102\*(Aq,S=\*(Aq\*(Aq]"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
PBKDF2
.RS 4
for the
PBKDF2
password\-based key derivation function with the internal hash function specified by the first argument\&. Required parameters (with suggested minimum values):
.PP
a
.RS 4
The name of the internal hash function, such as "sha1", "sha256", "sha512", "sha3\-256", or "sha3\-512"\&.
.RE
.PP
count
.RS 4
The iteration count (suggested:
\fB80,000\fR)\&.
.RE
.PP
dklen
.RS 4
The output length in bytes, also called the derived key length (suggested:
\fB32\fR)\&.
.RE
.sp
.RE
.PP
PBKDF2\-SHA1
.RS 4
for the
PBKDF2
password\-based key derivation function with
HMAC\-SHA1
(see
\m[blue]\fBRFC 2898\fR\m[]\&\s-2\u[150]\d\s+2)\&. This should probably be avoided in preference to
PBKDF2\-SHA256
or
PBKDF2\-SHA512\&. Required parameters (with suggested minimum values):
.PP
count
.RS 4
The iteration count (suggested:
\fB80,000\fR)\&.
.RE
.PP
dklen
.RS 4
The output length in bytes, also called the derived key length (suggested:
\fB32\fR)\&.
.RE
.sp
.RE
.PP
PBKDF2\-SHA256
.RS 4
for the
PBKDF2
password\-based key derivation function with
HMAC\-SHA256\&. Required parameters (with suggested minimum values):
.PP
count
.RS 4
The iteration count (suggested:
\fB80,000\fR)\&.
.RE
.PP
dklen
.RS 4
The output length in bytes, also called the derived key length (suggested:
\fB32\fR)\&.
.RE
.sp
.RE
.PP
PBKDF2\-SHA512
.RS 4
for the
PBKDF2
password\-based key derivation function with
HMAC\-SHA512\&. Required parameters (with suggested minimum values):
.PP
count
.RS 4
The iteration count (suggested:
\fB80,000\fR)\&.
.RE
.PP
dklen
.RS 4
The output length in bytes, also called the derived key length (suggested:
\fB64\fR)\&.
.RE
.sp
.RE
.PP
SCRYPT
.RS 4
for the
scrypt
memory\-hard password\-based key derivation function, which uses
PBKDF2\-SHA256\&. Required parameters (with suggested minimum values):
.PP
N
.RS 4
CPU/memory cost parameter (suggested:
\fB131,072\fR)\&.
.RE
.PP
r
.RS 4
Block size parameter (suggested:
\fB8\fR)\&.
.RE
.PP
p
.RS 4
Parallelization parameter (suggested:
\fB1\fR)
.RE
.PP
dklen
.RS 4
The output length in bytes, also called the derived key length (suggested:
\fB32\fR)\&.
.RE
.sp
.RE
.sp
The
PBKDF2,
scrypt, and
Argon2
functions should be carefully parameterized to be computationally intensive and memory intensive, if applicable, for the platform on which the password\-based authentication module is run\&. The goal is to make password hashing unavoidably inefficient\&. This makes it more difficult for an attacker that accesses a copy of a password file to guess passwords because each guess takes longer or requires more resources than a comparatively efficient algorithm\&. For additional information about these algorithms and their parameters, see
\m[blue]\fBargon2()\fR\m[]\&\s-2\u[151]\d\s+2,
\m[blue]\fBpbkdf2()\fR\m[]\&\s-2\u[152]\d\s+2, and
\m[blue]\fBscrypt()\fR\m[]\&\s-2\u[153]\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
\fBSecurity\fR
.ps -1
.br
Apart from using an authentication method stronger than one based solely on passwords, it is considered best practice to use a key derivation function such as
\fBpbkdf2\fR
or
\fBscrypt\fR
rather than a plain cryptographic digest for the
PASSWORD_DIGEST\&.
.sp
These key derivation functions are intended to be inherently inefficient yet as efficient as possible\&. They are used for this purpose to provide additional resistance against brute force methods, even those that employ special hardware, should an attacker obtain a password file\&. But they do not help much if users are allowed to choose weak passwords, if the key derivation function is not properly parameterized, or if the function has exploitable properties\&. In these cases, it will still not be much of a challenge for an attacker to determine the original passwords\&. On the other hand, if only strong passwords are allowed and a good cryptographic digest function is used, a key derivation function is unnecessary\&. A key derivation function is most suitable for protecting passwords that are neither very weak nor particularly strong\&.
.sp
Memory\-hard functions are a relatively new idea and many designs have not yet received much scrutiny\&. It should also be noted that significantly increasing the memory and CPU resources needed for each authentication operation could pose a problem for sites that must be prepared to handle many concurrent sign\-ons\&. Running several memory\-hard functions simultaneously on a server could cause it to run out of resources, which may provide an opportunity for denial of service attacks\&.
.sp
The selected password digest algorithm and its parameters should be reviewed periodically\&. If changes are made to
PASSWORD_DIGEST, they will apply to new accounts but existing password entries will not be invalidated, so it may be necessary to force users to reset their passwords\&.
.sp .5v
.RE
The digest algorithm and parameters used are stored with a password entry when the password is set or changed\&. The algorithm or its parameters can therefore be reconfigured without voiding any pre\-existing password entries\&. As processing power continues to increase, the strength of the configured
PASSWORD_DIGEST
should periodically be increased\&. An administrator can determine the digest method used for each password entry (see
\m[blue]\fBdacspasswd(1)\fR\m[]\&\s-2\u[137]\d\s+2), and a user that has an entry that employed a relatively weak method should be asked to re\-register his password\&.
.sp
The system
\fBcrypt()\fR
function may have platform\-dependent limitations on the number of characters that are significant in a password or the maximum length of a password, but all other algorithms use all of the characters and impose no maximum password length\&.
.RE
.PP
PASSWORD_OPS_NEED_PASSWORD (Optional1)
.RS 4
Ordinarily,
\m[blue]\fBdacspasswd(1)\fR\m[]\&\s-2\u[137]\d\s+2
will not allow password maintenance operations (other than listing) unless the user has authenticated as an
\m[blue]\fBADMIN_IDENTITY\fR\m[]\&\s-2\u[39]\d\s+2
or provides a valid password for the username being administered (one that was created by
\m[blue]\fBdacspasswd(1)\fR\m[]\&\s-2\u[137]\d\s+2)\&. If this directive is "no", a password is not required and
\fBdacspasswd\fR
will assume that all necessary access control has already been performed\&.
.RE
.PP
PASSWORD_SALT_PREFIX (Optional1)
.RS 4
This string is prepended to a random salt string used when creating a digest of a password used by
\fBDACS\fR
in various contexts (e\&.g\&.,
\m[blue]\fBdacspasswd(1)\fR\m[]\&\s-2\u[137]\d\s+2)\&. This may be of interest when
\m[blue]\fBPASSWORD_DIGEST\fR\m[]\&\s-2\u[106]\d\s+2
is
CRYPT
because some versions of
\m[blue]\fBcrypt(3)\fR\m[]\&\s-2\u[145]\d\s+2
interpret the salt string\&.
.RE
.PP
PERMIT_CHAINING (Optional1)
.RS 4
If "yes", credentials exported by
\m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[6]\d\s+2
anywhere in the federation as a result of a rule having the
permit_chaining
attribute set to
yes
will be honoured at this jurisdiction for access control purposes\&.
.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
Enabling this feature weakens security because it may allow misappropriated
\fBDACS\fR
identities to be used at a jurisdiction that has enabled
PERMIT_CHAINING\&. Use of this feature is discouraged but is sometimes necessary; use with care\&. Refer to the description of the
permit_chaining
attribute in
\m[blue]\fBdacs\&.acls(5)\fR\m[]\&\s-2\u[25]\d\s+2\&.
.sp .5v
.RE
.RE
.PP
PROXY_EXEC_DOCUMENT_ROOT (Optional1)
.RS 4
Reserved for future use\&.
.RE
.PP
PROXY_EXEC_MAPPER_DEFAULT_ACTION (Optional1)
.RS 4
Reserved for future use\&.
.RE
.PP
PROXY_EXEC_MAPPER_LOGGING (Optional1)
.RS 4
Reserved for future use\&.
.RE
.PP
PROXY_EXEC_MAPPER_LOG_FILE (Optional1)
.RS 4
Reserved for future use\&.
.RE
.PP
PROXY_EXEC_MAPPER_RULES_FILE (Optional1)
.RS 4
Reserved for future use\&.
.RE
.PP
PROXY_EXEC_PROG_URI (Optional1)
.RS 4
Reserved for future use\&.
.RE
.PP
RLINK (Optional)
.RS 4
This directive, which may be repeated, is used to determine whether the current request includes an
\m[blue]\fBRlink\fR\m[]\&\s-2\u[154]\d\s+2\&. The
RLINK
directives are processed in the order in which they occur\&. The value of the directive is a space\-separated pair: the first is an
\m[blue]\fBexpression\fR\m[]\&\s-2\u[20]\d\s+2
that is evaluated at rule\-processing time, and the second is a
\m[blue]\fBVFS specification\fR\m[]\&\s-2\u[155]\d\s+2
for the location of the Rlinks (i\&.e\&., a
\fBDACS\fR
URI, an item type, or an absolute pathname)\&. If the expression evaluates to a non\-empty string:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
the string is assumed to be an
\m[blue]\fBRname\fR\m[]\&\s-2\u[154]\d\s+2, which is relative to the VFS specification,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Rlink processing is enabled for the current request, and
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
no other
RLINK
directives are considered or evaluated\&.
.RE
.sp
If the expression evaluates to the empty string or an error occurs, the directive is ignored and the next one, if any, is processed\&. Example:
.sp
.if n \{\
.RS 4
.\}
.nf
RLINK \*(Aq"${Args::RNAME:?}" /usr/local/dacs/rlinks\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
In the example above, the directive specifies that if the current request includes a non\-empty argument called
\fIRNAME\fR, then its value is an Rname, Rlink processing is enabled, and the Rlink can be found in the
/usr/local/dacs/rlinks
directory\&.
.RE
.PP
ROLE_STRING_MAX_LENGTH (Optional1)
.RS 4
A limit is imposed on the length of the role string returned by any authentication or roles service, the length of any intermediate role string formed by concatenation during determination of the role string, and the length of the final role string, which is used in credentials\&. A string that exceeds the limit is invalid and treated as an empty string\&. The limit is necessary because credentials (which may contain a role string) are encapsulated within an HTTP cookie and browsers have context\-dependent and implementation\-dependent restrictions on cookie lengths\&. This directive is used to set the limit, overriding a compile\-time value of 200 bytes\&. Please refer to
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[50]\d\s+2
for additional information about roles\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBWarning\fR
.ps -1
.br
A role string that is too long may cause the user to experience strange and possibly incorrect behaviour from
\fBDACS\fR
because the browser may discard cookies produced by
\fBDACS\fR\&.
.sp .5v
.RE
.RE
.PP
SECURE_MODE (Optional1)
.RS 4
This directive causes
\fBDACS\fR
to operate "insecurely" only if its value is "no" or "off" (case insensitive), otherwise
\fBDACS\fR
will use a more secure mode of operation\&. In secure mode,
\fBDACS\fR
requires all user interactions to be through SSL/TLS (HTTPS) and cookies will have the
secure
attribute\&. The default is "yes"\&. Odd behaviour may result if interactions between
\fBDACS\fR
and a particular client mix
http
and
https
requests (such as when handlers are involved)\&.
.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
Always use the secure mode of operation unless you fully understand the consequences of disabling it\&. For
\fBDACS\fR
to be a secure system, secure mode should be disabled only for testing purposes or if all HTTP traffic is protected by some secure means other than SSL/TLS\&.
.sp .5v
.RE
.RE
.PP
SIGNOUT_HANDLER (Optional1)
.RS 4
When
\m[blue]\fBdacs_signout(8)\fR\m[]\&\s-2\u[33]\d\s+2
terminates, provided a fatal error was not encountered, the subsequent action can be customized using this directive\&. For instance, the system administrator can ask for the user\*(Aqs browser to be redirected to a login page\&. This capability can also be used to construct a chain of requests to signout a user from multiple federations\&.
.sp
The following syntaxes are supported:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
SIGNOUT_HANDLER "[url] \fIURL\fR"
.sp
This form will cause
\fBDACS\fR
to redirect the client to the specified URL, which may be a relative or absolute URL\&. If the keyword
url
is absent,
\fIURL\fR
must begin with the four characters
http\&. Whether the
GET
method is used depends on the context of the original request\&. The URL may contain a properly escaped query string;
\fBDACS\fR
will append the following parameters, URL encoded and in the order given:
.PP
\fIDACS_VERSION\fR
.RS 4
The version number of
\fBDACS\fR
(e\&.g\&., "1\&.4")\&.
.RE
.PP
\fIDACS_FEDERATION\fR
.RS 4
The federation that received the service request, if available\&.
.RE
.PP
\fIDACS_JURISDICTION\fR
.RS 4
The jurisdiction that received the service request, if available\&.
.RE
.PP
\fIDACS_SIGNOUT_RESULT\fR
.RS 4
The number of credentials (a non\-negative integer) that
\m[blue]\fBdacs_signout(8)\fR\m[]\&\s-2\u[33]\d\s+2
asked the web browser to delete by setting expired HTTP cookies\&. Note that the total number of HTTP cookies set by
\m[blue]\fBdacs_signout(8)\fR\m[]\&\s-2\u[33]\d\s+2
could be greater than this number\&.
.RE
.sp
The following directive will redirect the user\*(Aqs browser to a relative URL:
.sp
.if n \{\
.RS 4
.\}
.nf
SIGNOUT_HANDLER "url /dacs/handlers/signout_ok\&.html?FOO=bar"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
SIGNOUT_HANDLER "defaulturl \fIURL\fR"
.sp
This form is like that of the
url
syntax except that a URL given by a
\fIDACS_SIGNOUT_HANDLER\fR
parameter will be used if it is passed to
\m[blue]\fBdacs_signout(8)\fR\m[]\&\s-2\u[33]\d\s+2\&. A
\fIDACS_SIGNOUT_HANDLER\fR
parameter is ignored in the other forms of the
SIGNOUT_HANDLER
directive\&. If that parameter is absent, the URL specified by this directive is used\&. As in the
url
form,
\fBDACS\fR
will append parameters to the
\fIDACS_SIGNOUT_HANDLER\fR
URL\&. Note that the
defaulturl
keyword is not optional\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
SIGNOUT_HANDLER "[file] \fIfull\-pathname\fR"
.sp
This form causes the contents of the file named by
\fIfull\-pathname\fR
to be returned\&. The file must include any header lines it requires, such as a
Content\-Type
line, a header\-terminating blank line, and then the document content\&.
.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 "full\-pathname" usage differs from the "local\-URL" usage of the
ACS_ERROR_HANDLER
directive, though both elements begin with a slash character; the former specifies the absolute pathname of a file, while the latter specifies a URL local to the receiving web server\&. To specify a relative URL, use the
url
keyword\&.
.sp .5v
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
SIGNOUT_HANDLER "[message] \e"\fImessage\fR\e""
.sp
This form causes the given message, surrounded by escaped double quote characters, to be returned as HTML\&.
.sp
.if n \{\
.RS 4
.\}
.nf
SIGNOUT_HANDLER "message \e"You\*(Aqre outta here!\e""
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
SIGNOUT_HANDLER "credentials"
.sp
This form causes the user\*(Aqs remaining credentials to be displayed as an HTML document\&. This is the default behaviour\&.
.RE
.sp
The optional keywords are treated case\-insensitively\&.
.RE
.PP
SSL_PROG (Optional1)
.RS 4
The full pathname of the command used to provide an SSL/TLS connection for group information distribution\&. Currently, only
\m[blue]\fBsslclient(1)\fR\m[]\&\s-2\u[156]\d\s+2
is supported for this purpose\&.
.RE
.PP
SSL_PROG_ARGS (Optional1)
.RS 4
Additional command line arguments to be passed to
SSL_PROG\&.
.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
This directive is "global" in that it applies to all internal invocations of
SSL_PROG\&. SSL/TLS options should probably be more flexibly configurable (e\&.g\&., from within
Auth
and
Roles
clauses)\&.
.sp .5v
.RE
.RE
.PP
SSL_PROG_CA_CRT (Optional1)
.RS 4
The full pathname of the file containing the CA certificate shared by this
\fBDACS\fR
federation\&. This is passed to
SSL_PROG
so that certificates can be validated\&.
.RE
.PP
SSL_PROG_CLIENT_CRT (Optional1)
.RS 4
This provides the name of a private key and certificate chain PEM file\&. Please refer to
\m[blue]\fBsslclient(1)\*(Aqs\fR\m[]\&\s-2\u[156]\d\s+2
\fB\-ccf\fR
flag\&.
.RE
.PP
STATUS_LINE (Optional1)
.RS 4
If this directive is set to "on",
\m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[6]\d\s+2
will emit a
\m[blue]\fBDACS\-Status\-Line\fR\m[]\&\s-2\u[157]\d\s+2
header in the response from the server\&. The default value is "off"\&. See the description of the
\m[blue]\fBDACS_ACS argument\fR\m[]\&\s-2\u[51]\d\s+2
for additional details\&.
.RE
.PP
TEMP_DIRECTORY (Optional1)
.RS 4
A directory where
\fBDACS\fR
can create temporary files\&. If the value is not an absolute path, the location is relative to
\m[blue]\fBDACS_HOME\fR\m[]\&\s-2\u[158]\d\s+2\&. Lock files, for example, are put in this directory\&. If not configured or if this directory does not exist, a compile\-time path (DEFAULT_TEMP_DIRECTORY) is used (currently:
/tmp)\&. It is always safe to delete the contents of this directory if
\fBDACS\fR
is not running\&. Read and write access to this directory must be restricted to
\fBDACS\fR\&.
.RE
.PP
TOKEN_REQUIRES_PIN (Optional1)
.RS 4
If set to
no, then
\m[blue]\fBdacstoken(1)\fR\m[]\&\s-2\u[138]\d\s+2
does not require created or imported accounts to have a
PIN\&. The default value is
yes, and a
PIN
is required\&.
.RE
.PP
TOKEN_HOTP_ACCEPT_WINDOW (Optional1)
.RS 4
When validating or authenticating against a given one\-time password, this is the maximum number of successive counter values to consider, if necessary, after the expected counter value\&. A value of zero disables this search\&. If not configured, a compile\-time value is used (currently,
3)\&.
.RE
.PP
TRACE_LEVEL (Optional1)
.RS 4
If assigned a non\-zero value, tracing is enabled in various
\fBDACS\fR
services\&. Larger values will cause more events to be traced\&. This is intended to give an indication of the steps a
\fBDACS\fR
service takes during execution for debugging purposes\&. Logging information is generally written to the web server\*(Aqs log file or to a file configured into
\fBDACS\fR
at compile time\&. Also see
LOG_LEVEL
and
VERBOSE_LEVEL\&.
.RE
.PP
UNAUTH_ROLES (Optional1)
.RS 4
This directive is used to assign a
\m[blue]\fBrole descriptor string\fR\m[]\&\s-2\u[159]\d\s+2
to
\fIunauthenticated\fR
users\&. Association with these roles can be tested using the
\m[blue]\fBuser()\fR\m[]\&\s-2\u[160]\d\s+2
predicate\&.
.sp
If a jurisdiction configures this directive:
.sp
.if n \{\
.RS 4
.\}
.nf
UNAUTH_ROLES "anonymous"
.fi
.if n \{\
.RE
.\}
.sp
then the following predicates would both return
\fBTrue\fR
when applied to an unauthenticated user:
.sp
.if n \{\
.RS 4
.\}
.nf
user("unauth")
user("%:anonymous")
.fi
.if n \{\
.RE
.\}
.sp
A useful application of this directive is to classify unauthenticated users based on contextual elements\&. Consider this directive:
.sp
.if n \{\
.RS 4
.\}
.nf
UNAUTH_ROLES from("10\&.0\&.0\&.0/24") ? "user" : ""
.fi
.if n \{\
.RE
.\}
.sp
If an unauthenticated user submits a request from a local IP address between
10\&.0\&.0\&.0
and
10\&.0\&.0\&.255, the user would be treated as having the role
user, otherwise the user would have no roles\&. This might be used to conveniently grant limited access to "local" users without them having to authenticate\&. A rule could be written to grant access based on having the role
user, for example, without needing to consider whether or not the user has authenticated\&.
.sp
Unlike roles assigned to credentials, roles specified in this way are strictly local to the jurisdiction that configures them\&. Some form of coordination is required if different jurisdictions need to assign the same roles to unauthenticated users\&. These roles are not reported by
\m[blue]\fBdacs_current_credentials(8)\fR\m[]\&\s-2\u[92]\d\s+2\&.
.RE
.PP
UPROXY_APPROVED (Stack)
.RS 4
This directive is used by
\m[blue]\fBdacs_uproxy(8)\fR\m[]\&\s-2\u[161]\d\s+2
to enable proxying to one or more hosts and to configure each of those mappings\&. Each directive specifies a member of the "approved list" (i\&.e\&., a host that may be proxied) using the following syntax:
.sp
.if n \{\
.RS 4
.\}
.nf
[{\*(Aqhttp\*(Aq | \*(Aqhttps\*(Aq} \*(Aq://\*(Aq] \fIhostname\fR [:\fIport\fR] [\fIpath\fR]
.fi
.if n \{\
.RE
.\}
.sp
\fBdacs_uproxy\fR
is invoked with a URI with the following syntax:
.sp
.if n \{\
.RS 4
.\}
.nf
\&.\&.\&./dacs_uproxy/\fIproxied\-hostname\fR[:\fIproxied\-port\fR][\fIproxied\-path\-prefix\fR]
.fi
.if n \{\
.RE
.\}
.sp
A
\fIproxied\-hostname\fR
is matched against the
\fIhostname\fR
of each entry in the list, according to the stacked directive ordering, until a (case insensitive) match is found\&. If the
\fIproxied\-hostname\fR
is followed by a port number, that port number must be explicitly specified in a directive for a match to occur\&. If no scheme is specified,
http
is used, regardless of what protocol the
\fIport\fR
may imply\&. If a
\fIpath\fR
is given, it is appended to the
\fIproxied\-path\-prefix\fR\&.
.sp
For example, consider the directives:
.sp
.if n \{\
.RS 4
.\}
.nf
UPROXY_APPROVED "example\&.com"
UPROXY_APPROVED "https://foo\&.example\&.com"
UPROXY_APPROVED "http://bar\&.example\&.com:8080"
UPROXY_APPROVED "https://baz\&.example\&.com:8443/some/path"
.fi
.if n \{\
.RE
.\}
.sp
A request for the proxied hostname
foo\&.example\&.com, such as this:
.sp
.if n \{\
.RS 4
.\}
.nf
\&.\&.\&./dacs_uproxy/foo\&.example\&.com/a/b/c\&.cgi
.fi
.if n \{\
.RE
.\}
.sp
will be forwarded by
\fBdacs_uproxy\fR
as the URI:
.sp
.if n \{\
.RS 4
.\}
.nf
https://foo\&.example\&.com/a/b/c\&.cgi
.fi
.if n \{\
.RE
.\}
.sp
And the proxied request:
.sp
.if n \{\
.RS 4
.\}
.nf
\&.\&.\&./dacs_uproxy/baz\&.example\&.com/a/b/c\&.cgi
.fi
.if n \{\
.RE
.\}
.sp
will be forwarded by
\fBdacs_uproxy\fR
as the URI:
.sp
.if n \{\
.RS 4
.\}
.nf
https://baz\&.example\&.com:8443/some/path/a/b/c\&.cgi
.fi
.if n \{\
.RE
.\}
.sp
This request would fail because there is no approved entry for
bar\&.example\&.com:80:
.sp
.if n \{\
.RS 4
.\}
.nf
\&.\&.\&./dacs_uproxy/bar\&.example\&.com:80/a/b/c\&.cgi
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
VERBOSE_LEVEL (Optional1)
.RS 4
If assigned a non\-zero value, debugging output is enabled in various
\fBDACS\fR
services\&. Larger values will cause more output to be generated\&. This is intended to display input arguments and the values of variables as a
\fBDACS\fR
service is executed, for debugging purposes\&. Logging information is generally written to the web server\*(Aqs log file or to a file configured into
\fBDACS\fR
at compile time\&. Also see
LOG_LEVEL
and
TRACE_LEVEL\&.
.RE
.PP
VERIFY_IP (Required1)
.RS 4
If "yes", then the IP address in credentials must exactly match the IP address from which a service request is made\&. For example, if
\fBDACS\fR
issued credentials in response to an authentication request that came from the IP address
10\&.0\&.0\&.123, then these credentials will only be considered valid for service requests that come from that IP address\&. If the directive\*(Aqs value is "no", this verification is not performed\&. Any other value is assumed to be a valid argument to the
\m[blue]\fBfrom()\fR\m[]\&\s-2\u[162]\d\s+2
predicate:
.sp
.if n \{\
.RS 4
.\}
.nf
# Only credentials that were issued to an address on this subnet
# are acceptable
VERIFY_IP "10\&.0\&.0\&.0/24"
.fi
.if n \{\
.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
\fBTip\fR
.ps -1
.br
Verification might be turned off, for example, in an environment where a user might legitimately submit service requests associated with different IP addresses\&. Refer to
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[62]\d\s+2
for additional information\&.
.sp .5v
.RE
.RE
.PP
VERIFY_UA (Optional1)
.RS 4
If "yes", then the user agent string presented when authentication occurred (the
USER\-AGENT
request header, exported by
\fBApache\fR
as
\fBHTTP_USER_AGENT\fR) must match the user agent string that is sent with subsequent requests using those credentials\&. This is the default\&. If the directive\*(Aqs value is "no", this verification is not performed at this jurisdiction but credentials it produces can still be verified by other jurisdictions\&. If the directive\*(Aqs value is "disable", the feature is totally disabled at this jurisdiction\&. The feature is always disabled for certain internally\-generated credentials\&.
.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
In typical use of
\fBDACS\fR, this feature should be enabled because it makes it somewhat more difficult for misappropriated
\fBDACS\fR
credentials to be used\&. It is not a foolproof measure, however, because a sophisticated attacker may be able to obtain or guess a user agent string and use it with stolen credentials, although guesses may draw attention by causing log messages to be emitted\&.
.sp
Some user agents, including
\m[blue]\fBdacshttp(1)\fR\m[]\&\s-2\u[4]\d\s+2,
\fBMozilla\fR,
\fBFirefox\fR,
\fBcurl\fR,
\fBwget\fR, and
\fBKonqueror\fR, allow the user agent string to be set\&. Including a random or unusual component in the string will strengthen this feature\&. Also, middleware may be able to take advantage of its ability to send a string of its choosing in the
User\-Agent
header field\&.
.sp
Verification might be turned off, for example, in proxying situations or if credentials are cached by middleware and then legitimately used with different user agents\&. The feature should be disabled for backward compatibility with releases earlier than
\fBDACS\fR
1\&.4\&.14\&.
.sp .5v
.RE
.RE
.PP
VFS (Stack)
.RS 4
These directives are used to configure the virtual filestore (VFS) subsystem (see
\m[blue]\fBdacs\&.vfs(5)\fR\m[]\&\s-2\u[163]\d\s+2
and
\m[blue]\fBdacsvfs(1)\fR\m[]\&\s-2\u[164]\d\s+2
for details)\&.
.sp
The value of this directive (a
vfs_uri) has the following syntax:
.sp
.if n \{\
.RS 4
.\}
.nf
vfs_uri \-> [ \*(Aq[\*(Aq \fIitem_type\fR \*(Aq]\*(Aq ] \fIURI\fR
.fi
.if n \{\
.RE
.\}
.sp
As specified in
\m[blue]\fBRFC 2396\fR\m[]\&\s-2\u[104]\d\s+2
and
\m[blue]\fBRFC 3986\fR\m[]\&\s-2\u[165]\d\s+2, the general form of the URI syntax is:
.sp
.if n \{\
.RS 4
.\}
.nf
\fIscheme\fR : [ // \fIauthority\fR] [\fIpath\fR] [\fIquery\fR] [\fIfragment\fR]
.fi
.if n \{\
.RE
.\}
.sp
The
\fIitem_type\fR
(see
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[166]\d\s+2) is optional in some cases \- it can usually be omitted if the directive will not be referenced and if it does not refer to an indexed object\&. It is a case\-sensitive label that associates this directive with a class of objects used by
\fBDACS\fR\&. Some labels are reserved and have predefined meaning to
\fBDACS\fR; these are always lowercase;
\m[blue]\fBdacsconf(1)\fR\m[]\&\s-2\u[2]\d\s+2
can list them\&. Any label can be defined by a
\fBDACS\fR
administrator, but a reserved item type should only be defined for its intended use; user\-defined item types should therefore include at least one uppercase letter\&. For example, here are a few reserved item types:
passwds
(used by
\m[blue]\fBdacspasswd(1)\fR\m[]\&\s-2\u[137]\d\s+2
and others),
federation_keys
and
jurisdiction_keys
(used by
\m[blue]\fBdacskey(1)\fR\m[]\&\s-2\u[167]\d\s+2
and others),
revocations
(used by
\m[blue]\fBdacs\&.acls(5)\fR\m[]\&\s-2\u[25]\d\s+2
and others), and
stdin
(used by
\m[blue]\fBget()\fR\m[]\&\s-2\u[168]\d\s+2
and others)\&.
.sp
Although the
\fIscheme\fR
is case\-insensitive, the canonical form is lowercase\&. The
\fIauthority\fR,
\fIquery\fR, and
\fIfragment\fR
URI components are often absent\&. The
\fIquery\fR
component is used to specify options\&.
.sp
The
\fIpath\fR
component of a URI has the format:
.sp
.if n \{\
.RS 4
.\}
.nf
[ \fInaming_context\fR ] [ "," \fIrel\-path\fR ]
.fi
.if n \{\
.RE
.\}
.sp
For paths that have a separate key relative to the naming context, its start is delimited by a comma\&.
.sp
The
\fIscheme\fR
may be:
.PP
dacs\-db
.RS 4
A
\m[blue]\fBBerkeley DB\fR\m[]\&\s-2\u[169]\d\s+2, a hash\-based database that manages a collection of objects within a regular file\&. The
\fIitem_type\fR
is required because it forms the initial part of the key\&.
.RE
.PP
dacs\-ndbm
.RS 4
The Unix
\m[blue]\fBdbm(3)\fR\m[]\&\s-2\u[170]\d\s+2
API (includes
\m[blue]\fBGNU gdbm\fR\m[]\&\s-2\u[171]\d\s+2), which is similar to
dacs\-db\&. The
\fIitem_type\fR
is required because it forms the initial part of the key\&.
.RE
.PP
dacs\-fs
.br
fs
.br
file
.RS 4
Files and directories managed through filesystem operations\&. Where
\fIpath\fR
names a directory, each key maps to a regular file within that directory\&.
.RE
.PP
dacs\-sqlite
.RS 4
An
\m[blue]\fBSQLite\fR\m[]\&\s-2\u[172]\d\s+2
database that manages a collection of objects within a regular file\&. The
\fIitem_type\fR
is required because it is used as the SQL table name\&.
.RE
.PP
http
.br
https
.RS 4
HTTP\-based object access\&. For example,
example\&.com
might configure access to its revocation list like this (with appropriate access controls):
.sp
.if n \{\
.RS 4
.\}
.nf
VFS "[revocations]https://example\&.com/dacs/revocation_list"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
dacs\-kwv
.RS 4
A keyword\-value organization that is managed within a single object associated with another item type\&. In other words, it says that another object, configured with its own
VFS
directive, has an internal structure where each line of the object represents one record\&. Each record consists of a keyword, followed by a separator character, and the value associated with the keyword\&. A keyword consists of a sequence of printable, non\-whitespace characters\&. By default, the separator character is a colon\&. (A well\-known example of a file having this format is
/etc/password\&.) To specify a different separator, the
vfs_uri
should include the query argument
\fIfield_sep\fR
whose value is the separator character to use\&. The
\fIpath\fR
component gives the name of the
item_type
that should be used to manage the underlying objects\&.
.sp
For example, components of
\fBDACS\fR
expect the
passwds
item type to be defined\&. Taken together, the following pair of directives specify that the plain file
/usr/local/dacs/passwd
consists of keyword\-value pairs:
.sp
.if n \{\
.RS 4
.\}
.nf
VFS "[password_file]dacs\-fs:/usr/local/dacs/passwd"
VFS "[passwds]dacs\-kwv:password_file"
.fi
.if n \{\
.RE
.\}
.sp
To specify a space as the separator character instead of the colon (which is the default), use the directives:
.sp
.if n \{\
.RS 4
.\}
.nf
VFS "[password_file]dacs\-fs:/usr/local/dacs/passwd"
VFS "[passwds]dacs\-kwv:password_file?field_sep=+"
.fi
.if n \{\
.RE
.\}
.sp
Because these are URIs, they must be properly encoded and the \*(Aq+\*(Aq character represents a space\&. If the passwords are to be stored in a Berkeley DB database, the directive would be:
.sp
.if n \{\
.RS 4
.\}
.nf
VFS "[passwds]dacs\-db:/usr/local/dacs/passwd\&.db"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
dacs\-kwv\-\fIsubscheme\fR
.RS 4
A concise way of composing the
dacs\-kwv
scheme with underlying objects accessed using
\fIsubscheme\fR\&. Currently,
\fIsubscheme\fR
can be
fs
(for
dacs\-fs),
http, or
https\&. For
fs, the
\fIpath\fR
component is the absolute pathname of a file, its contents having the keyword\-value organization\&. For
http
and
https, the
\fIpath\fR
component is the remainder of the URL (i\&.e\&., the scheme that specifies the object is implied), which will be retrieved using the
GET
method, stored and replaced using the
PUT
method, deleted using the
DELETE
method, and tested for using the
HEAD
method\&. Note that any options (i\&.e\&., a query string) bind to
\fIsubscheme\fR; if options for
dacs\-kwv
are needed, two separate URIs must be used instead of this method\&.
.sp
This configuration directive is almost equivalent to the pair of directives described in the example above:
.sp
.if n \{\
.RS 4
.\}
.nf
VFS "[passwds]dacs\-kwv\-fs:/usr/local/dacs/passwd"
.fi
.if n \{\
.RE
.\}
.sp
The following configuration directive states that the password file used by
\m[blue]\fBdacspasswd(1)\fR\m[]\&\s-2\u[137]\d\s+2
is to be accessed at the URL
https://example\&.com/dacs/passwds
using the standard HTTP methods:
.sp
.if n \{\
.RS 4
.\}
.nf
VFS "[passwds]dacs\-kwv\-https://example\&.com/dacs/passwds"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
dacs\-vfs
.RS 4
The
\fBDACS\fR
CGI\-based VFS service,
\m[blue]\fBdacs_vfs(8)\fR\m[]\&\s-2\u[173]\d\s+2, which exports VFS operations on VFS objects through a web service\&. An item type must be provided and must be configured at the specified
\fBDACS\fR
jurisdiction using any of the supported store types (which means the
dacs\-vfs
scheme can be used to access items stored in a remote regular file, hash\-based database, and so on)\&.
.sp
For example, this directive causes
\fBDACS\fR
to look for password entries used by
\m[blue]\fBlocal_passwd_authenticate\fR\m[]\&\s-2\u[174]\d\s+2
to be accessed through the virtual filestore at
example\&.com:
.sp
.if n \{\
.RS 4
.\}
.nf
VFS "[passwds]dacs\-vfs:https://example\&.com/cgi\-bin/dacs/dacs_vfs"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
A
vfs\-ref
is a reference to a virtual filestore definition and can be a
vfs_uri
or an
item_type
defined by a
VFS
directive\&. In some situations it can also be an absolute pathname\&.
.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
At present, the VFS does not implement much in the way of concurrency control\&. Some
\fBDACS\fR
components use coarse\-grained locking to ensure that only a single user can access resources, however, and databases may implement their own concurrency control\&. Only a few of these resources are not used in a read\-only fashion; administrators should adopt appropriate data management practices for them to ensure concurrent updates cannot occur\&.
.sp .5v
.RE
.RE
.PP
XSD_BASE_URL (Optional1)
.RS 4
When
\fBDACS\fR
services are asked to send an XML Schema response (i\&.e\&., they are passed the argument
FORMAT=XMLSCHEMA) and this directive is configured, services will emit
xmlns:xsi
and
xsi:schemaLocation
attributes, the former having a compile\-time value (e\&.g\&.,
http://www\&.w3\&.org/2001/XMLSchema\-instance) and the latter being a pair, the first having the same value as the value of the
xmlns
attribute and the second having a value derived from the
XSD_BASE_URL
directive; e\&.g\&.,
.sp
.if n \{\
.RS 4
.\}
.nf
.fi
.if n \{\
.RE
.\}
.sp
If
XSD_BASE_URL
is not configured, only the default
xmlns
attribute is emitted\&.
.RE
.RE
.SS "The Auth Clause"
.PP
Each
Auth
clause configures an authentication module\&. The
Auth
clause and its directives are described in
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[27]\d\s+2\&.
.PP
Note that the order of these clauses is significant \- they are processed in the order in which they appear in the applicable configuration section\&.
.SS "The Roles Clause"
.PP
Each
Roles
clause configures a roles module\&.
Roles
clause and its directives are described in
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[175]\d\s+2\&.
.PP
The clauses are processed in the order in which they appear\&. Authentication modules may return roles, to improve efficiency, but roles are usually obtained through a roles module\&. Roles modules are processed only if authentication is successful\&.
.SS "The Transfer Clause"
.PP
Each
Transfer
clause configures
\m[blue]\fBdacs_auth_transfer(8)\fR\m[]\&\s-2\u[29]\d\s+2
for importing from one or more federations specified within the clause\&. The clauses are processed in the order in which they appear\&. No clause should apply to more than one initial federation, although this is not enforced\&.
.PP
Each
Transfer
element has an
id
attribute\&. Its value is merely a label (an alphabetic followed by zero or more alphanumerics, hyphens, and underscores) that allows the clause to be referenced; the syntax is the same as that of a
\m[blue]\fBgroupname\fR\m[]\&\s-2\u[80]\d\s+2\&. The attribute values must be unique (case\-sensitively)\&.
Transfer
clause directives are described in
\m[blue]\fBdacs_auth_transfer(8)\fR\m[]\&\s-2\u[29]\d\s+2\&.
.SS "Advanced Techniques"
.PP
Configuration processing is ordinarily quite straightforward, but to accommodate more complicated situations it also supports a few advanced techniques\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBConfiguration Variables\fR
.RS 4
.PP
After configuration processing determines which directives have been overridden, those that are in effect have their right hand sides (which are expressions) evaluated\&. These expressions are usually simple strings but they can be any
\fBDACS\fR
expression\&.
.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
When configuration processing begins, variables in the
\fIDACS\fR
and
\fIArgs\fR
\m[blue]\fBnamespaces\fR\m[]\&\s-2\u[14]\d\s+2
can by referenced by configuration directives\&.
.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
\fBSecurity\fR
.ps -1
.br
.PP
The ability to reference an argument during configuration processing can be useful and powerful when used carefully but since argument values are completely in the hands of the user constructing a request, it is a potential security weakness, particularly in
\fBDACS\fR
deployments that are exposed to the Internet\&.
.PP
For example, an argument might be missing or duplicated, accidentally have a problematic value (such as containing non\-printable or otherwise invalid characters), or be specifically constructed in an attempt to misconfigure
\fBDACS\fR
to thwart security\&. For this reason, variables in the
\fIArgs\fR
namespace should be referenced in configuration files only when specifically indicated in the documentation, or by advanced
\fBDACS\fR
administrators in appropriate circumstances and with caution\&.
.sp .5v
.RE
.PP
As each expression is evaluated to determine the value of the directive, a variable in the
\fIConf\fR
namespace (see
\m[blue]\fBdacs\&.exprs(5)\fR\m[]\&\s-2\u[14]\d\s+2) is created and assigned the value, and can then be referenced in subsequent expressions\&. Variables in this namespace can be referenced within access control rules, permitting rules to be written that depend on how the particular site, federation, and jurisdiction have been configured\&. In addition, during the remainder of the configuration processing stage, the variable\*(Aqs value can be modified, effectively changing the value associated with the directive\&. After completion of configuration processing, the variables in the
\fIConf\fR
namespace become read\-only\&. It is these variables that are displayed by the
\fB\-vars\fR
option of
\m[blue]\fBdacsconf(1)\fR\m[]\&\s-2\u[2]\d\s+2\&.
.PP
For example, if the directive
.sp
.if n \{\
.RS 4
.\}
.nf
FEDERATION_DOMAIN "example\&.com"
.fi
.if n \{\
.RE
.\}
.sp
is in effect when directive evaluation begins, the variable
\fI${Conf::FEDERATION_DOMAIN}\fR
will be created and assigned the value "example\&.com"\&.
.PP
Variables within the
\fIConf\fR
\m[blue]\fBnamespace\fR\m[]\&\s-2\u[14]\d\s+2
can be created as needed within expressions (using the
EVAL
directive, for example)\&. Care should be taken not to unintentionally modify the value of a
\fBDACS\fR
directive, however\&.
.PP
A standard set of variables is always instantiated when available:
.PP
\fIAPACHE_HOME\fR
.RS 4
The value of the corresponding build\-time symbol
.RE
.PP
\fICGI_SUFFIX\fR
.RS 4
The file name extension for CGI executables, specified at build\-time
.RE
.PP
\fIDACS_CONF\fR
.RS 4
The full pathname for this jurisdiction\*(Aqs
dacs\&.conf
file
.RE
.PP
\fIDACS_CONF_SPEC\fR
.RS 4
The pathname specification template used for this jurisdiction\*(Aqs
dacs\&.conf
file
.RE
.PP
\fIDACS_HOME\fR
.RS 4
The value of the corresponding build\-time symbol, from the path set by the
\fB\-\-prefix\fR
flag or defaulting to
/usr/local/dacs
.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
This directory should be writable only by an administrator\&.
.sp .5v
.RE
.RE
.PP
\fIDACS_CGIBINDIR\fR
.RS 4
The value of the corresponding build\-time symbol
.RE
.PP
\fIDACS_RELEASE\fR
.RS 4
The value of the the compile\-time symbol
DACS_VERSION_RELEASE
.RE
.PP
\fIDACS_BINDIR\fR
.RS 4
The location of the
\fBDACS\fR
bin
directory
.RE
.PP
\fIDACS_SBINDIR\fR
.RS 4
The location of the
\fBDACS\fR
sbin
directory
.RE
.PP
\fIDACS_SITE_CONF\fR
.RS 4
The full pathname for this jurisdiction\*(Aqs
site\&.conf
file
, if any
.RE
.PP
\fIDACS_SITE_CONF_SPEC\fR
.RS 4
The pathname specification template used for this jurisdiction\*(Aqs
site\&.conf
file, if any
.RE
.PP
\fIDACS_VERSION\fR
.RS 4
The value of the compile\-time symbol
DACS_VERSION_NUMBER
.RE
.PP
\fIDOCUMENT_ROOT\fR
.RS 4
\fBApache\fR\*(Aqs
\fBDOCUMENT_ROOT\fR
environment variable
.RE
.PP
\fIEXE_SUFFIX\fR
.RS 4
The file name extension for non\-CGI executables
.RE
.PP
\fIFEDERATIONS_ROOT\fR
.RS 4
The value of the corresponding build\-time symbol
.RE
.PP
\fIHTTP_HOST\fR
.RS 4
\fBApache\fR\*(Aqs
\fBHTTP_HOST\fR
environment variable, obtained from the HTTP
Host
request header
.RE
.PP
\fIJURISDICTION_URI\fR
.RS 4
The initial part of the request URI, including scheme and port number, that uniquely identifies the jurisdiction receiving the service request (also see
\fIJURISDICTION_URI_PREFIX\fR)
.RE
.PP
\fIJURISDICTION_URI_PREFIX\fR
.RS 4
The URI prefix that uniquely identifies the jurisdiction receiving the service request (also see
\fIJURISDICTION_URI\fR)
.RE
.PP
\fIOPENSSL_PROG\fR
.RS 4
The full pathname of the
\fBopenssl\fR
command, if available
.RE
.PP
\fISERVER_ADDR\fR
.RS 4
\fBApache\fR\*(Aqs
\fBSERVER_ADDR\fR
environment variable
.RE
.PP
\fISERVER_NAME\fR
.RS 4
\fBApache\fR\*(Aqs
\fBSERVER_NAME\fR
environment variable
.RE
.PP
\fISERVER_PORT\fR
.RS 4
\fBApache\fR\*(Aqs
\fBSERVER_PORT\fR
environment variable
.RE
.PP
\fIURI_SCHEME\fR
.RS 4
Set to
https
if the service request came over SSL/TLS (\fBHTTPS\fR
== "on"), otherwise
http
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAuthentication and Roles\fR
.RS 4
.PP
This section unfortunately left blank\&.
.RE
.SH "SEE ALSO"
.PP
\m[blue]\fBdacsconf(1)\fR\m[]\&\s-2\u[2]\d\s+2,
\m[blue]\fBdacs_conf(8)\fR\m[]\&\s-2\u[3]\d\s+2,
\m[blue]\fBdacs\&.exprs(5)\fR\m[]\&\s-2\u[20]\d\s+2
.SH "BUGS"
.PP
There\*(Aqs no way to turn off inherited defaults in a jurisdiction section or
Default
section; i\&.e\&., one cannot turn off all
Auth
or handler directives for just one jurisdiction section\&.
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fB\%http://www.dss.ca\fR\m[])
.SH "COPYING"
.PP
Copyright \(co 2003\-2018 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[176]\d\s+2
file that accompanies the distribution for licensing information\&.
.SH "NOTES"
.IP " 1." 4
dacs(1)
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#key_concepts
.RE
.IP " 2." 4
dacsconf(1)
.RS 4
\%http://dacs.dss.ca/man/dacsconf.1.html
.RE
.IP " 3." 4
dacs_conf(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_conf.8.html
.RE
.IP " 4." 4
dacshttp(1)
.RS 4
\%http://dacs.dss.ca/man/dacshttp.1.html
.RE
.IP " 5." 4
dacs(1)
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#dacsoptions
.RE
.IP " 6." 4
dacs_acs(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html
.RE
.IP " 7." 4
mod_auth_dacs
.RS 4
\%http://dacs.dss.ca/man/mod_auth_dacs.html
.RE
.IP " 8." 4
\fBmod_vhost_alias\fR
.RS 4
\%http://httpd.apache.org/docs-2.4/mod/mod_vhost_alias.html
.RE
.IP " 9." 4
LOG_FILE
.RS 4
\%http://dacs.dss.ca/man/#LOG_FILE
.RE
.IP "10." 4
pathname()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#pathname
.RE
.IP "11." 4
Jurisdiction section's
.RS 4
\%http://dacs.dss.ca/man/#jurisdiction_section
.RE
.IP "12." 4
Configuration.dtd
.RS 4
\%http://dacs.dss.ca/man/../dtd-xsd/Configuration.dtd
.RE
.IP "13." 4
Stack
category
.RS 4
\%http://dacs.dss.ca/man/#directive_categories
.RE
.IP "14." 4
namespace
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#variables
.RE
.IP "15." 4
EVAL directive
.RS 4
\%http://dacs.dss.ca/man/#EVAL
.RE
.IP "16." 4
undef()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#undef
.RE
.IP "17." 4
modifier flag
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#variable_modifiers
.RE
.IP "18." 4
ACS_ERROR_HANDLER
.RS 4
\%http://dacs.dss.ca/man/#ACS_ERROR_HANDLER
.RE
.IP "19." 4
effective jurisdictional URIs
.RS 4
\%http://dacs.dss.ca/man/#jurisdiction_section_uri
.RE
.IP "20." 4
expression
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html
.RE
.IP "21." 4
configuration variables
.RS 4
\%http://dacs.dss.ca/man/#config-vars
.RE
.IP "22." 4
example configuration
.RS 4
\%http://dacs.dss.ca/man/#example_dacs.conf
.RE
.IP "23." 4
Jurisdiction Selection by URI
.RS 4
\%http://dacs.dss.ca/man/#selection_by_uri
.RE
.IP "24." 4
string interpolation
.RS 4
\%http://dacs.dss.ca/man/#interpolation
.RE
.IP "25." 4
access control rules
.RS 4
\%http://dacs.dss.ca/man/dacs.acls.5.html
.RE
.IP "26." 4
INIT*
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#INIT*
.RE
.IP "27." 4
Auth clause
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#auth_clause
.RE
.IP "28." 4
section merging
.RS 4
\%http://dacs.dss.ca/man/#merging
.RE
.IP "29." 4
dacs_auth_transfer(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_auth_transfer.8.html
.RE
.IP "30." 4
Authorization Caching
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html#authorization_caching
.RE
.IP "31." 4
dacscookie(1)
.RS 4
\%http://dacs.dss.ca/man/dacscookie.1.html
.RE
.IP "32." 4
dacsauth(1)
.RS 4
\%http://dacs.dss.ca/man/dacsauth.1.html
.RE
.IP "33." 4
dacs_signout(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_signout.8.html
.RE
.IP "34." 4
The DACS_APPROVAL environment variable
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html#dacs_approval
.RE
.IP "35." 4
description of the ErrorDocument directive
.RS 4
\%http://httpd.apache.org/docs-2.4/mod/core.html#errordocument
.RE
.IP "36." 4
redirect()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#redirect
.RE
.IP "37." 4
access control rules
.RS 4
\%http://dacs.dss.ca/man/dacs.acls.5.html#elements
.RE
.IP "38." 4
dacs_admin()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#dacs_admin
.RE
.IP "39." 4
ADMIN_IDENTITY
.RS 4
\%http://dacs.dss.ca/man/#ADMIN_IDENTITY
.RE
.IP "40." 4
Bug 3641
.RS 4
\%http://issues.apache.org/bugzilla/show_bug.cgi?id=36411
.RE
.IP "41." 4
Bug 42430
.RS 4
\%http://issues.apache.org/bugzilla/show_bug.cgi?id=42430
.RE
.IP "42." 4
dacs_select_credentials(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_select_credentials.8.html
.RE
.IP "43." 4
ACS_TRACK_ACTIVITY
.RS 4
\%http://dacs.dss.ca/man/#ACS_TRACK_ACTIVITY
.RE
.IP "44." 4
SetDACSAuthPostBuffer
.RS 4
\%http://dacs.dss.ca/man/mod_auth_dacs.html#SetDACSAuthPostBuffer
.RE
.IP "45." 4
SERVICE_ARGS_TRUNCATED
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html#SERVICE_ARGS_TRUNCATED
.RE
.IP "46." 4
HTTP_AUTH
.RS 4
\%http://dacs.dss.ca/man/#HTTP_AUTH
.RE
.IP "47." 4
syntactically valid username
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#dacs_identity
.RE
.IP "48." 4
current jurisdiction
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#current_jurisdiction
.RE
.IP "49." 4
ACS_AUTHENTICATED_ONLY
.RS 4
\%http://dacs.dss.ca/man/#ACS_AUTHENTICATED_ONLY
.RE
.IP "50." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#Roles
.RE
.IP "51." 4
DACS_ACS
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html#dacs_acs_argument
.RE
.IP "52." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html
.RE
.IP "53." 4
on_success()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#on_success
.RE
.IP "54." 4
counter
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#counter
.RE
.IP "55." 4
current federation
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#current_federation
.RE
.IP "56." 4
ACS_INACTIVITY_LIMIT_SECS
.RS 4
\%http://dacs.dss.ca/man/#ACS_INACTIVITY_LIMIT_SECS
.RE
.IP "57." 4
FEDERATION_NAME
.RS 4
\%http://dacs.dss.ca/man/#FEDERATION_NAME
.RE
.IP "58." 4
NAME_COMPARE
.RS 4
\%http://dacs.dss.ca/man/#NAME_COMPARE
.RE
.IP "59." 4
auth_reply.dtd
.RS 4
\%http://dacs.dss.ca/man/../dtd-xsd/auth_reply.dtd
.RE
.IP "60." 4
dacs_auth_reply.dtd
.RS 4
\%http://dacs.dss.ca/man/../dtd-xsd/dacs_auth_reply.dtd
.RE
.IP "61." 4
AUTH_ERROR_HANDLER
.RS 4
\%http://dacs.dss.ca/man/#AUTH_ERROR_HANDLER
.RE
.IP "62." 4
cookie name
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#credentials
.RE
.IP "63." 4
dacs_auth_agent(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_auth_agent.8.html
.RE
.IP "64." 4
ACS_CREDENTIALS_LIMIT
.RS 4
\%http://dacs.dss.ca/man/#ACS_CREDENTIALS_LIMIT
.RE
.IP "65." 4
AUTH_SUCCESS_HANDLER
.RS 4
\%http://dacs.dss.ca/man/#AUTH_SUCCESS_HANDLER
.RE
.IP "66." 4
mitigate the risk of information disclosure with a cross-site scripting (XSS) attack
.RS 4
\%http://msdn.microsoft.com/en-us/library/ms533046%28VS.85%29.aspx
.RE
.IP "67." 4
are known
.RS 4
\%http://www.webappsec.org/lists/websecurity/archive/2006-05/msg00025.html
.RE
.IP "68." 4
a particular syntax
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#cookie-name-syntax
.RE
.IP "69." 4
COOKIE_SYNTAX
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#COOKIE_SYNTAX
.RE
.IP "70." 4
Netscape HTTP Cookies Specification
.RS 4
\%http://web.archive.org/web/20070805052634/http://wp.netscape.com/newsref/std/cookie_spec.html
.RE
.IP "71." 4
RFC 2965
.RS 4
\%http://www.rfc-editor.org/rfc/rfc2965.txt
.RE
.IP "72." 4
RFC 6265
.RS 4
\%http://www.rfc-editor.org/rfc/rfc6265.txt
.RE
.IP "73." 4
dacs.install(7)
.RS 4
\%http://dacs.dss.ca/man/dacs.install.7.html
.RE
.IP "74." 4
\fIFORMAT\fR
web service argument
.RS 4
\%http://dacs.dss.ca/man/dacs.services.8.html#FORMAT
.RE
.IP "75." 4
Advanced Techniques
.RS 4
\%http://dacs.dss.ca/man/#advanced
.RE
.IP "76." 4
RFC 1035
.RS 4
\%http://www.rfc-editor.org/rfc/rfc1035.txt
.RE
.IP "77." 4
dacs.groups(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.groups.5.html#group_syntax
.RE
.IP "78." 4
dacs.conf(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#jurisdiction_section_overview
.RE
.IP "79." 4
JURISDICTION_NAME
.RS 4
\%http://dacs.dss.ca/man/#JURISDICTION_NAME
.RE
.IP "80." 4
dacs(1)
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#naming
.RE
.IP "81." 4
RFC 2617
.RS 4
\%http://www.rfc-editor.org/rfc/rfc2617.txt
.RE
.IP "82." 4
HTTP Authentication
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html#http_authentication
.RE
.IP "83." 4
HTTP_AUTH_ENABLE
.RS 4
\%http://dacs.dss.ca/man/#HTTP_AUTH_ENABLE
.RE
.IP "84." 4
ACS_PRE_AUTH
.RS 4
\%http://dacs.dss.ca/man/#ACS_PRE_AUTH
.RE
.IP "85." 4
see below
.RS 4
\%http://dacs.dss.ca/man/#http_auth_syn2
.RE
.IP "86." 4
authentication styles
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#STYLE
.RE
.IP "87." 4
chmod(2)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=chmod&apropos=0&esektion=2&emanpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "88." 4
dacs_prenv(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_prenv.8.html
.RE
.IP "89." 4
dacsexpr(1)
.RS 4
\%http://dacs.dss.ca/man/dacsexpr.1.html
.RE
.IP "90." 4
encode()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#encode
.RE
.IP "91." 4
LDAP authentication
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#local_ldap_authenticate
.RE
.IP "92." 4
dacs_current_credentials(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_current_credentials.8.html
.RE
.IP "93." 4
regex(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=regex&apropos=0&esektion=3&emanpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "94." 4
dacs_sts(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_sts.8.html
.RE
.IP "95." 4
dacs_managed_infocard(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_managed_infocard.8.html
.RE
.IP "96." 4
XML Schema Part 2: Datatypes Second Edition
.RS 4
\%http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/datatypes.html#dateTime
.RE
.IP "97." 4
INFOCARD_CARD_LIFETIME_SECS
.RS 4
\%http://dacs.dss.ca/man/#INFOCARD_CARD_LIFETIME_SECS
.RE
.IP "98." 4
VFS URI
.RS 4
\%http://dacs.dss.ca/man/#VFS
.RE
.IP "99." 4
CARD_IMAGE_URL
.RS 4
\%http://dacs.dss.ca/man/dacs_managed_infocard.8.html#CARD_IMAGE_URL
.RE
.IP "00." 4
INFOCARD_CARD_DATETIME_EXPIRES
.RS 4
\%http://dacs.dss.ca/man/#INFOCARD_CARD_DATETIME_EXPIRES
.RE
.IP "01." 4
INFOCARD_CARDID_BASE_URL
.RS 4
\%http://dacs.dss.ca/man/#INFOCARD_CARDID_BASE_URL
.RE
.IP "02." 4
INFOCARD_CARD_OUTPUTDIR
.RS 4
\%http://dacs.dss.ca/man/#INFOCARD_CARD_OUTPUTDIR
.RE
.IP "03." 4
INFOCARD_CARDID_SUFFIX
.RS 4
\%http://dacs.dss.ca/man/#INFOCARD_CARDID_SUFFIX
.RE
.IP "04." 4
RFC 2396
.RS 4
\%http://www.rfc-editor.org/rfc/rfc2396.txt
.RE
.IP "05." 4
dacs_infocard(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_infocard.8.html
.RE
.IP "06." 4
PASSWORD_DIGEST
.RS 4
\%http://dacs.dss.ca/man/#PASSWORD_DIGEST
.RE
.IP "07." 4
INFOCARD_IP_PRIVACY_URL
.RS 4
\%http://dacs.dss.ca/man/#INFOCARD_IP_PRIVACY_URL
.RE
.IP "08." 4
dacs_mex(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_mex.8.html
.RE
.IP "09." 4
INFOCARD_STS_PASSWORD_METHOD
.RS 4
\%http://dacs.dss.ca/man/#INFOCARD_STS_PASSWORD_METHOD
.RE
.IP "10." 4
INFOCARD_STS_CERTFILE
.RS 4
\%http://dacs.dss.ca/man/#INFOCARD_STS_CERTFILE
.RE
.IP "11." 4
dacsinfocard(1)
.RS 4
\%http://dacs.dss.ca/man/dacsinfocard.1.html
.RE
.IP "12." 4
local_infocard_authenticate
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#local_infocard_authenticate
.RE
.IP "13." 4
INFOCARD_STS_KEYFILE_PASSWORD
.RS 4
\%http://dacs.dss.ca/man/#INFOCARD_STS_KEYFILE_PASSWORD
.RE
.IP "14." 4
INFOCARD_STS_KEYFILE
.RS 4
\%http://dacs.dss.ca/man/#INFOCARD_STS_KEYFILE
.RE
.IP "15." 4
INFOCARD_REQUIRE_APPLIES_TO
.RS 4
\%http://dacs.dss.ca/man/#INFOCARD_REQUIRE_APPLIES_TO
.RE
.IP "16." 4
INFOCARD_AUDIENCE
.RS 4
\%http://dacs.dss.ca/man/#INFOCARD_AUDIENCE
.RE
.IP "17." 4
wildcard certificate
.RS 4
\%http://wiki.cacert.org/wiki/WildcardCertificates
.RE
.IP "18." 4
\fBmod_vhost_alias\fR
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/mod_vhost_alias.html
.RE
.IP "19." 4
syslog(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=syslog&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "20." 4
LOG_LEVEL
.RS 4
\%http://dacs.dss.ca/man/#LOG_LEVEL
.RE
.IP "21." 4
regex(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=regex&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "22." 4
print()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#print
.RE
.IP "23." 4
printf()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#printf
.RE
.IP "24." 4
LOG_SENSITIVE
.RS 4
\%http://dacs.dss.ca/man/#LOG_SENSITIVE
.RE
.IP "25." 4
dacs(1)
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#logging
.RE
.IP "26." 4
diff(1)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=diff&apropos=0&sektion=1&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "27." 4
sed(1)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=sed&apropos=0&sektion=1&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "28." 4
LOG_FILTER
.RS 4
\%http://dacs.dss.ca/man/#LOG_FILTER
.RE
.IP "29." 4
--enable-hush-startup-logging
.RS 4
\%http://dacs.dss.ca/man/dacs.install.7.html#build_flag_--enable-hush-startup-logging
.RE
.IP "30." 4
debug_dacs
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html#debug_dacs
.RE
.IP "31." 4
mod_log_config
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/mod_log_config.html
.RE
.IP "32." 4
dacs_notices(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_notices.8.html
.RE
.IP "33." 4
Secure Mode
.RS 4
\%http://dacs.dss.ca/man/dacs_notices.8.html#secure_mode
.RE
.IP "34." 4
local_pam_authenticate
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#local_pam_authenticate
.RE
.IP "35." 4
pamd(8)
.RS 4
\%http://dacs.dss.ca/man/pamd.8.html
.RE
.IP "36." 4
dacs_passwd(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_passwd.8.html
.RE
.IP "37." 4
dacspasswd(1)
.RS 4
\%http://dacs.dss.ca/man/dacspasswd.1.html
.RE
.IP "38." 4
dacstoken(1)
.RS 4
\%http://dacs.dss.ca/man/dacstoken.1.html
.RE
.IP "39." 4
Web Service Arguments
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#web_service_arguments
.RE
.IP "40." 4
PASSWORD_AUDIT
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#PASSWORD_AUDIT
.RE
.IP "41." 4
ispunct(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=ispunct&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "42." 4
dacs_token(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_token.8.html
.RE
.IP "43." 4
dacs_admin(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_admin.8.html
.RE
.IP "44." 4
dacs(1)
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#digests-arg
.RE
.IP "45." 4
crypt(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=crypt&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "46." 4
MD5 function
.RS 4
\%http://www.rfc-editor.org/rfc/rfc1321.txt
.RE
.IP "47." 4
FIPS 180-4
.RS 4
\%http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf
.RE
.IP "48." 4
FIPS PUB 202, August/2015
.RS 4
\%http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf
.RE
.IP "49." 4
Argon2
.RS 4
\%https://en.wikipedia.org/wiki/Argon2
.RE
.IP "50." 4
RFC 2898
.RS 4
\%http://www.rfc-editor.org/rfc/rfc2898.txt
.RE
.IP "51." 4
argon2()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#argon2
.RE
.IP "52." 4
pbkdf2()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#pbkdf2
.RE
.IP "53." 4
scrypt()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#scrypt
.RE
.IP "54." 4
Rlink
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html#rlinks
.RE
.IP "55." 4
VFS specification
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#VFS
.RE
.IP "56." 4
sslclient(1)
.RS 4
\%http://dacs.dss.ca/man/sslclient.1.html
.RE
.IP "57." 4
DACS-Status-Line
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html#dacs_status_line
.RE
.IP "58." 4
DACS_HOME
.RS 4
\%http://dacs.dss.ca/man/#var_dacs_home
.RE
.IP "59." 4
role descriptor string
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#roles
.RE
.IP "60." 4
user()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#user
.RE
.IP "61." 4
dacs_uproxy(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_uproxy.8.html
.RE
.IP "62." 4
from()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#from
.RE
.IP "63." 4
dacs.vfs(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.vfs.5.html
.RE
.IP "64." 4
dacsvfs(1)
.RS 4
\%http://dacs.dss.ca/man/dacsvfs.1.html
.RE
.IP "65." 4
RFC 3986
.RS 4
\%http://www.rfc-editor.org/rfc/rfc3986.txt
.RE
.IP "66." 4
dacs(1)
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#gloss_item_type
.RE
.IP "67." 4
dacskey(1)
.RS 4
\%http://dacs.dss.ca/man/dacskey.1.html
.RE
.IP "68." 4
get()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#get
.RE
.IP "69." 4
Berkeley DB
.RS 4
\%http://www.oracle.com/us/products/database/berkeley-db/overview/index.html
.RE
.IP "70." 4
dbm(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=dbm&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "71." 4
GNU gdbm
.RS 4
\%http://www.gnu.org/software/gdbm/gdbm.html
.RE
.IP "72." 4
SQLite
.RS 4
\%http://www.sqlite.org
.RE
.IP "73." 4
dacs_vfs(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_vfs.8.html
.RE
.IP "74." 4
local_passwd_authenticate
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#local_passwd_authenticate
.RE
.IP "75." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#roles_clause
.RE
.IP "76." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE