Provided by: dacs_1.4.28b-3ubuntu2_i386 bug

NAME

       dacs.conf - DACS configuration files and directives

DESCRIPTION

       These files are part of the DACS suite.

       Nearly all DACS 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 DACS
       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 Apache. 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.

       Federations, jurisdictions, and other important concepts are discussed
       in dacs(1)[1].

           Note
           Unlike the "passive" configuration files found in most systems, the
           DACS 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 DACS 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.

           Note
           Each configuration file is completely read and processed once, each
           time a DACS 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
           Apache nor any other server needs to be restarted. It is usually
           safe to make minor updates to the configuration files while DACS 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 DACS 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.

           Tip
           While it may at first seem that DACS is difficult to configure, in
           practice the default configuration that comes with the DACS
           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.

           Tip
           ·   The DACS distribution includes a prototype version of
               site.conf, found in conf/site.conf-std, which establishes
               reasonable defaults based on DACS build-time arguments. It may
               need some customization for the local environment. By default,
               DACS looks for the site configuration file in
               federations/site.conf, relative to the DACS installation
               directory; conf/site.conf-std can be copied there and any
               necessary customizations made.

           ·   A command to validate and display configuration, dacsconf(1)[2]
               is available, as is a simple web service, dacs_conf(8)[3].
               Until you become comfortable with configuration files, consider
               running one of them after making changes. A fatal configuration
               error will prevent DACS from running and access to all
               DACS-wrapped resources will be denied.

   Locating dacs.conf and site.conf
       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 DACS jurisdictions. For example, if a machine
       is hosting more than one DACS jurisdiction, they can each use the same
       DACS binaries.

           Note
           Most DACS commands and web services require the dacs.conf file to
           exist; the exceptions are a few "standalone" programs, such as
           dacshttp(1)[4]. 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.

       Command line flags common to many DACS programs are described in
       dacs(1)[5].

       So that dacs_acs(8)[6] (which is invoked by the mod_auth_dacs[7]
       module) can find its configuration, the location of dacs.conf can be
       specified in Apache's httpd.conf file using the SetDACSAuthConf
       directive. It may instead, however, be specified through the DACS_CONF
       environment variable, on the command line, or using a build-time
       default. Similarly, the location of site.conf can be specified in
       Apache's httpd.conf file using the SetDACSAuthSiteConf directive,
       through the DACS_SITE_CONF environment variable, on the command line,
       or using a build-time default.

       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
       dacs_acs. It is a fatal error if a DACS service can't locate dacs.conf.

       Regardless of how the location of dacs.conf is specified, DACS performs
       string interpolation on the pathname. If interpolation fails, DACS will
       encounter a fatal error because it will not be able to locate its
       configuration file.

       Path Interpolation
           Path interpolation is available using a syntax and method similar
           to Apache's mod_vhost_alias[8] module. Interpolation is always
           performed to determine the locations of several resources used by
           DACS, such as dacs.conf and site.conf, and with DACS's LOG_FILE[9]
           directive, regardless of the manner in which the location is
           provided to DACS. It is applied whether the location of dacs.conf
           is specified using the -u command line flag or the Apache
           (mod_auth_dacs) SetDACSAuthConf directive, for instance.

           The functionality can also be accessed using the pathname()[10]
           function.

           The strings that may be interpolated into the pathname are obtained
           from the execution environment, in particular the URI authority
           information (based on Apache's SERVER_NAME and SERVER_PORT
           environment variables), the URI service path (described below),
           build-time configuration, and the applicable Jurisdiction section's
           distinguishing URI.

           Interpolation is controlled by printf-like format specifiers, as
           follows:

           %%
               Insert a literal percent character

           %a
               Insert the application name, which is obtained from the
               filename component of the program's argv[0] argument

           %bA
               Insert the absolute pathname of the root of the Apache
               installation directory, specified at build-time (APACHE_HOME)

           %bD
               Insert the absolute pathname of the root of the DACS
               installation directory, specified at build-time (DACS_HOME)

           %p
               Insert the port number of the virtual host (SERVER_PORT)

           %N.M
               Insert one or more components of the name, or a substring of
               those subcomponents.  N and M are numbers used to select part
               of the SERVER_NAME string (a domain name or IP address).  N
               selects from the dot-separated components of SERVER_NAME, while
               M selects characters within whatever N has selected.  M is
               optional and defaults to zero if it isn't present. The dot must
               be present if and only if M is also present. If N or M are
               greater than the number of parts available, a single underscore
               is interpolated. The numbers are interpreted as follows:

               0 or 1+ or -1+
                   the whole name

               1
                   the first part

               2
                   the second name

               -1
                   the last part

               -2
                   the next-to-last part

               2+
                   the second and all following parts

               -2+
                   the next-to-last and all preceding parts

           %s[N.M]
               This is a synonym for %N.M, with %s being equivalent to %0.

                   Note
                   In cases where the character following %s should not be
                   interpreted as part of the format, it must be escaped
                   (e.g., %s%2).

           %u[N.M]
               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".

                   Note
                   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).

           %U[N.M]
               This functions like the %u specifier except that it is applied
               to the applicable Jurisdiction section's[11] distinguishing URI
               (described below).  %U is equivalent to %U0.

                   Note
                   ·   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.

                   ·   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).

           Other format specifiers
               If a % is followed by an unrecognized specifier, that character
               is inserted verbatim.

           Other characters
               All other characters are inserted verbatim

           For example, if SERVER_NAME is dss.example.com and SERVER_PORT is
           8080, then the Apache directive:

               SetDACSAuthConf dacs-acs "/usr/local/apache2/conf/dacs/%2+/dacs.conf"

           will expand the path to
           /usr/local/apache2/conf/dacs/example.com/dacs.conf. The command
           line flag:

               -c /usr/local/dacs/%1%.%p/dacs.conf

           specifies the location of the configuration file to be
           /usr/local/dacs/dss.8080/dacs.conf.

           The %u specifier interpolates the URI service path, or portions
           thereof, which is the string HTTP_HOST/REQUEST_URI (without a query
           component). When a DACS 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.

   File Format
       dacs.conf is an XML document that conforms to Configuration.dtd[12].

       A dacs.conf file consists of an optional Default section followed by
       zero or more Jurisdiction sections. Either type of section consists of
       DACS directives or XML elements, called clauses, that contain DACS
       directives. There are three kinds of clauses: Auth clauses, Roles
       clauses, and Transfer clauses.

       Just to give its flavour, here's an incomplete dacs.conf file:

           <Configuration>
             <Default>
               LOG_FILE "${Conf::DACS_HOME}/logs/logfile"
               FEDERATION_DOMAIN "example.com"
               FEDERATION_NAME "ROOT"
               LOG_LEVEL "notice"
               SSL_PROG "/usr/local/dacs/bin/sslclient"
             </Default>

             <!-- Configuration of first jurisdiction -->
             <Jurisdiction uri="dss.example.com">
               JURISDICTION_NAME "DSS"
               <Auth id="auth_name">
                 URL "https://dss.example.com/cgi-bin/dacs/local_unix_authenticate"
                 STYLE "pass"
                 CONTROL "sufficient"
               </Auth>
              </Jurisdiction>

             <!-- Configuration of second jurisdiction -->
              <Jurisdiction uri="dss.example.com/foo">
                JURISDICTION_NAME "FOO"
              </Jurisdiction>

             <!-- Configuration of third jurisdiction -->
              <Jurisdiction uri="metalogic.example.com">
                JURISDICTION_NAME "METALOGIC"
              </Jurisdiction>
            </Configuration>

       The structure of site.conf is only slightly different. The Default
       section is mandatory in site.conf and no Jurisdiction sections are
       allowed.

           Note
           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 &amp; and a <
           character must be written as &lt;.

       Although the XML format of the DACS 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.

   The Default Section
       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.

       The site.conf file, if it exists, consists of only a Default section.
       Directives that are common to all of a site's dacs.conf files might be
       put in site.conf.

       Any configuration directive or clause may appear in the Default
       section.

   The Jurisdiction Section
       Each Jurisdiction section contains configuration directives that are
       associated with a particular jurisdiction. These directives override
       those found anywhere else, as described below.

   Section Merging and Directive Evaluation
       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 DACS, 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.

       The exception to this merging procedure is directives in the Stack
       category[13]. Instead of overriding, these directives accumulate.

       The order in which directives (but not clauses) appear within a section
       is not significant, even with respect to references to variables in the
       Conf namespace[14], with the exception of the EVAL directive[15].

       Only after directives in the three sections are merged are their
       right-hand sides evaluated (again, with the exception of EVAL[15]) 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).

       The undef() directive
           As a special case, if a directive is given the special value
           returned by undef()[16], 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 DACS web services but not for
           commands:

               LOG_LEVEL ${Env::REMOTE_ADDR:e} ? "TRACE" : undef()

               Note
               Because of the way configuration files are currently processed,
               the check for directive category satisfaction happens before
               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 Directive Categories[13]), even if
               just one would be included after the evaluation step.

       Fatal errors
           It is a fatal error to reference an undefined variable unless the e
           or ?  modifier flag[17] 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).

               Note
               When a fatal error occurs during configuration processing, a
               DACS 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
               ACS_ERROR_HANDLER[18] directive) will be invoked or a requested
               output format will be honoured during abnormal termination. A
               non-zero exit process status is always returned.

       An example
           Consider the following configuration excerpts:

               # In site.conf:
                 LOG_LEVEL "debug"

               # In the dacs.conf Default section:
                 LOG_LEVEL "notice"

               # In the dacs.conf Jurisdiction section:
                 LOG_LEVEL "trace"

           After configuration processing, the directive LOG_LEVEL will be set
           to "trace", and the variable ${Conf::LOG_LEVEL} will have that
           value during configuration processing.

           Here are some excerpts from a dacs.conf file:

               # 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}\
               /${Conf::JURISDICTION_NAME}/abc"

           When computing the VFS directive's value in the example above, the
           values of the FEDERATIONS_ROOT 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.

           Given the configuration:

               # 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"

           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.

   Jurisdiction Section Selection
       DACS web services and commands do not have any federation or
       jurisdiction information compiled into them, so that a single set of
       DACS 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 DACS work out what the request
       URIs to that jurisdiction look like, if it needs to.

       Most DACS 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 DACS 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.

       The applicable Jurisdiction section to use for a particular web service
       request or command can be determined in a variety of ways, using:

       ·   the -u command line flag to specify a config-uri that is matched
           against effective jurisdictional URIs[19];

       ·   the -uj command line flag to specify a jurisdiction-name that is
           matched against Jurisdiction sections' JURISDICTION_NAME directive;

       ·   the -us command line flag to indicate that there is only a single
           Jurisdiction section, so that section should be selected; or

       ·   by matching a request URI against effective jurisdictional
           URIs[19].

       Command line flags are described in dacs(1)[5], as is the
       DEFAULT_JURISDICTION environment variable.

       These methods will be described individually shortly.

           Tip
           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.

       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's domain
       name is foo.example.com, for instance, the Jurisdiction section in
       dacs.conf might look like:

           <Configuration>
             <Jurisdiction uri="foo.example.com">
               JURISDICTION_NAME "FOO"
               FEDERATION_DOMAIN "example.com"
               # And so on...
              </Jurisdiction>
            </Configuration>

       In the Apache configuration file (httpd.conf), one might specify:

           AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs "-u foo.example.com"

       (which tells DACS 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

           AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs "-us"

       (telling DACS 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

           AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs "-uj FOO"

       (telling DACS 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

           AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs

       In the last case, DACS will match the request URI (which presumably
       looks like https://foo.example.com/...) against foo.example.com.

       Multiple jurisdictions that are identified by distinct domain names are
       also easily configured once a DACS administrator decides how he would
       like request URIs to identify them. This is usually done much like
       this:

           <Configuration>
             <Jurisdiction uri="foo.example.com">
               JURISDICTION_NAME "FOO"
               FEDERATION_DOMAIN "example.com"
               # And so on...
              </Jurisdiction>

             <Jurisdiction uri="baz.example.com">
               JURISDICTION_NAME "BAZ"
               FEDERATION_DOMAIN "example.com"
               # And so on...
              </Jurisdiction>
            </Configuration>

       And so that the domain name in the request URI is matched against the
       jurisdiction's effective URI, one would use:

           AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs

       Multiple jurisdictions that share a domain name but are distinguished
       by a portion of the request URI pathname component, are often
       configured something like:

           <Configuration>
             <Jurisdiction uri="example.com/foo">
               JURISDICTION_NAME "FOO"
               FEDERATION_DOMAIN "example.com"
               # And so on...
              </Jurisdiction>

             <Jurisdiction uri="example.com/baz">
               JURISDICTION_NAME "BAZ"
               FEDERATION_DOMAIN "example.com"
               # And so on...
              </Jurisdiction>
            </Configuration>

       And again using:

           AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs

       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.

       Similarly, port numbers can also be used for Jurisdiction section
       selection:

           <Configuration>
             <Jurisdiction uri="example.com:443">
               JURISDICTION_NAME "FOO"
               FEDERATION_DOMAIN "example.com"
               # And so on...
              </Jurisdiction>

             <Jurisdiction uri="example.com:8443">
               JURISDICTION_NAME "BAZ"
               FEDERATION_DOMAIN "example.com"
               # And so on...
              </Jurisdiction>
            </Configuration>

       Lastly, a hostname wildcard syntax can be useful:

           <Configuration>
             <Jurisdiction uri="*.foo.example.com">
               JURISDICTION_NAME "FOO"
               FEDERATION_DOMAIN "example.com"
               # And so on...
              </Jurisdiction>

             <Jurisdiction uri="*.baz.example.com">
               JURISDICTION_NAME "BAZ"
               FEDERATION_DOMAIN "example.com"
               # And so on...
              </Jurisdiction>
            </Configuration>

           Important
           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't appear in multiple Jurisdiction
           sections and that each section has a different effective
           jurisdictional URI.

       If your particular requirement has been covered, it is probably safe to
       skip the detail that follows.

       The Effective Jurisdictional URI
           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 expression[20] that is evaluated at configuration
           processing time. The effective jurisdictional URI (or the
           jurisdiction's 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's URI or the -u flag's config-uri to find the applicable
           Jurisdiction section.

           The standard set of configuration variables[21] in the Conf and Env
           namespace[14] (but no others) are accessible during evaluation of
           uri_expr. Consider this partial configuration:

               <Jurisdiction uri_expr="${Env::SERVER_NAME}">

           Here, the effective jurisdictional URI is the value of the
           SERVER_NAME environment variable.

               Note
               ·   The environment established for a DACS web service and the
                   environment of a DACS command are typically different, so
                   programs run from the command line may fail if uri_expr
                   references an undefined variable.

               ·   Any error that occurs during evaluation of uri_expr is
                   fatal.

               ·   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:

                       <Jurisdiction uri_expr="regmatch(${Env::SERVER_NAME}, '(foo.example.com)|(baz.example.com)')">

           The effective jurisdictional URI has the following syntax:

               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

       Jurisdiction Selection by URI
           Whether the Jurisdiction section is selected based on the -u flag's
           explicit config-uri or the request URI provided to DACS through
           environment variables, the effective jurisdictional URIs are
           matched against the provided URI.

           An effective jurisdictional URI has the following semantics for
           matching against the provided URI:

           ·   If uri specifies the http scheme, the provided UR must not have
               used SSL; if uri specifies the https scheme, the provided URI
               must have used SSL; if neither scheme is specified, the scheme
               is immaterial.

           ·   The optional domain-spec specifies a domain name to match
               (case-insensitively) against the provided URI. If the initial
               component of domain-spec is "*.", then only the components that
               follow it in domain-spec need to match the domain name in the
               provided URI. For example, *.example.com matches example.com
               and foo.baz.example.com. If the domain-spec is omitted, the
               domain name in the provided URI is immaterial.

                   Note
                   The matching algorithm does not consider domain names that
                   map to the same IP address (i.e., aliases) to be
                   equivalent.

               The domain-spec 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.

           ·   The optional port-spec consists of one or more port numbers,
               any one of which must match the one specified explicitly (i.e.,
               not by default) in the provided URI. If the provided URI does
               not contain a port, it will not match any port-spec. Port
               numbers are separated by a comma (with no embedded whitespace).
               If the port-spec is omitted, the port number in the provided
               URI is immaterial.

           ·   The optional path-spec must match the prefix of the provided
               URI's path component. Matching is case-sensitive and is
               performed on corresponding path-segment elements.

           The matching algorithm first rejects any Jurisdiction section
           having an effective jurisdictional URI that does not satisfy the
           scheme-spec or the domain-spec. It looks for the section that
           contains a matching port-spec and that has the longest matching
           path-spec; the first such section will be selected. If no such
           section is found, however, it looks for the section that does not
           contain a port-spec and that has the longest matching path-spec;
           the first such section will be selected. It is a fatal error if no
           section can be selected.

               Tip
               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, etc. and lets dissimilar
               requests map to the same jurisdiction.

           For example, given the example configuration[22] above, if the
           request URL is:

               https://dss.example.com/foo/cgi-bin/dacs_authenticate

           then the second Jurisdiction section will be used.

           If the request URL is:

               https://dss.example.com/cgi-bin/dacs_authenticate

           then the first Jurisdiction section will be used.

           If a DACS utility is invoked with the command line flag -u
           metalogic.example.com, the third Jurisdiction section will be used.

       Jurisdiction Selection by Jurisdiction Name
           The applicable Jurisdiction section can be selected by providing
           the jurisdiction's name. The -uj flag's jurisdiction-name argument
           is compared against the unevaluated value of each section's
           JURISDICTION_NAME directive until the first exact string match is
           found; the section containing the directive will be selected.

               Note
               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 jurisdiction-name is that
               expression, not its value. Appropriate quotes are implied
               around jurisdiction-name, so they should be omitted on the
               command line.

               For example, given the (partial) configuration file entry:

                   <Jurisdiction uri="demo.example.com">
                   JURISDICTION_NAME "DEMO"
                   ...
                   </Jurisdiction>

               the command line argument "-uj DEMO" would select that
               jurisdiction section. If instead JURISDICTION_NAME were an
               expression that evaluated to the string DEMO, the argument
               would not select that jurisdiction section.

       Jurisdiction Selection by Default
           If dacs.conf contains a single Jurisdiction section, the -us flag
           can be used to select it without regard to the jurisdiction's name
           or effective jurisdictional URI. This can be particularly useful
           during testing.

           Should there be more than one Jurisdiction section when this flag
           is used, a fatal error will occur.

       The Distinguishing URI
           Regardless of how the Jurisdiction section is selected, that
           section's effective jurisdictional URI is matched against the -u
           flag's config-uri, if given, or the request URI according to the
           method described for Jurisdiction Selection by URI[23]. The
           resulting string is called the distinguishing URI. This string is
           another way of identifying the selected Jurisdiction section and
           can be used for string interpolation[24]. It is also related to the
           shared attribute used in access control rules[25].

           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.

   Directives
       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.

       A directive value is an expression or sequence of expressions
       (dacs.exprs(5)[20]) that is evaluated at run time during configuration
       processing. Here are some directives that are equivalent (on a
       Saturday):

           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

       Blank lines, leading white space, and lines whose first non-white space
       character is a # character (i.e., comments) are ignored.

       Any directive line may be split over physical lines by escaping the
       newline character, for example:

           ACS_ERROR_HANDLER "902 'Access denied, \
           user not authenticated'"

       An unrecognized directive name is a fatal error, as is an error
       encountered during expression evaluation.

       Evaluated Directives
           Some directive names end with a * character. By convention, this
           means that the directive's 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.

           Consider this INIT*[26] directive, which might appear within an
           Auth clause[27]:

                 INIT* '${Auth::CURRENT_USERNAME} = "goa\\" . ${Auth::CURRENT_USERNAME}'

           Because the directive's 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's value
           is presumably known and the formerly quoted expression is
           evaluated, yielding a final value for the directive.

       Directive Categories
           After section merging[28] 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:

           Required1:
               Directives of this category must be defined and must appear
               only once after merging.

           Required1-C:
               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.

           Required:
               These directives must always be specified at least once after
               merging, and may be repeated.

           Optional1:
               These directives may appear at most once after merging.

           Optional:
               These directives may appear zero or more times after merging.

           Stack:
               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.

               Note
               A directive marked Deprecated will be removed in a future
               version and should not be used.

           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).

           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 DACS 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).

               Note
               Directives that expect to be assigned a value of yes, no, on,
               or off recognize these keywords case-insensitively.

       General Directives
           The following general directives are provided. If present, they
           must appear within any Default section or Jurisdiction section, but
           outside of any clauses.

           Directive Index:

            1. ACCEPT_ALIEN_CREDENTIALS (Optional1)

            2. ACS_ACCESS_TOKEN_ENABLE (Optional1)

            3. ACS_ACCESS_TOKEN_LIFETIME_LIMIT (Required1-C)

            4. ACS_ACCESS_TOKEN_LIFETIME_SECS (Required1-C)

            5. ACS_AUTHENTICATED_ONLY (Optional1)

            6. ACS_CREDENTIALS_LIMIT (Optional1)

            7. ACS_EMIT_APPROVAL (Optional1)

            8. ACS_ERROR_HANDLER (Stack)

            9. ACS_FAIL (Optional1)

           10. ACS_INACTIVITY_LIMIT_SECS (Optional1)

           11. ACS_POST_BUFFER_LIMIT (Optional1)

           12. ACS_POST_EXCEPTION_MODE (Optional1)

           13. ACS_PRE_AUTH (Optional)

           14. ACS_SUCCESS (Optional)

           15. ACS_TRACK_ACTIVITY (Optional1)

           16. ADMIN_IDENTITY (Optional)

           17. ALLOW_HTTP_COOKIE (Optional1)

           18. AUTH_AGENT_ALLOW_ADMIN_IDENTITY (Optional1)

           19. AUTH_CREDENTIALS_ADMIN_LIFETIME_SECS (Optional1)

           20. AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS (Required1)

           21. AUTH_ERROR_HANDLER (Stack)

           22. AUTH_FAIL (Optional1)

           23. AUTH_FAIL_DELAY_SECS (Optional1)

           24. AUTH_SINGLE_COOKIE (Optional1)

           25. AUTH_SUCCESS (Optional)

           26. AUTH_SUCCESS_HANDLER (Optional1)

           27. AUTH_TRANSFER_EXPORT (Optional)

           28. AUTH_TRANSFER_TOKEN_LIFETIME_SECS (Optional1)

           29. COMPAT_MODE (Optional1)

           30. COOKIE_HTTPONLY (Optional1)

           31. COOKIE_NO_DOMAIN (Optional1)

           32. COOKIE_PATH (Optional1)

           33. CSS_PATH (Optional1)

           34. DTD_BASE_URL (Optional1)

           35. EVAL (Optional)

           36. FEDERATION_DOMAIN (Required1)

           37. FEDERATION_NAME (Required1)

           38. HTTP_AUTH (Stack)

           39. HTTP_AUTH_ENABLE (Optional1)

           40. HTTP_PROG (Required1)

           41. INFOCARD_AUDIENCE (Optional)

           42. INFOCARD_AUDIENCE_RESTRICTION (Optional)

           43. INFOCARD_CARD_DEFS_URL (Optional1)

           44. INFOCARD_CARD_FILL_URL (Optional1)

           45. INFOCARD_CARD_IMAGE_BASE_URL (Required1-C)

           46. INFOCARD_CARD_LIFETIME_SECS (Optional1)

           47. INFOCARD_CARD_OUTPUTDIR (Optional1)

           48. INFOCARD_CARD_VERSION (Optional1)

           49. INFOCARD_CARDID_BASE_URL (Required1-C)

           50. INFOCARD_CARDID_SUFFIX (Optional1)

           51. INFOCARD_CARD_DATETIME_EXPIRES (Optional1)

           52. INFOCARD_DIGEST (Optional1)

           53. INFOCARD_IP_PRIVACY_URL (Required1-C)

           54. INFOCARD_IP_PRIVACY_VERSION (Optional1)

           55. INFOCARD_ISSUER_INFO_ENTRY (Optional)

           56. INFOCARD_MEX_URL (Required1-C)

           57. INFOCARD_REQUIRE_APPLIES_TO (Optional1)

           58. INFOCARD_STRONG_RP_IDENTITY (Optional1)

           59. INFOCARD_STS_AUTH_TYPE (Required1-C)

           60. INFOCARD_STS_CACERTFILE (Required1-C)

           61. INFOCARD_STS_CERTFILE (Required1-C)

           62. INFOCARD_STS_KEYFILE (Required1-C)

           63. INFOCARD_STS_KEYFILE_PASSWORD (Required1-C)

           64. INFOCARD_STS_PASSWORD_METHOD (Required1-C)

           65. INFOCARD_STS_RP_ENDPOINT (Optional)

           66. INFOCARD_TOKEN_DRIFT_SECS (Optional1)

           67. INFOCARD_TOKEN_ISSUER (Required1-C)

           68. INFOCARD_TOKEN_LIFETIME_SECS (Optional1)

           69. INFOCARD_TOKEN_MAX_LENGTH (Optional1)

           70. INFOCARD_USERNAME_SELECTOR (Optional1)

           71. JURISDICTION_NAME (Required1)

           72. LOGINGEN_FILE (Optional1)

           73. LOGINGEN_PROG (Optional1)

           74. LOG_FILE (Optional1)

           75. LOG_FILTER (Stack)

           76. LOG_FORMAT (Optional1)

           77. LOG_LEVEL (Optional1)

           78. LOG_SENSITIVE (Optional1)

           79. NAME_COMPARE (Optional1)

           80. NOTICES_ACCEPT_HANDLER (Optional1)

           81. NOTICES_ACK_HANDLER (Optional1)

           82. NOTICES_DECLINE_HANDLER (Optional1)

           83. NOTICES_NAT_NAME_PREFIX (Optional1)

           84. NOTICES_SECURE_HANDLER (Optional1)

           85. NOTICES_WORKFLOW_LIFETIME_SECS (Optional1)

           86. PAMD_HOST (Optional1)

           87. PAMD_PORT (Optional1)

           88. PASSWORD_CONSTRAINTS (Optional1)

           89. PASSWORD_DIGEST (Optional1)

           90. PASSWORD_OPS_NEED_PASSWORD (Optional1)

           91. PASSWORD_SALT_PREFIX (Optional1)

           92. PERMIT_CHAINING (Optional1)

           93. PROXY_EXEC_DOCUMENT_ROOT (Optional1)

           94. PROXY_EXEC_MAPPER_DEFAULT_ACTION (Optional1)

           95. PROXY_EXEC_MAPPER_LOGGING (Optional1)

           96. PROXY_EXEC_MAPPER_LOG_FILE (Optional1)

           97. PROXY_EXEC_MAPPER_RULES_FILE (Optional1)

           98. PROXY_EXEC_PROG_URI (Optional1)

           99. RLINK (Optional)

           100. ROLE_STRING_MAX_LENGTH (Optional1)

           101. SECURE_MODE (Optional1)

           102. SIGNOUT_HANDLER (Optional1)

           103. SSL_PROG (Optional1)

           104. SSL_PROG_ARGS (Optional1)

           105. SSL_PROG_CA_CRT (Optional1)

           106. SSL_PROG_CLIENT_CRT (Optional1)

           107. STATUS_LINE (Optional1)

           108. TEMP_DIRECTORY (Optional1)

           109. TOKEN_REQUIRES_PIN (Optional1)

           110. TOKEN_HOTP_ACCEPT_WINDOW (Optional1)

           111. TRACE_LEVEL (Optional1)

           112. UNAUTH_ROLES (Optional1)

           113. UPROXY_APPROVED (Stack)

           114. VERBOSE_LEVEL (Optional1)

           115. VERIFY_IP (Required1)

           116. VERIFY_UA (Optional1)

           117. VFS (Stack)

           118. XSD_BASE_URL (Optional1)

           ACCEPT_ALIEN_CREDENTIALS (Optional1)
               If "yes", DACS will honour credentials imported (by any means)
               from a different federation. As a security precaution, such
               credentials are not used by default.

                   Security
                   In federations where dacs_auth_transfer(8)[29] is used,
                   jurisdictions will likely enable this capability.

           ACS_ACCESS_TOKEN_ENABLE (Optional1)
               If "yes", ACS's access token mechanism will be enabled. By
               default, this feature is disabled. Please see Authorization
               Caching[30] for details.

           ACS_ACCESS_TOKEN_LIFETIME_LIMIT (Required1-C)
               If ACS's 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 Authorization Caching[30] for details.

           ACS_ACCESS_TOKEN_LIFETIME_SECS (Required1-C)
               If ACS's 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 Authorization
               Caching[30] for details.

           ACS_AUTHENTICATED_ONLY (Optional1)
               If "yes", ACS will deny all requests that are not accompanied
               by valid credentials, regardless of any access control rules or
               other directives.

                   Note
                   Since this restriction also applies to DACS services, if
                   this mode is enabled an unauthenticated user will not be
                   able to access DACS 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 dacscookie(1)[31] or dacsauth(1)[32]), or
                   authenticate at some other jurisdiction.

           ACS_CREDENTIALS_LIMIT (Optional1)
               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 903).

               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
               REMOTE_USER 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.

               A user denied access at a jurisdiction due to this directive
               will be denied access to dacs_signout(8)[33] 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's cookie manager or by
               terminating the browser session.

                   Note
                   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
                   DACS 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.

                   Security
                   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).

                   DACS does not limit a user's 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
                   DACS.

           ACS_EMIT_APPROVAL (Optional1)
               If "yes", DACS will generate a DACS_APPROVAL environment
               variable that can be inspected by an invoked program to verify
               that its use in the current context was authorized by DACS.
               Before this feature is enabled, additional configuration is
               necessary; see The DACS_APPROVAL environment variable[34] for
               details.

           ACS_ERROR_HANDLER (Stack)
               If DACS denies a service request, the web server's DACS module
               will be so informed and will return a 403 ("Forbidden") status
               code to the web server. By using Apache's ErrorDocument
               directive, the resulting action taken by Apache can be
               customized.

               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 DACS 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.

               The ACS_ERROR_HANDLER directive defines (or overrides) Apache's
               behaviour with respect to an ErrorDocument directive for 403
               errors if DACS denies a service request. The syntax and meaning
               of this directive are similar to that of Apache's ErrorDocument
               directive. Please refer to the Apache documentation for a
               description of the ErrorDocument directive[35].

               Also refer to the description of the redirect()[36] function.

               The syntax of the directive is:

                   [url_pattern] error-code [handler-type] [error-action]

               The optional url_pattern is a URI path component that is
               matched against the request for which access was denied. It
               must begin with a '/'. It is like the url_pattern used in
               access control rules[37] in that it can require an exact match
               or end in "/*"; no query argument component is allowed. If it
               is absent, the url_pattern defaults to "/*", which matches any
               path.

               The error-code is either a numeric error code, an equivalent
               case-insensitive error-name, or the special symbol "*", which
               means the directive applies to any DACS error code for which
               there is no explicit directive.

               The following error-name and error-code values are defined:

               NO_RULE (900)
               Access denied, no applicable rule
                   All rules were examined but no rule applies to the service
                   request.

               BY_RULE (901)
               Access denied, forbidden by rule
                   The closest matching rule does not grant the service
                   request.

               NO_AUTH (902)
               Access denied, user not authenticated
                   No valid credentials were provided and either a) no rule
                   applies or b) the rule does not grant the service request.

               REVOKED (903)
               Access denied, user access revoked
                   Credentials were explicitly revoked.

               BY_REDIRECT (904)
               Access denied, redirect
                   A rule has explicitly redirected the user.

               ACK_NEEDED (905)
               Access denied, acknowledgement needed
                   One or more notices associated with the request must be
                   acknowledged.

               LOW_AUTH (906)
               Access denied, low authentication level
                   Although valid credentials were provided, they were
                   obtained by an authentication method not strong enough for
                   the requested resource.

               BY_SIMPLE_REDIRECT (907)
               Access denied, simple redirect
                   A rule has explicitly redirected the user; do not append
                   DACS query arguments.

               CREDENTIALS_LIMIT (908)
               Access denied, too many credentials were submitted
                   Too many selected credentials accompanied the request.

               INACTIVITY (909)
               Access denied, inactivity timeout
                   No authenticated requests were made within a designated
                   time interval.

               UNKNOWN (998)
               Access denied, reason unknown
                   An error occurred during processing but no additional
                   information is available.

               DEFAULT (*)
               Control symbol
                   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.

               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 DACS 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.

               If a handler-type 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
               error-action. The reason and default keywords are the only
               handler-type keyword that are not followed by an error-action.

               The following handler-type keywords and error-action arguments
               are recognized:

                1. reason

                   DACS will cause Apache to display the DACS error code that
                   identifies the reason for denying access followed by the
                   corresponding textual message.  Apache might display
                   messages like the following:

                       900 Access denied, no applicable access control rule
                       998 Access denied, internal error: Cookie parse error

                2. default

                   This form instructs DACS not to alter Apache's behaviour
                   (as if there was no ACS_ERROR_HANDLER specified at all).

                3. [url] URL

                   This form will cause Apache to redirect the client to URL
                   using the GET method. If the url keyword is absent, URL
                   must begin with the four characters "http". An invalid URL
                   may be rejected by Apache and treated as a message. The URL
                   may contain a properly escaped query string; DACS will
                   append the following parameters, in the order given, to URL
                   (unless the error name is BY_SIMPLE_REDIRECT, in which case
                   none of these parameters is passed):

                    1. DACS_ERROR_CODE, the DACS error code.

                    2. DACS_VERSION, the version number of DACS (e.g., "1.4").

                    3. DACS_FEDERATION, the federation that received the
                       service request, if available.

                    4. DACS_JURISDICTION, the jurisdiction that received the
                       service request, if available.

                    5. DACS_HOSTNAME, the domain name of the host that
                       received the service request, if available.

                    6. DACS_USER_AGENT, if provided by the user agent, this is
                       an identifying string, such as:

                           Mozilla/3.01 (X11; U; Linux 2.4.2 i386)

                    7. DACS_REQUEST_METHOD, the method used to invoke the
                       service request, if available. For example, "GET" or
                       "POST".

                    8. DACS_ERROR_URL, the service request URL, including any
                       query string component. The values of these parameters
                       are URL encoded.

                4. [localurl] /local-URL

                   This form is similar to the absolute URL form except that
                   redirection is to a local URL-path. The error-action must
                   begin with a slash. The URL may contain a properly escaped
                   query string; DACS will append additional parameters as in
                   the absolute URL form.

                5. [message] \"a message\"

                   This form causes Apache 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).

                       Note
                       Apache always sets the Content-Type for this message to
                       text/html. Although reported quite some time ago, Bug
                       3641[38] 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 Bug 42430[39].

                6. expr expression

                   The expr keyword, which cannot be omitted, indicates that
                   the error-action is an expression. The expression 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.

               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
               url_pattern and error-code that match the error condition
               exactly is used. Otherwise, if no such exact match if found,
               the first directive encountered having the closest url_pattern
               match and exact error-code match is used; failing that, the
               first directive with the closest url_pattern match and default
               ("*") error-code match is used.

               Consider these example directives:

                   ACS_ERROR_HANDLER "* reason"
                   ACS_ERROR_HANDLER '903 "Your access has been revoked"'
                   ACS_ERROR_HANDLER "/foo/* * /cgi-bin/dacs/foohandler"
                   ACS_ERROR_HANDLER "/foo/foo.html NO_AUTH /cgi-bin/foo-login.cgi"

               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.

               Here is an example of the expr handler form:

                   ACS_ERROR_HANDLER "* expr '\"&lt;em>Today is&lt;/em> \" . strftime(\"%D\")'"

               If triggered, this directive will emit a message similar to the
               following as Apache's custom error response:

                   <em>Today is</em> 05/16/07

               As with all such messages, Apache forces the Content-Type to be
               text/html.

               These two directives are equivalent:

                   ACS_ERROR_HANDLER "* message 'Hello world.'"
                   ACS_ERROR_HANDLER "* \"Hello world.\""

               The error response returned by Apache will be:

                   Hello world.

               Any invalid directive will result in Apache following its
               configured behaviour. A directive with a syntactically valid
               but undefined error-code is ignored, however.

               In the case where the service request was issued by Internet
               Explorer, if the length of the error response by the server
               isn't greater than some magic value and IE's "Show friendly
               HTTP error messages" is enabled, which it is by default, then
               IE will ignore the custom message. When the "message" and
               "reason" handler types are used, DACS adds some padding to
               thwart IE's "cleverness". For other handler types, the
               administrator is responsible for working around this problem.

                   Note
                   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 DACS. One example is
                   the situation where a user's access has been revoked and is
                   therefore unable to access any DACS-protected resource. If
                   an error occurs while DACS is processing a request for a
                   handler, DACS will fall back to Apache's default behaviour,
                   ignoring any normally applicable ACS_ERROR_HANDLER
                   directives.

           ACS_FAIL (Optional1)
               If dacs_acs denies access, the given expression is evaluated
               just before the ACS_ERROR_HANDLER[18] 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.

           ACS_INACTIVITY_LIMIT_SECS (Optional1)
               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
               dacs_select_credentials(8)[40]).

               There are two cases. If an activity tracking cookie is not sent
               with the current request (see ACS_TRACK_ACTIVITY[41]), 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
               dacs_acs(8)[6], access is denied and an INACTIVITY error (909)
               is raised; see ACS_ERROR_HANDLER[18]. At present, the only way
               for a user to continue after an inactivity error is to
               explicitly delete DACS cookies or implicitly delete them by
               restarting the browser. A non-DACS-wrapped web page or CGI
               program might be invoked as an error handler to assist.

               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.

           ACS_POST_BUFFER_LIMIT (Optional1)
               This is the counterpart to the SetDACSAuthPostBuffer[42]
               directive of DACS's mod_auth_dacs[7] Apache module. It
               establishes the maximum number of bytes of environment and POST
               stream that DACS should read from mod_auth_dacs[7], 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.)

           ACS_POST_EXCEPTION_MODE (Optional1)
               In the event that the web server has not made all of the
               request's arguments available to DACS for access control
               processing (see SERVICE_ARGS_TRUNCATED[43]), this directive
               tells dacs_acs(8)[6] what to do. The following keywords are
               recognized values:

               abort
                   Access control processing stops and access is denied.

               default
                   This is equivalent to discard.

               discard
                   Processing continues, but all web service arguments are
                   ignored and none will be available to access control rules.

               proceed
                   Continue processing, even though one or more arguments may
                   be corrupted or missing. This may result in a segmentation
                   fault or other unrecoverable error.

               query
                   Continue processing, discarding all POST arguments but
                   including any arguments that were passed in the request
                   URI's query component.

           ACS_PRE_AUTH (Optional)
               Similar to the pre-authorization authentication feature
               configured through the HTTP_AUTH[44] 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 syntactically
               valid username[45], credentials are created that (normally)
               exist only for the duration of the authorization check and
               which are associated with the current jurisdiction[46]. This
               directive provides a hook for associating an identity with a
               request based on the request itself (such as the request URI,
               its arguments, and other context).

               As a simple example, the following directive checks if the
               request includes a USERNAME argument, and if so, just uses it:

                   ACS_PRE_AUTH '${Args::USERNAME:e} ? ${Args::USERNAME} : ""'

               Note the single quotes around the expression so that it is
               evaluated at access control time instead of configuration
               processing time.

               The ACS_PRE_AUTH directives are processed if a request is
               received that does not include valid credentials and if not
               disabled by ACS_AUTHENTICATED_ONLY[47]. 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 ${Auth::ROLES} to a valid
               role string, it will be included in the credentials (see
               dacs_authenticate(8)[48]). Evaluation errors are ignored. If no
               expression returns a valid username, access control processing
               continues.

               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.

               If the request includes a -rname flag with the DACS_ACS[49]
               argument, its value is ${Args::RNAME}.

               Unlike when authentication is done through
               dacs_authenticate(8)[50], credentials are not returned to the
               client. This means that no DACS session state exists outside of
               dacs_acs and therefore some DACS 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.

           ACS_SUCCESS (Optional)
               If dacs_acs 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.

               Also see the on_success()[51] function.

                   Note
                   While it is typically true that if DACS 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 counter[52], 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.

           ACS_TRACK_ACTIVITY (Optional1)
               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 current
               federation[53]) if no web service request is made within a
               certain time period (also at any jurisdiction where it is
               enabled within the current federation[53]). See
               ACS_INACTIVITY_LIMIT_SECS[54]. 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.

               If the directive's value is "yes", dacs_acs(8)[6] emits a
               federation-wide HTTP cookie that notes the jurisdiction and
               date/time at which each DACS-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.

               The name of the activity tracking cookie has the following
               format:

                   DACS:federation-name::::ACTIVITY

               where federation-name is the official name assigned to the
               federation for which the cookie is valid (FEDERATION_NAME[55]).
               Activity tracking may be enabled without enabling inactivity
               detection (via ACS_INACTIVITY_LIMIT_SECS[54]). This feature
               depends on an appropriate level of clock synchronization at all
               participating jurisdictions.

           ADMIN_IDENTITY (Optional)
               This repeatable directive specifies a DACS identity (group
               names are currently not allowed) that DACS grants special
               privileges. If omitted, the current federation and
               jurisdiction[53] are implied. The usernames "unauth" and
               "unauthenticated" are disallowed, whether qualified with a
               jurisdiction or not. The function dacs_admin()[56] 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 dacs_admin().
               Changes to the list of DACS administrators take effect
               immediately. Comparison of these identities with credentials is
               controlled by the NAME_COMPARE[57] directive.

               Some DACS services call an internal version of this function to
               ensure certain operations are limited to a DACS administrator.

                   Security
                   Consider requiring more secure authentication for
                   administrator identities, such as using a two-factor
                   authentication method or combining two different
                   authentication methods.

           ALLOW_HTTP_COOKIE (Optional1)
               If "yes", DACS components will allow the environment variable
               HTTP_COOKIE to be used to pass DACS credentials. This is
               currently necessary when DACS components are invoked through
               IIS (except in conjunction with DACS 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", DACS components will
               fail if HTTP_COOKIE is present.

           AUTH_AGENT_ALLOW_ADMIN_IDENTITY (Optional1)
               Unless this directive has the value "yes", dacs_auth_agent will
               not return credentials that have been designated as an
               ADMIN_IDENTITY.

           AUTH_CREDENTIALS_ADMIN_LIFETIME_SECS (Optional1)
               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 dacs_authenticate
               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.

           AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS (Required1)
               The default lifetime, in seconds, of all credentials created by
               this jurisdiction for users. The jurisdiction's authentication
               services may override this value on a case-by-case basis,
               either through an authentication module (see
               auth_reply.dtd[58]) or by setting
               ${Auth::CREDENTIALS_LIFETIME_SECS} (see
               dacs_authenticate(8)[50]).

                   Security
                   The lifetime should be chosen such that it strikes a
                   balance between security and user convenience that is
                   appropriate for the jurisdiction and federation.

           AUTH_ERROR_HANDLER (Stack)
               If dacs_authenticate(8)[50] 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's browser.

                   Note
                   This feature is activated only if dacs_authenticate is
                   passed an ENABLE_AUTH_HANDLERS parameter that has a value
                   of 1.
               The following error code numbers and corresponding descriptive
               text are defined:

                   800 Authentication failed, invalid authenticating information
                   801 Authentication failed, invalid argument
                   802 Authentication failed, internal error
                   899 Authentication failed, reason unknown

               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.

               The dacs_authenticate service recognizes a FORMAT argument that
               is used to select between an XML-aware user agent (FORMAT=XML)
               and an HTML capable user agent (FORMAT is not specified or is
               not XML). In the case of an XML result, dacs_auth_reply.dtd[59]
               is used. The behaviour of this directive with respect to FORMAT
               is described below on a case-by-case basis.

               The following directives are supported:

                1. AUTH_ERROR_HANDLER "AUTH-error-code reason"

                   DACS will return an HTML (or XML, if FORMAT=XML) document
                   that describes why authentication failed, such as the
                   following:

                       800 Authentication failed, invalid authenticating information

                   This is the default behaviour.

                2. AUTH_ERROR_HANDLER "AUTH-error-code [url] URL"

                   This form causes DACS to redirect the client to the
                   specified URL, which may be a relative or absolute URL. If
                   the keyword url is absent, URL must begin with the four
                   characters http. The GET method will be used. The URL may
                   contain a properly escaped query string; DACS will append
                   the following parameters, in the order given, to the URL:

                    1. DACS_ERROR_CODE, the AUTH-error-code that identifies
                       the failure.

                    2. DACS_VERSION, the version number of DACS (e.g., "1.4").

                    3. DACS_FEDERATION, the federation that received the
                       service request, if available.

                    4. DACS_JURISDICTION The jurisdiction that received the
                       service request, if available.

                    5. FORMAT, 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 dacs_authenticate or the
                       default (HTML if FORMAT was not specified).

                   The values of these parameters are URL encoded.

                3. AUTH_ERROR_HANDLER "AUTH-error-code [file] full-pathname"

                   This form causes the contents of the file named by
                   full-pathname to be returned without regard to the presence
                   of a FORMAT argument.

                       Note
                       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.

                4. AUTH_ERROR_HANDLER "AUTH-error-code [message] \"message\""

                   This form causes the given message, surrounded by escaped
                   double quote characters, to be returned as HTML (or XML if
                   FORMAT=XML).

               The optional keywords are treated case-insensitively.

               The AUTH-error-code 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.

               This directive may appear multiple times, although multiple
               directives for the same AUTH-error-code are not allowed. Any
               invalid directive will generally be treated as a fatal error. A
               directive with a syntactically valid but undefined
               AUTH-error-code is ignored, however.

           AUTH_FAIL (Optional1)
               If dacs_authenticate fails to authenticates a user, the given
               expression is evaluated just before the AUTH_ERROR_HANDLER[60]
               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's purported identity may be available
               (${Args::USERNAME}), or if the user was previously
               authenticated successfully, as ${Env::REMOTE_USER}.

           AUTH_FAIL_DELAY_SECS (Optional1)
               If assigned a positive integer value, a particular user
               (ordinarily the one identified by the USERNAME argument to
               dacs_authenticate) 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 DACS.

           AUTH_SINGLE_COOKIE (Optional1)
               By default, each set of credentials that is returned in an HTTP
               cookie is assigned a cookie name[61] that corresponds to the
               identity represented by the credentials. If a user
               authenticates as two different identities through
               dacs_authenticate, 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's browser will
               replace the previous cookie with the new one.

               This directive also controls cookie names associated with
               credentials generated by dacscookie(1)[31],
               dacs_auth_agent(8)[62], and dacs_auth_transfer(8)[29]. Also see
               ACS_CREDENTIALS_LIMIT[63].

               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.

               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.  DACS will reject all
               credentials if a request includes more than one cookie with the
               same cookie name.

               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.

                   Security
                   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).

                   Changing this directive's 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.  DACS does not allow a request to
                   include multiple credentials for the same identity.

           AUTH_SUCCESS (Optional)
               If dacs_authenticate successfully authenticates a user, the
               given expression is evaluated just before the
               AUTH_SUCCESS_HANDLER[64] 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.

               Also see the on_success()[51] function.

               As an example, the following directive will run a web service
               after every successful login:

                   AUTH_SUCCESS 'https://internal.example.com/cgi-bin/userlogin?USERNAME=${Auth::IDENTITY}'

           AUTH_SUCCESS_HANDLER (Optional1)
               If dacs_authenticate successfully authenticates a user, the
               resulting action can be customized. This provides a way for the
               DACS administrator to redirect a user's browser after login.

                   Note
                   This feature is enabled only if dacs_authenticate is passed
                   an ENABLE_AUTH_HANDLERS parameter that has a value of 1.
               The dacs_authenticate service recognizes a FORMAT argument that
               is used to select between an XML-aware user agent (FORMAT=XML)
               and an HTML capable user agent (FORMAT is not specified or is
               not XML). In the case of an XML result, dacs_auth_reply.dtd[59]
               is used. The behaviour of this directive with respect to FORMAT
               is described below on a case-by-case basis.

               The following syntaxes are supported:

                1. AUTH_SUCCESS_HANDLER "[url] URL"

                   This form causes DACS to redirect the client to URL, which
                   may be a relative or absolute URL. If the keyword url is
                   absent, URL must begin with the four characters http. The
                   GET method will be used. The URL may contain a properly
                   escaped query string; DACS will append the following
                   parameters, in the order given, to the URL:

                   DACS_VERSION
                       The version number of DACS (e.g., "1.4").

                   DACS_FEDERATION
                       The federation that received the service request, if
                       available.

                   DACS_JURISDICTION
                       The jurisdiction that received the service request, if
                       available.

                   DACS_USERNAME
                       The username associated with the new credentials.

                   FORMAT
                       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 dacs_authenticate or the default (HTML
                       if FORMAT was not specified).

                   The values of these parameters are URL encoded.

                2. AUTH_SUCCESS_HANDLER "[file] full-pathname"

                   This form causes the contents of the file named by
                   full-pathname to be returned without regard to the presence
                   of a FORMAT 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.

                       Note
                       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.

                3. AUTH_SUCCESS_HANDLER "[message] \"message\""

                   This form causes the given message, surrounded by escaped
                   double quote characters, to be returned as HTML (or XML if
                   FORMAT=XML).

                4. AUTH_SUCCESS_HANDLER "credentials"

                   This form causes the user's credentials to be displayed,
                   either as an HTML or XML (if FORMAT=XML) document. This is
                   the default behaviour.

               The optional keywords are treated case-insensitively.

           AUTH_TRANSFER_EXPORT (Optional)
               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; it must be a
               syntactically valid federation name. Whitespace separates the
               federation name from the URL. Please refer to
               dacs_auth_transfer(8)[29] for details.

           AUTH_TRANSFER_TOKEN_LIFETIME_SECS (Optional1)
               This is the lifetime, in seconds, of a token produced by the
               TOKEN operation of dacs_auth_transfer(8)[29] 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.

           COMPAT_MODE (Optional1)
               This indicates that, to the extent possible, credentials issued
               by a different release of DACS should be accepted. At present,
               the only supported values are off (the default, which disables
               this mode) and 1.2.

                   Important
                   This directive is not intended to provide complete
                   interoperability among DACS releases and in fact it does
                   not in certain situations. Old releases of DACS may contain
                   security-related bugs, or may rely on third-party software
                   that contains security-related bugs.  DACS installations
                   are urged to upgrade rather than to depend on the limited
                   backward compatibility supplied by this directive.  There
                   is no guarantee that any particular level of backward
                   compatibility will be carried forward in subsequent
                   releases of DACS.

           COOKIE_HTTPONLY (Optional1)
               If "yes", the HttpOnly attribute will be included with cookies
               produced by DACS. This attribute is a Microsoft extension that
               is used to "mitigate the risk of information disclosure with a
               cross-site scripting (XSS) attack[65]". This attribute is not
               recognized by all browsers but these browsers should ignore it.
               The default is "no".

                   Security
                   Methods of defeating this attribute are known[66], so
                   administrators may need to take additional precautions
                   against XSS attacks.

           COOKIE_NO_DOMAIN (Optional1)
               If "yes", no domain attribute will appear when DACS 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
               DACS's single sign-on feature since the cookie (credentials)
               will only be sent with requests made to that domain name or IP
               address.

               This directive is sometimes useful when DACS 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.

               The default is "no".

           COOKIE_PATH (Optional1)
               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 Netscape
               HTTP Cookies Specification[67] and RFC 2965[68] for details.

                   Security
                   The default value is "/", which means that the cookie will
                   be sent by a user agent along with every request sent to
                   the jurisdiction's host. The value should be set to the
                   most specific URL path under which all DACS-wrapped
                   services appear so that DACS 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 DACS-authenticated
                   user to visit a service that is not DACS-wrapped and
                   capture cookies that represent DACS identities. For
                   example, if a jurisdiction segregated its DACS-wrapped
                   static content under /dacs/content and its DACS-wrapped CGI
                   programs under /dacs/cgi-bin, then COOKIE_PATH should have
                   the value "/dacs".

           CSS_PATH (Optional1)
               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 DACS web services and utilities.
               The mapping between this path and a local directory, if any,
               depends on Apache's configuration; for example, if its value is
               "/css", the location of the corresponding directory will depend
               on the location of the server's document root and any
               applicable Alias directive.

               If this directive is not used, a compile-time default of "/css"
               is used, which assumes that an Apache directive like this one
               is used:

                   Alias /css "/usr/local/dacs/www/css/"

               Please refer to dacs.install(7)[69] for additional information
               about use of the Alias directive.

           DTD_BASE_URL (Optional1)
               When DACS 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.,

                   <!DOCTYPE foo SYSTEM "http://example.com/dacs/dtd-xsd/foo.dtd">

               If DTD_BASE_URL is not configured, an internal DTD will be
               emitted. Also see the description of the FORMAT web service
               argument[70].

           EVAL (Optional)
               The EVAL directive is special in that it may appear in any
               clause and because it is always evaluated when it is first seen
               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 Advanced Techniques[71]). 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
               ${Conf::FEDERATION_DOMAIN}, for example). Example:

                   EVAL ${Conf::a_special_path} = "/my/path"

           FEDERATION_DOMAIN (Required1)
               The suffix of the domain name (RFC 1035[72] 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 dacs.groups(5)[73]), and that
               this is a one-to-many association (see dacs.conf(5)[74]).
               Example: example.com

           FEDERATION_NAME (Required1)
               The name for the federation of jurisdictions. The syntax is the
               same as for JURISDICTION_NAME[75]: an alphabetic followed by
               zero or more alphanumeric characters, '-', or '_'. By
               convention, this is in all-caps, however. Please see
               dacs(1)[76] for additional information. Example: FEDROOT

           HTTP_AUTH (Stack)
               This directive is used to perform user authentication at access
               control time rather than in a separate step. This
               authentication is triggered through DACS's internal
               implementation of HTTP Basic or Digest authentication (see RFC
               2617[77]). If prompting is enabled, the user will be asked for
               his username and password by the user agent's 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 DACS
               authentication method for validation. The resulting identity is
               associated with the current jurisdiction[46].

               Other than by placing the resource or resources specified by
               this directive under the control of DACS, no additional Apache
               configuration needs to be done to use this feature. Please
               refer to the section on HTTP Authentication[78] for additional
               information about this feature and how it is used. Also consult
               the HTTP_AUTH_ENABLE[79] directive.

               Two different mechanisms are available: pre-authorization
               testing and post-authorization testing. The HTTP_AUTH_ENABLE
               directive is used to enable one or both mechanisms.

               The pre-authorization testing mechanism is used if:

                1. a request is received that does not include valid
                   credentials;

                2. the feature is enabled by HTTP_AUTH_ENABLE (i.e., it is set
                   to "pre_acs_only" or "both") and not disabled by
                   ACS_AUTHENTICATED_ONLY[47];

                3. no ACS_PRE_AUTH[80] directive is successful;

                4. the applicable directive includes the -pre flag (see
                   below[81]); and

                5. either the request includes an Authorization request header
                   or the return of an HTTP WWW-Authenticate response header
                   is enabled.

               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 dacs_acs is allowed to respond
               with a WWW-Authenticate response header, the configuration
               variable ${Conf::http_auth_401} must be set to "yes".

               The post-authorization testing mechanism is used if:

                1. a request is denied because the user was not authenticated;

                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;

                3. the applicable directive does not include a -pre flag (see
                   below).

               One important difference between the two mechanisms is that
               while the post-authorization mechanism works by redirecting the
               user to dacs_authenticate(8)[50] after authorization checking
               denies a request, the pre-authorization mechanism does not
               involve any redirection and dacs_authenticate is not used.
               Instead, dacs_acs performs authentication internally (by
               calling dacsauth as a function) and credentials are not
               returned to the client; credentials are created that (normally)
               exist only for the duration of the authorization check, which
               means that no DACS session state exists outside of dacs_acs and
               therefore some DACS 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 authentication styles[82]
               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 AUXILIARY 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 AUXILIARY argument using a
               run-time configuration directive. With pre-authorization, roles
               can be assigned to the temporary credentials (refer to the
               description of the -r flag and the role-module-spec in
               dacsauth(1)[32] for details).

                   Security
                   Like dacsauth and dacs_authenticate, if dacs_acs uses a
                   built-in module to perform authentication, it must run
                   setuid or setgid (chmod(2)[83]). 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.

               The value of the HTTP_AUTH directive follows any one of the
               following three forms:

                1.

                       auth_scheme auth_realm url_pattern+

                2.

                       auth_scheme auth_realm url_pattern+ -pre [[-param] param-string]
                           {-m auth-module-spec [auth-flag]*}+ {-r roles-module-spec}*

                3.

                       except url_pattern+

               The first syntactical form is for the post-authentication
               mechanism:

               ·   auth_scheme is the (case-insensitive) authentication scheme
                   to use (e.g., Basic);

               ·   auth_realm is the (case-sensitive) realm-value string
                   associated with the resource (see RFC 2617[77]);

               ·   url_pattern+ 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 url_pattern attribute used in access control
                   rules[37] in that it can either specify an exact match or,
                   by ending in "/*", a wildcard match; no query argument
                   component is allowed. Each url_pattern begins with a /
                   character.

               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:

               ·   -pre selects the pre-authorization testing mechanism; the
                   default is to use post-authorization testing. Because each
                   url_pattern begins with a / character, the -pre flag
                   implicitly ends the url_pattern list.

               ·   param-string is an optional string consisting of
                   authentication parameters as per RFC 2617 (note: Basic auth
                   does not permit any optional parameters). For clarity, or
                   if param-string might be confused with another syntactic
                   element, it can be preceded by a -param flag. In the
                   absence of the -param flag, any non-flag argument is
                   assumed to be the param-string. Only one param-string is
                   allowed.

               ·   -m auth-module-spec specifies an authentication module
                   using the command-line syntax of dacsauth(1)[32]. This
                   argument must occur at least once. Following the
                   auth-module-spec can be zero or more auth-flag arguments to
                   apply to the module's authentication context. The
                   -Ddirective=value flag, -fj jurname flag, and the -fn
                   fedname flag are recognized and have the same semantics as
                   when used by dacsauth(1)[32].

               ·   -r roles-module_spec specifies a roles module. This
                   argument may occur zero or more times.

               In the third syntactical form, the except keyword identifies
               portions of the URL space that should not trigger HTTP
               authentication.

               The HTTP_AUTH directives "stack", like the
               ACS_ERROR_HANDLER[18] directive.  DACS will search for the
               first exact url_pattern that matches or will select the closest
               wildcard url_pattern. Two or more directives with the same
               url_pattern should not be configured.

               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 current
               jurisdiction[46]) 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.

                   HTTP_AUTH "basic \"Info Realm\" /cgi-bin/dacs/dacs_prenv /cgi-bin/dacs/dacs_version"
                   HTTP_AUTH "basic \"CGI Realm\"   /cgi-bin/dacs/*"

               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):

                     HTTP_AUTH "basic \"CGI Realm\" /cgi-bin/dacs/*"
                     HTTP_AUTH "except /cgi-bin/dacs/dacs_prenv"

                   Tip
                   An administrator can take advantage of DACS's active
                   configuration processing to decide at run-time which
                   auth_scheme, auth_realm, or password file to use, for
                   instance, perhaps depending on the request's arguments.
               As an example of pre-authorization testing authentication,
               consider the following configuration directives:

                   HTTP_AUTH_ENABLE "pre_acs_only"
                   EVAL ${Conf::http_auth_401} = "no"
                   HTTP_AUTH "basic \"dacs_prenv Realm\" /cgi-bin/dacs/dacs_prenv -m unix passwd suff"

               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 DACS dacs_prenv(8)[84] service with
               the built-in Basic authentication feature at pre-authorization
               testing time. Given this configuration, if a client requests
               dacs_prenv but does not include credentials:

               ·   if no Authorization header was sent and
                   ${Conf::http_auth_401} is "no", then execution will proceed
                   as if the feature were disabled (i.e., the user will be
                   unauthenticated)

               ·   if no Authorization header was sent and
                   ${Conf::http_auth_401} is "yes", then DACS will respond
                   with a WWW-Authenticate response header and 401 status code

               ·   if an Authorization header was sent, the username and
                   password will be validated using the built-in Unix
                   authentication module:

                   ·   if authentication succeeds, temporary credentials will
                       be created and used for the request, but will not be
                       returned to the client

                   ·   if authentication fails, access will be denied

                   Tip
                   You can create an Authorization header by constructing a
                   string consisting of an account name, a colon, and the
                   account's password. MIME encode the resulting string - you
                   can use dacsexpr(1)[85] and the encode()[86] function:

                       % dacsexpr
                       > encode(mime, "guest:apassword")
                       "Z3Vlc3Q6YXBhc3N3b3Jk"

                   The header for the example above would look like:

                       Authorization: Basic Z3Vlc3Q6YXBhc3N3b3Jk

                   And using dacshttp(1)[4], you could use the flag:

                       -header Authorization "Basic Z3Vlc3Q6YXBhc3N3b3Jk"
               The example that follows shows how LDAP authentication[87]
               using the direct method might be configured. In an appropriate
               place in dacs.conf, we might insert these directives:

                   HTTP_AUTH_ENABLE "pre_acs_only"
                   HTTP_AUTH "basic \"LDAP Login Using Your Common Name\" /basic/* -pre \
                       -m https://example.example.com/cgi-bin/dacs/local_ldap_authenticate \
                       password sufficient -Of /usr/local/dacs/ldap/ldap_auth_options_direct"

               In the file /usr/local/dacs/ldap/ldap_auth_options_direct
               (which must be readable at run-time by dacs_acs(8)[6]), we
               might put:

                   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}"

               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
               DACS username, it must be replaced by (or mapped to) an
               acceptable DACS 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 local_ldap_authenticate
               module to validate the information provided by the user.

               To also obtain the user's roles from the directory, the
               set_roles style modifier and an LDAP_ROLES_SELECTOR* directive
               can be added to the configuration:

                   HTTP_AUTH_ENABLE "pre_acs_only"
                   HTTP_AUTH "basic \"LDAP Login Using Your Common Name\" /basic/* -pre \
                       -m https://example.example.com/cgi-bin/dacs/local_ldap_authenticate \
                       password,set_roles sufficient -Of /usr/local/dacs/ldap/ldap_auth_options_direct"

               And to /usr/local/dacs/ldap/ldap_auth_options_direct:

                   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}"

                   Tip
                   Since the pre-authorization mechanism does not return DACS
                   credentials to the user's web browser, a subsequent
                   invocation of dacs_current_credentials(8)[88] 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 Apache
                   with access permitted by DACS, however, the program can
                   display its environment, which will include DACS_USERNAME,
                   DACS_ROLES, and so on. For example, dacs_prenv(8)[84] can
                   be used for this, as can this simple PHP script
                   (phpinfo.php):

                       <html><head></head><body>
                       <p>
                       <?php
                       phpinfo();
                       ?>
                       </p>
                       </body>
                       </html>
               To authenticate against a Unix account and assign the user's
               group membership as roles, this configuration might be used:

                   HTTP_AUTH_ENABLE "pre_acs_only"
                   HTTP_AUTH "basic \"Login Using Your Unix Account\" /basic/* -pre \
                       -m https://example.example.com/cgi-bin/dacs/local_unix_authenticate \
                       password sufficient -Of /usr/local/dacs/ldap/ldap_auth_options_direct \
                       -r https://example.example.com/cgi-bin/dacs/local_unix_roles"

               Note that local_unix_authenticate must run with sufficient
               privileges to validate the username/password pair.

           HTTP_AUTH_ENABLE (Optional1)
               This directive's value must be one of:

               ·   "post_acs_only", if only post-authorization testing HTTP
                   Authentication[78] may be used,

               ·   "pre_acs_only", if only pre-authorization testing HTTP
                   authentication may be used, or

               ·   "yes" or "both" if either mechanism may be used.

               Refer to HTTP_AUTH[44] for additional details.

           HTTP_PROG (Required1)
               The full pathname of the executable dacshttp(1)[4] program, a
               utility distributed with DACS. This program is used by DACS
               components to invoke local services, optionally using SSL.

           INFOCARD_AUDIENCE (Optional)
               This directive must be configured for DACS to function as a
               Relying Party. When DACS acts as a Relying Party, each of these
               directives is applied to the value of an Audience element (a
               URI) in a secure token's AudienceRestrictionCondition element
               until a successful match is found. Several matching functions
               are available using the following syntax:

                   function [space+ arg-to-match-against-Audience]

               function is case insensitive.

               uri match-URI
                   The match-URI 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.

                       INFOCARD_AUDIENCE "uri http://DACS.DSS.CA/infocard-demo"

               any
                   Any Audience is acceptable.

                       INFOCARD_AUDIENCE "any"

               regex match-regex
               regex/flags match-regex
                   In the first form, the regular expression match-regex is
                   matched (unanchored) against the Audience URI. In the
                   second form, one or more flags can precede the regular
                   expression: 'i' specifies case-insensitive matching and 'e'
                   specifies "extended" regular expressions rather than the
                   default "basic" regular expressions. IEEE Std 1003.2
                   ("POSIX.2") regular expressions are supported
                   (regex(3)[89]).

                       INFOCARD_AUDIENCE "regex/i ^https://dacs.dss.ca:8443"

                   The following directives are equivalent:

                       INFOCARD_AUDIENCE "regex .*"
                       INFOCARD_AUDIENCE "any"

               host match-hostname
                   The match-hostname, which may be a domain name or an IP
                   address, is matched case-insensitively against the host
                   name in the Audience URI.

                       INFOCARD_AUDIENCE "host dacs.dss.ca"

               prefix match-URI
                   The match-URI 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).

                       INFOCARD_AUDIENCE "prefix https://dacs.dss.ca/infocards"

           INFOCARD_AUDIENCE_RESTRICTION (Optional)
               Used by dacs_sts(8)[90], this optional directive specifies the
               value of an Audience element in an
               AudienceRestrictionCondition.

           INFOCARD_CARD_DATETIME_EXPIRES (Optional1)
               This optional directive specifies the date and time of
               expiration for a managed InfoCard created by
               dacs_managed_infocard(8)[91]. The XML Schema dateTime format
               must be used (see XML Schema Part 2: Datatypes Second
               Edition[92]); e.g.,

                   INFOCARD_CARD_DATETIME_EXPIRES "2010-06-15T09:46:31-08:00"

               Also see INFOCARD_CARD_LIFETIME_SECS[93].

           INFOCARD_CARD_DEFS_URL (Optional1)
               This optional directive is used by dacs_managed_infocard(8)[91]
               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's infocard directory includes an example program,
               demo_card_defs.php, which documents the program's arguments and
               output syntax.

           INFOCARD_CARD_FILL_URL (Optional1)
               This optional directive is used by dacs_sts(8)[90] 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 DACS-wrapped. It is passed special DACS
               credentials (as an HTTP cookie). The distribution's infocard
               directory includes an example program, demo_fill_claims.php,
               which documents the program's arguments and output syntax.

           INFOCARD_CARD_IMAGE_BASE_URL (Required1-C)
               This directive is required by dacs_managed_infocard(8)[91]. It
               is the initial part of a DACS VFS URI[94] 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 infocard_card_image_passwd,
               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 infocard_card_image_cert (default
               value: dacs_x509certificate_credential.png) and
               infocard_card_image_card (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 CARD_IMAGE_URL[95] argument to
               dacs_managed_infocard.

               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.

           INFOCARD_CARD_LIFETIME_SECS (Optional1)
               If INFOCARD_CARD_DATETIME_EXPIRES is not defined, the
               expiration date and time of a managed InfoCard created by
               dacs_managed_infocard(8)[91] 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
               INFOCARD_CARD_DATETIME_EXPIRES[96].

           INFOCARD_CARD_OUTPUTDIR (Optional1)
               If a managed InfoCard generated by dacs_managed_infocard(8)[91]
               is stored in a file, it is written to this directory. The name
               of the file is of the form username_random.crd. See
               INFOCARD_CARDID_BASE_URL[97].

           INFOCARD_CARD_VERSION (Optional1)
               This directive is used by dacs_managed_infocard(8)[91] to
               provide a value for the CardVersion element in a managed
               InfoCard. The default is "1".

           INFOCARD_CARDID_BASE_URL (Required1-C)
               This directive is required by dacs_managed_infocard(8)[91]. 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 INFOCARD_CARD_OUTPUTDIR[98], 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 INFOCARD_CARDID_SUFFIX[99].

           INFOCARD_CARDID_SUFFIX (Optional1)
               This optional directive is used by dacs_managed_infocard(8)[91]
               and specifies a string to be appended as a final path element
               to the value of INFOCARD_CARDID_BASE_URL[97] to form a new
               card's CardId. If the value of INFOCARD_CARDID_SUFFIX is:

               identity
                   The specified or implied identity assigned to the card is
                   interpolated; this is the default.

               username
                   The specified or implied username assigned to the card is
                   interpolated.

               random
                   A safely-encoded 20-byte random string is interpolated.

               default
                   The default is used ("identity").

               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 (RFC 2396[100]).

           INFOCARD_DIGEST (Optional1)
               The name of the hash algorithm to use in account files for
               self-issued InfoCard-based authentication (see
               dacs_infocard(8)[101]). The syntax is the same as for the
               PASSWORD_DIGEST[102] directive. The default is "SHA256".

           INFOCARD_IP_PRIVACY_URL (Required1-C)
               This directive is required by dacs_managed_infocard(8)[91] and
               specifies the URL of the Identity Provider's PrivacyNotice. A
               default notice is configured.

           INFOCARD_IP_PRIVACY_VERSION (Optional1)
               This optional directive is used by dacs_managed_infocard(8)[91]
               and specifies an integer version number (greater than zero) of
               the document returned by the INFOCARD_IP_PRIVACY_URL[103]. If
               it is set to the empty string, however, no version number will
               be specified for the PrivacyNotice. The default is "1".

           INFOCARD_ISSUER_INFO_ENTRY (Optional)
               This optional directive, which may be repeated, is used by
               dacs_managed_infocard(8)[91] 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
               "EntryName:EntryValue".

           INFOCARD_MEX_URL (Required1-C)
               This directive, used by dacs_managed_infocard(8)[91], specifies
               the URL of the WS-MetadataExchange responder for managed
               InfoCards. Also see dacs_mex(8)[104].

           INFOCARD_REQUIRE_APPLIES_TO (Optional1)
               Used optionally by dacs_managed_infocard(8)[91], this directive
               controls a managed InfoCard's RequireAppliesTo element, which
               by default is omitted. This element is used to control whether
               the card's Identity Provider (e.g., dacs_sts(8)[90]) will be
               informed as to the identity of the Relying Party via the
               wsp:AppliesTo element (when it is informed, it is called an
               auditing card, which is used in auditing mode). Following the
               Identity Selector Interoperability Profile, this directive may
               have any of the following values:

               no
                   The RequireAppliesTo element is omitted (called a
                   non-auditing card).

               yes
                   RequireAppliesTo is emitted, but with its optional
                   attribute omitted (an auditing card).

               true
                   RequireAppliesTo is emitted with the attribute
                   Optional="true" (called an auditing-optional card).

               false
                   RequireAppliesTo is emitted with the attribute
                   Optional="false" (an auditing card).

           INFOCARD_STRONG_RP_IDENTITY (Optional1)
               Used optionally by dacs_managed_infocard(8)[91], 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.

           INFOCARD_STS_AUTH_TYPE (Required1-C)
               This directive, required by dacs_managed_infocard(8)[91],
               specifies (case-insensitively) the authentication credential
               type, which identifies an Identity Selector user to an IP/STS
               (see dacs_sts(8)[90]). 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:

               password
               passwd
                   This is the username/password credential type. See
                   INFOCARD_STS_PASSWORD_METHOD[105].

               cert
                   This is the X.509 V3 certificate credential type. An SSL
                   client certificate must be used with the request to
                   dacs_managed_infocard(8)[91] 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.

               card
                   This is the self-issued credential type. A self-issued
                   InfoCard must be submitted with the request to
                   dacs_managed_infocard(8)[91] for a managed InfoCard, and
                   the same self-issued InfoCard must be available to the
                   user's Identity Selector when the managed InfoCard is
                   submitted to a Relying Party. This self-issued InfoCard
                   does not need to be separately registered using
                   dacs_infocard(8)[101].

               kerberos
                   This is the Kerberos V5 credential type. This
                   authentication credential type is currently unsupported.

                   Note
                   Although the specification allows an ordered list of STS
                   endpoints to appear, at present only a single endpoint may
                   be configured.

           INFOCARD_STS_CACERTFILE (Required1-C)
               This directive, which is required by
               dacs_managed_infocard(8)[91], specifies the filename of the
               certificate authority's PEM-encoded X.509 certificate for
               INFOCARD_STS_CERTFILE[106].

                   Note
                   File permissions and ownership must be set appropriately to
                   allow run-time access.

           INFOCARD_STS_CERTFILE (Required1-C)
               This directive, which is required by dacsinfocard(1)[107],
               dacs_infocard(8)[101], and dacs_managed_infocard(8)[91],
               specifies the filename of the PEM-encoded X.509 certificate for
               the Secure Token Service provided by dacs_sts(8)[90].

                   Note
                   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.

           INFOCARD_STS_KEYFILE (Required1-C)
               This directive, which is required by dacsinfocard(1)[107],
               local_infocard_authenticate[108], dacs_infocard(8)[101],
               dacs_managed_infocard(8)[91], and dacs_sts(8)[90], specifies
               the filename of the key for the X.509 certificate specified by
               INFOCARD_STS_CERTFILE. If this file is password protected,
               INFOCARD_STS_KEYFILE_PASSWORD[109] must be configured.

                   Note
                   File permissions and ownership must be set appropriately to
                   allow run-time access.

           INFOCARD_STS_KEYFILE_PASSWORD (Required1-C)
               If INFOCARD_STS_KEYFILE[110] is encrypted, this directive is
               required to specify the password.

           INFOCARD_STS_PASSWORD_METHOD (Required1-C)
               If the username/password credential type is needed by a managed
               InfoCard, dacs_sts(8)[90] requires this directive to specify
               how the username and password are to be validated:

               empty
                   The password is no password at all (i.e., the empty
                   string). If a password is given, authentication will fail.

               ignore
                   Any password string, including no password at all (i.e.,
                   the empty string), is acceptable.

               sts
                   The given password string must exactly match the
                   authentication-time value of the configuration variable
                   infocard_sts_password.

               account:id
                   The given username and password must be valid relative to
                   the specified DACS authentication module identified by the
                   Auth clause label id, which must be enabled and configured
                   as per dacs_authenticate(8)[50]. (Note: This form is
                   currently unsupported.)

           INFOCARD_STS_RP_ENDPOINT (Optional)
               This directive causes dacs_sts(8)[90] 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's AppliesTo element (apparently the URL of
               the Relying Party's 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
               INFOCARD_REQUIRE_APPLIES_TO[111]. The syntax for this directive
               is identical to that of INFOCARD_AUDIENCE[112]. Although the
               Relying Party's server certificate can be provided with the
               identification material in the token request, it is not
               currently accessible to this directive.

           INFOCARD_STS_URL (Required1-C)
               This directive, used by dacs_managed_infocard(8)[91],
               dacs_mex(8)[104], and dacs_sts(8)[90], specifies the URL of the
               Secure Token Service for managed InfoCards.

           INFOCARD_TOKEN_DRIFT_SECS (Optional1)
               A security token (produced by dacs_sts(8)[90], 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's clock may be faster
               or slower than the IP/STS's 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's clock may be too fast or too slow. If
               the directive's value is zero, or if the directive is not
               configured, a compile time default value is used (currently,
               300 seconds). If the directive's value is "disable", the
               validity test is suppressed.

           INFOCARD_TOKEN_ISSUER (Required1-C)
               This directive, used by dacs_managed_infocard(8)[91] and
               dacs_sts(8)[90], 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.

                   Note
                   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's issuer parameter), it seems
                   that the INFOCARD_TOKEN_ISSUER is ignored by an Identity
                   Selector in preference to the name in the Identity
                   Provider's SSL certificate. It has been noted that if a
                   Relying Party uses a wildcard certificate[113], an Identity
                   Selector may have trouble matching the issuer parameter in
                   an HTML OBJECT request with an InfoCard; it may be
                   necessary for the Relying Party to specify the value of the
                   issuer parameter as the empty string.

           INFOCARD_TOKEN_LIFETIME_SECS (Optional1)
               This optional directive specifies the lifetime, in seconds, of
               a secure token created by dacs_sts(8)[90]. 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's validity window is outside of its clock's current
               value.

           INFOCARD_TOKEN_MAX_LENGTH (Optional1)
               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).

           INFOCARD_USERNAME_SELECTOR (Optional1)
               This directive determines how the DACS username is selected for
               a self-issued InfoCard during registration by
               dacs_infocard(8)[101]. The resulting identity is relative to
               the current jurisdiction[46]; 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:

               credentials
                   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.

               email
                   The username is obtained from the email address field of
                   the InfoCard; the email address must be a syntactically
                   valid username (see dacs(1)[76]).

               webpage
                   The username is derived from the web page URL field of the
                   InfoCard; this is not currently implemented. (see
                   dacs(1)[76]).

           JURISDICTION_NAME (Required1)
               The name of the jurisdiction. The syntax is the same as for
               FEDERATION_NAME[55]: an alphabetic followed by zero or more
               alphanumerics, '-' (hyphens), or '_' (underscores). Note that
               periods are not permitted. By convention, this name is in
               all-caps, Please see dacs(1)[76] for additional information.
               Example: METALOGIC

           LOGINGEN_FILE (Optional1)
               Reserved for future use. (Used with the DACS logingen utility,
               this directive gives the full pathname of the template file.)

           LOGINGEN_PROG (Optional1)
               Reserved for future use. (Used with the DACS logingen utility,
               this directive specifies a program which will read
               LOGINGEN_FILE on its stdin and write the filtered output to
               stdout.)

           LOG_FILE (Optional1)
               DACS uses the LOG_FILE directive to identify the primary file
               to which it should write log information.  DACS performs
               directory name interpolation on the pathname string using a
               syntax and method similar to Apache's mod_vhost_alias[8] module
               (see String Interpolation[24]).

               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, syslog(3)[114] is used, with an
               ident argument of "dacs" and a facility of "user". Each DACS
               logging level is mapped to the corresponding syslog level, with
               the trace level mapped to syslog's debug level.

               While DACS is starting and before it reads and processes its
               configuration files, this directive is not yet available to it;
               until DACS 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 DACS is built (the default is equivalent to
               ${Conf::DACS_HOME}/logs/error_log). If DACS_LOG is unusable,
               stderr is used.

           LOG_FILTER (Stack)
               This directive configures a fine-grained way of specifying
               which messages will be written compared to the LOG_LEVEL[115]
               directive. The directive, which may be repeated, selects the
               types of events that DACS should 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.

               Because this directive is in the Stack category[13], "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.

               The syntax is one of:

                   LOG_FILTER "type flag[,flag]* level name [[+|-]file]"
                   LOG_FILTER "any flag[,flag]* level [[+|-]file]"

               The type, 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 name is to be matched against. If type is
               filename, for instance, it means that for this filter to be
               applicable to a particular log message, the name must match the
               filename from which the log message is generated.

               A list of comma-separated, case-insensitive modifier flags
               specifies how matching of type is done against name. A flag can
               have the value exact, regex, icase, sensitive, user, audit, or
               normal.

               The name is matched against type case sensitively, unless the
               icase flag is present. Matching is performed using
               regex(3)[116] 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).

               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 print()[117] and printf()[118]
               functions.

               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 LOG_SENSITIVE[119]
               directive can change the default to enable sensitive messages.

               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.

               Assuming the type and level do not deselect the message, here
               are some example cases:

               ·   a message without any attributes will be logged provided
                   the audit flag is not specified

               ·   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

               If the directive's value begins with the keyword any, the
               filter matches any source, so there is no name and the modifier
               flags related to matching name are ignored.

               In order of increasing importance and decreasing amount of
               detail, level is one of the following case-insensitive
               keywords:

               ·   trace (or tracing, least important messages)

               ·   debug (or debugging)

               ·   info

               ·   notice (or notices)

               ·   warn (or warning or warnings)

               ·   error (or errors)

               ·   critical (or crit)

               ·   alert (or alerts)

               ·   emerg (or emergency, most important messages)

               Any log message having a lower importance than level 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 Apache and
               syslog(3)[114].

               The file field, which is optional, is used instead of (or in
               addition to) LOG_FILE and interpolation is performed in the
               same way. If file is syslog, all messages matching the filter
               will be written using syslog(3) instead of to LOG_FILE. If file
               is prefixed with a '+', output will be written to both LOG_FILE
               and the expansion of file; 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 file is useful to discard unhelpful messages.

               Without regard to how LOG_LEVEL and LOG_SENSITIVE are
               configured, this directive says that all messages generated by
               any function located within the DACS source file named crypto.c
               having a level of at least debug, should be logged, including
               those marked as sensitive:

                   LOG_FILTER 'filename exact,sensitive debug crypto.c'

                   Tip
                   The directive:

                       LOG_FILTER 'any audit trace +syslog'

                   causes all log messages with the audit modifier having
                   level trace or higher to be written to both syslog(3) and
                   LOG_FILE. If you want to use the syslog feature in this
                   way, you will need a section in the syslog(3) configuration
                   file (typically /etc/syslog.conf) that looks something like
                   the following, depending on the flavour of syslog(3) that
                   your system uses:

                       !dacs
                       *.*        /usr/local/dacs/logs/audit_log

                   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 DACS
                   installation directory:

                       LOG_FILTER 'any audit,sensitive TRACE +%bD/logs/Audit_log'

                   By removing the '+' character, the log messages would not
                   be written to LOG_FILE.
               Please refer to dacs(1)[120] for general information about
               logging.

           LOG_FORMAT (Optional1)
               This directive is used to specify the format of log messages
               produced by DACS. Interpolation is controlled by printf-like
               format specifiers, as follows:

               %%
                   Insert a literal percent character

               %a
                   Insert the application name, which is typically the
                   basename of argv[0].

               %c
                   Insert the value of a per-process message counter, which is
                   then incremented.

               %F
                   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 ("-").

               %fn
                   Interpolate the federation name.

               %fd
                   Interpolate the federation domain.

               %j
                   Interpolate the jurisdiction name.

               %l
                   Interpolate the log level of the message.

               %p
                   Interpolate the process id of the process generating the
                   message.

               %sF
                   Interpolate the name of the function generating the
                   message.

               %sf
                   Interpolate the name of the file generating the message.

               %sl
                   Interpolate the line number within the file that is
                   generating the message.

               %sm
                   Interpolate the name of the module generating the message.

               %sp
                   Interpolate the name of the program generating the message.

               %t
                   Interpolate the current time and date.

               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.

           LOG_LEVEL (Optional1)
               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 LOG_FILTER[121]
               directive it overrides this behaviour, however.

               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
               LOG_FILTER[121] directive for additional information.

               The LOG_LEVEL overrides the compile-time default, which is
               obtained using the LOG_DEFAULT_LEVEL symbol.

               The "verbose" command line flag (-v) or the VERBOSE_LEVEL
               directive overrides this directive, which are in turn
               overridden by the -t 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.

               Also see debug_dacs[122].

           LOG_SENSITIVE (Optional1)
               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).

                   Note
                   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., Samba or
                   OpenLDAP), Apache (including mod_auth_dacs), or the
                   operating system. For example, requests for CGI programs
                   invoked using the GET method will be logged in the Apache
                   Access Log, and the request's query string will typically
                   be printed; password parameters may be present in the log
                   (see mod_log_config[123] 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 syslog(3)[114]) may be visible to an
                   attacker.

           NAME_COMPARE (Optional1)
               This directive sets the default method used to compare DACS
               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 user() function (dacs.exprs(5)[20]) for
               details.

                   Security
                   The selected comparison method applies to all components of
                   DACS names; if this is not desired, the strtr() function
                   might be helpful. Note that this directive does not alter
                   the DACS name determined by authentication, only the way
                   the name is compared. While it's 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.

                   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.

                   The recommended practice is to not define NAME_COMPARE or
                   set it to case because of its system-wide effects. When
                   needed, use the user() function with an appropriate
                   comparison method argument.

           NOTICES_ACCEPT_HANDLER (Optional1)
               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.

           NOTICES_ACK_HANDLER (Optional1)
               This directive provides the URL of the notice acknowledgement
               handler, which is the program that receives a user's 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.

           NOTICES_DECLINE_HANDLER (Optional1)
               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.

           NOTICES_NAT_NAME_PREFIX (Optional1)
               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.

           NOTICES_SECURE_HANDLER (Optional1)
               By default, dacs_notices(8)[124] 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 dacs_notices'
               Secure Mode[125] of operation.

           NOTICES_WORKFLOW_LIFETIME_SECS (Optional1)
               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.

           PAMD_HOST (Optional1)
               When local_pam_authenticate[126] is used, this directive is
               required to specify the domain name or IP address of the host
               where pamd(8)[127] is executed.

           PAMD_PORT (Optional1)
               When local_pam_authenticate[126] is used, this may be used to
               specify the port number or service name on PAMD_HOST where the
               pamd(8)[127] server accepts connections. This directive can be
               overridden on the pamd 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.

           PASSWORD_CONSTRAINTS (Optional1)
               This directive describes requirements that must be met by new
               passwords created by dacs_passwd(8)[128], other than when used
               by a DACS administrator. In other situations, where a DACS
               administrator must be running the program (such as with
               dacspasswd(1)[129] or dacstoken(1)[130]), a warning message is
               produced if a new, non-conforming password or PIN is set but
               the password can still be used.

               This directive's syntax is also used by the PASSWORD_AUDIT[131]
               directive, which may appear in an Auth clause.

               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 constraint type:

               ·   L refers to the minimum length of a password, in
                   characters;

               ·   C is the minimum number of characters from each case that
                   must be present (e.g., 3C means a password must have at
                   least three upper case characters and three lower case
                   characters);

               ·   D is the minimum number of digits (0-9) that must be
                   present;

               ·   and P is the minimum number of punctuation characters (see
                   ispunct(3)[132]) that must be present.

               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.

                   Security
                   No check is made for constraints that are impossible to
                   satisfy.

               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:

                   PASSWORD_CONSTRAINTS "8L,1D,1C,0P"

           PASSWORD_DIGEST (Optional1)
               By default, SHA-1 is used as the secure hash function by
               dacstoken(1)[130], dacspasswd(1)[129], dacstoken(1)[130],
               dacs_passwd(8)[128], and dacs_admin(8)[133] for computing
               password digests. The value of this directive can be (case
               insensitively):

               CRYPT
                   for the Unix crypt(3)[134] function

               MD5
                   for the MD5 function[135] (deprecated).

               SHA1
               SHA224
               SHA256
               SHA384
               SHA512
                   , , , , for one of the variants of the Secure Hash Standard
                   (FIPS 180-3[136]).

               The system crypt() 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 the other
               digest algorithms use all of the characters and impose no
               maximum password length. .sp The digest algorithm used is
               stored with the password entry, so the algorithm can be changed
               without voiding pre-existing passwords.

           PASSWORD_OPS_NEED_PASSWORD (Optional1)
               Ordinarily, dacspasswd(1)[129] will not allow password
               maintenance operations (other than listing) unless the user has
               authenticated as an ADMIN_IDENTITY[137] or provides a valid
               password for the username being administered (one that was
               created by dacspasswd(1)[129]). If this directive is "no", a
               password is not required and dacspasswd will assume that all
               necessary access control has already been performed.

           PASSWORD_SALT_PREFIX (Optional1)
               This string is prepended to a random salt string used when
               creating a digest of a password used by DACS in various
               contexts (e.g., dacspasswd(1)[129]). This may be of interest
               when PASSWORD_DIGEST[102] is CRYPT because some versions of
               crypt(3)[134] interpret the salt string.

           PERMIT_CHAINING (Optional1)
               If "yes", credentials exported by dacs_acs(8)[6] 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.

                   Security
                   Enabling this feature weakens security because it may allow
                   misappropriated DACS 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 dacs.acls(5)[25].

           PROXY_EXEC_DOCUMENT_ROOT (Optional1)
               Reserved for future use.

           PROXY_EXEC_MAPPER_DEFAULT_ACTION (Optional1)
               Reserved for future use.

           PROXY_EXEC_MAPPER_LOGGING (Optional1)
               Reserved for future use.

           PROXY_EXEC_MAPPER_LOG_FILE (Optional1)
               Reserved for future use.

           PROXY_EXEC_MAPPER_RULES_FILE (Optional1)
               Reserved for future use.

           PROXY_EXEC_PROG_URI (Optional1)
               Reserved for future use.

           RLINK (Optional)
               This directive, which may be repeated, is used to determine
               whether the current request includes an Rlink[138]. 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 expression[20] that is evaluated at rule-processing time,
               and the second is a VFS specification[139] for the location of
               the Rlinks (i.e., a DACS URI, an item type, or an absolute
               pathname). If the expression evaluates to a non-empty string:

               ·   the string is assumed to be an Rname[138], which is
                   relative to the VFS specification,

               ·   Rlink processing is enabled for the current request, and

               ·   no other RLINK directives are considered or evaluated.

               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:

                   RLINK '"${Args::RNAME:?}" /usr/local/dacs/rlinks'

               In the example above, the directive specifies that if the
               current request includes a non-empty argument called RNAME,
               then its value is an Rname, Rlink processing is enabled, and
               the Rlink can be found in the /usr/local/dacs/rlinks directory.

           ROLE_STRING_MAX_LENGTH (Optional1)
               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 dacs_authenticate(8)[48] for additional information
               about roles.

                   Warning
                   A role string that is too long may cause the user to
                   experience strange and possibly incorrect behaviour from
                   DACS because the browser may discard cookies produced by
                   DACS.

           SECURE_MODE (Optional1)
               This directive causes DACS to operate "insecurely" only if its
               value is "no" or "off" (case insensitive), otherwise DACS will
               use a more secure mode of operation. In secure mode, DACS
               requires all user interactions to be through SSL (HTTPS) and
               cookies will have the secure attribute. The default is "yes".
               Odd behaviour may result if interactions between DACS and a
               particular client mix http and https requests (such as when
               handlers are involved).

                   Security
                   Always use the secure mode of operation unless you fully
                   understand the consequences of disabling it. For DACS 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.

           SIGNOUT_HANDLER (Optional1)
               After dacs_signout(8)[33] successfully logs a user off, the
               subsequent action can be customized. In particular, this
               directive provides a way for the system administrator to
               redirect the user's browser, such as back to a login page.

               The following syntaxes are supported:

                1. SIGNOUT_HANDLER "[url] URL"

                   This form will cause DACS to redirect the client to the
                   specified URL, which may be a relative or absolute URL. If
                   the keyword url is absent, URL must begin with the four
                   characters http. The GET method is used. The URL may
                   contain a properly escaped query string; DACS will append
                   the following parameters, in the order given, to the URL:

                   DACS_VERSION
                       The version number of DACS (e.g., "1.4").

                   DACS_FEDERATION
                       The federation that received the service request, if
                       available.

                   DACS_JURISDICTION
                       The jurisdiction that received the service request, if
                       available.

                   The values of these parameters are URL encoded.

                2. SIGNOUT_HANDLER "[file] full-pathname"

                   This form causes the contents of the file named by
                   full-pathname 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.

                       Note
                       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.

                3. SIGNOUT_HANDLER "[message] \"message\""

                   This form causes the given message, surrounded by escaped
                   double quote characters, to be returned as HTML.

                4. SIGNOUT_HANDLER "credentials"

                   This form causes the user's remaining credentials to be
                   displayed as an HTML document. This is the default
                   behaviour.

               The optional keywords are treated case-insensitively.

           SSL_PROG (Optional1)
               The full pathname of the command used to provide an SSL
               connection for group information distribution. Currently, only
               sslclient(1)[140] is supported for this purpose.

           SSL_PROG_ARGS (Optional1)
               Additional command line arguments to be passed to SSL_PROG.

                   Note
                   This directive is "global" in that it applies to all
                   internal invocations of SSL_PROG. SSL options should
                   probably be more flexibly configurable (e.g., from within
                   Auth and Roles clauses).

           SSL_PROG_CA_CRT (Optional1)
               The full pathname of the file containing the CA certificate
               shared by this DACS federation. This is passed to SSL_PROG so
               that certificates can be validated.

           SSL_PROG_CLIENT_CRT (Optional1)
               This provides the name of a private key and certificate chain
               PEM file. Please refer to sslclient(1)'s[140] -ccf flag.

           STATUS_LINE (Optional1)
               If this directive is set to "on", dacs_acs(8)[6] will emit a
               DACS-Status-Line[141] header in the response from the server.
               The default value is "off". See the description of the DACS_ACS
               argument[49] for additional details.

           TEMP_DIRECTORY (Optional1)
               A directory where DACS can create temporary files. If the value
               is not an absolute path, the location is relative to
               DACS_HOME[142]. 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 DACS is not running.

           TOKEN_REQUIRES_PIN (Optional1)
               If set to no, then dacstoken(1)[130] does not require created
               or imported accounts to have a PIN. The default value is yes,
               and a PIN is required.

           TOKEN_HOTP_ACCEPT_WINDOW (Optional1)
               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).

           TRACE_LEVEL (Optional1)
               If assigned a non-zero value, tracing is enabled in various
               DACS services. Larger values will cause more events to be
               traced. This is intended to give an indication of the steps a
               DACS service takes during execution for debugging purposes.
               Logging information is generally written to the web server's
               log file or to a file configured into DACS at compile time.
               Also see LOG_LEVEL and VERBOSE_LEVEL.

           UNAUTH_ROLES (Optional1)
               This directive is used to assign a role descriptor string[143]
               to unauthenticated users. Association with these roles can be
               tested using the user()[144] predicate.

               If a jurisdiction configures this directive:

                   UNAUTH_ROLES "anonymous"

               then the following predicates would both return True when
               applied to an unauthenticated user:

                   user("unauth")
                   user("%:anonymous")

               A useful application of this directive is to classify
               unauthenticated users based on contextual elements. Consider
               this directive:

                   UNAUTH_ROLES from("10.0.0.0/24") ? "user" : ""

               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.

               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
               dacs_current_credentials(8)[88].

           UPROXY_APPROVED (Stack)
               This directive is used by dacs_uproxy(8)[145] 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:

                   [{'http' | 'https'} '://'] hostname [:port] [path]

               dacs_uproxy is invoked with a URI with the following syntax:

                   .../dacs_uproxy/proxied-hostname[:proxied-port][proxied-path-prefix]

               A proxied-hostname is matched against the hostname of each
               entry in the list, according to the stacked directive ordering,
               until a (case insensitive) match is found. If the
               proxied-hostname 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 port may imply. If a path is given, it is
               appended to the proxied-path-prefix.

               For example, consider the directives:

                   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"

               A request for the proxied hostname foo.example.com, such as
               this:

                   .../dacs_uproxy/foo.example.com/a/b/c.cgi

               will be forwarded by dacs_uproxy as the URI:

                   https://foo.example.com/a/b/c.cgi

               And the proxied request:

                   .../dacs_uproxy/baz.example.com/a/b/c.cgi

               will be forwarded by dacs_uproxy as the URI:

                   https://baz.example.com:8443/some/path/a/b/c.cgi

               This request would fail because there is no approved entry for
               bar.example.com:80:

                   .../dacs_uproxy/bar.example.com:80/a/b/c.cgi

           VERBOSE_LEVEL (Optional1)
               If assigned a non-zero value, debugging output is enabled in
               various DACS services. Larger values will cause more output to
               be generated. This is intended to display input arguments and
               the values of variables as a DACS service is executed, for
               debugging purposes. Logging information is generally written to
               the web server's log file or to a file configured into DACS at
               compile time. Also see LOG_LEVEL and TRACE_LEVEL.

           VERIFY_IP (Required1)
               If "yes", then the IP address in credentials must exactly match
               the IP address from which a service request is made. For
               example, if DACS 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's value is "no", this verification is not
               performed. Any other value is assumed to be a valid argument to
               the from()[146] predicate:

                   # Only credentials that were issued to an address on this subnet
                   # are acceptable
                   VERIFY_IP "10.0.0.0/24"

                   Tip
                   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
                   dacs_authenticate(8)[61] for additional information.

           VERIFY_UA (Optional1)
               If "yes", then the user agent string presented when
               authentication occurred (the USER-AGENT request header,
               exported by Apache as HTTP_USER_AGENT) must match the user
               agent string that is sent with subsequent requests using those
               credentials. This is the default. If the directive's 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's value is "disable", the
               feature is totally disabled at this jurisdiction. The feature
               is always disabled for certain internally-generated
               credentials.

                   Security
                   In typical use of DACS, this feature should be enabled
                   because it makes it somewhat more difficult for
                   misappropriated DACS 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.

                   Some user agents, including dacshttp(1)[4], Mozilla,
                   Firefox, curl, wget, and Konqueror, 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.

                   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 DACS 1.4.14.

           VFS (Stack)
               These directives are used to configure the virtual filestore
               (VFS) subsystem (see dacs.vfs(5)[147] and dacsvfs(1)[148] for
               details).

               The value of this directive (a vfs_uri) has the following
               syntax:

                   vfs_uri -> [ '[' item_type ']' ] URI

               As specified in RFC 2396[100] and RFC 3986[149], the general
               form of the URI syntax is:

                   scheme : [ // authority] [path] [query] [fragment]

               The item_type (see dacs(1)[150]) 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 DACS. Some labels are reserved and
               have predefined meaning to DACS; these are always lowercase;
               dacsconf(1)[2] can list them. Any label can be defined by a
               DACS 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
               dacspasswd(1)[129] and others), federation_keys and
               jurisdiction_keys (used by dacskey(1)[151] and others),
               revocations (used by dacs.acls(5)[25] and others), and stdin
               (used by get()[152] and others).

               Although the scheme is case-insensitive, the canonical form is
               lowercase. The authority, query, and fragment URI components
               are often absent. The query component is used to specify
               options.

               The path component of a URI has the format:

                   [ naming_context ] [ "," rel-path ]

               For paths that have a separate key relative to the naming
               context, its start is delimited by a comma.

               The scheme may be:

               dacs-db
                   A Berkeley DB[153], a hash-based database that manages a
                   collection of objects within a regular file. The item_type
                   is required because it forms the initial part of the key.

               dacs-ndbm
                   The Unix dbm(3)[154] API (includes GNU gdbm[155]), which is
                   similar to dacs-db. The item_type is required because it
                   forms the initial part of the key.

               dacs-fs
               fs
               file
                   Files and directories managed through filesystem
                   operations. Where path names a directory, each key maps to
                   a regular file within that directory.

               dacs-sqlite
                   An SQLite[156] database that manages a collection of
                   objects within a regular file. The item_type is required
                   because it is used as the SQL table name.

               http
               https
                   HTTP-based object access. For example, example.com might
                   configure access to its revocation list like this (with
                   appropriate access controls):

                       VFS "[revocations]https://example.com/dacs/revocation_list"

               dacs-kwv
                   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 field_sep whose value is the separator
                   character to use. The path component gives the name of the
                   item_type that should be used to manage the underlying
                   objects.

                   For example, components of DACS 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:

                       VFS "[password_file]dacs-fs:/usr/local/dacs/passwd"
                       VFS "[passwds]dacs-kwv:password_file"

                   To specify a space as the separator character instead of
                   the colon (which is the default), use the directives:

                       VFS "[password_file]dacs-fs:/usr/local/dacs/passwd"
                       VFS "[passwds]dacs-kwv:password_file?field_sep=+"

                   Because these are URIs, they must be properly encoded and
                   the '+' character represents a space. If the passwords are
                   to be stored in a Berkeley DB database, the directive would
                   be:

                       VFS "[passwds]dacs-db:/usr/local/dacs/passwd.db"

               dacs-kwv-subscheme
                   A concise way of composing the dacs-kwv scheme with
                   underlying objects accessed using subscheme. Currently,
                   subscheme can be fs (for dacs-fs), http, or https. For fs,
                   the path component is the absolute pathname of a file, its
                   contents having the keyword-value organization. For http
                   and https, the path 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 subscheme; if
                   options for dacs-kwv are needed, two separate URIs must be
                   used instead of this method.

                   This configuration directive is almost equivalent to the
                   pair of directives described in the example above:

                       VFS "[passwds]dacs-kwv-fs:/usr/local/dacs/passwd"

                   The following configuration directive states that the
                   password file used by dacspasswd(1)[129] is to be accessed
                   at the URL https://example.com/dacs/passwds using the
                   standard HTTP methods:

                       VFS "[passwds]dacs-kwv-https://example.com/dacs/passwds"

               dacs-vfs
                   The DACS CGI-based VFS service, dacs_vfs(8)[157], which
                   exports VFS operations on VFS objects through a web
                   service. An item type must be provided and must be
                   configured at the specified DACS 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).

                   For example, this directive causes DACS to look for
                   password entries used by local_passwd_authenticate[158] to
                   be accessed through the virtual filestore at example.com:

                       VFS "[passwds]dacs-vfs:https://example.com/cgi-bin/dacs/dacs_vfs"

               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.

                   Note
                   At present, the VFS does not implement much in the way of
                   concurrency control. Some DACS 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.

           XSD_BASE_URL (Optional1)
               When DACS 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.,

                   <foo xmlns="http://example.com/dacs/v1.4"
                         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                         xsi:schemaLocation="http://example.com/dacs/v1.4
                         http://example.com/dacs/dtd-xsd/foo.xsd">

               If XSD_BASE_URL is not configured, only the default xmlns
               attribute is emitted.

   The Auth Clause
       Each Auth clause configures an authentication module. The Auth clause
       and its directives are described in dacs_authenticate(8)[27].

       Note that the order of these clauses is significant - they are
       processed in the order in which they appear in the applicable
       configuration section.

   The Roles Clause
       Each Roles clause configures a roles module.  Roles clause and its
       directives are described in dacs_authenticate(8)[159].

       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.

   The Transfer Clause
       Each Transfer clause configures dacs_auth_transfer(8)[29] 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.

       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 groupname[76]. The attribute values must be unique
       (case-sensitively).  Transfer clause directives are described in
       dacs_auth_transfer(8)[29].

   Advanced Techniques
       Configuration processing is ordinarily quite straightforward, but to
       accommodate more complicated situations it also supports a few advanced
       techniques.

       Configuration Variables
           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 DACS expression.

               Tip
               When configuration processing begins, variables in the DACS and
               Args namespaces[14] can by referenced by configuration
               directives.

               Security
               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 DACS deployments that are exposed to the
               Internet.

               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 DACS to
               thwart security. For this reason, variables in the Args
               namespace should be referenced in configuration files only when
               specifically indicated in the documentation, or by advanced
               DACS administrators in appropriate circumstances and with
               caution.

           As each expression is evaluated to determine the value of the
           directive, a variable in the Conf namespace (see dacs.exprs(5)[14])
           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's
           value can be modified, effectively changing the value associated
           with the directive. After completion of configuration processing,
           the variables in the Conf namespace become read-only. It is these
           variables that are displayed by the -vars option of dacsconf(1)[2].

           For example, if the directive

               FEDERATION_DOMAIN   "example.com"

           is in effect when directive evaluation begins, the variable
           ${Conf::FEDERATION_DOMAIN} will be created and assigned the value
           "example.com".

           Variables within the Conf namespace[14] 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 DACS
           directive, however.

           A standard set of variables is always instantiated when available:

           APACHE_HOME
               The value of the corresponding build-time symbol

           CGI_SUFFIX
               The file name extension for CGI executables, specified at
               build-time

           DACS_CONF
               The full pathname for this jurisdiction's dacs.conf file

           DACS_CONF_SPEC
               The pathname specification template used for this
               jurisdiction's dacs.conf file

           DACS_HOME
               The value of the corresponding build-time symbol, from the path
               set by the --prefix flag or defaulting to /usr/local/dacs

                   Important
                   This directory should be writable only by an administrator.

           DACS_CGIBINDIR
               The value of the corresponding build-time symbol

           DACS_RELEASE
               The value of the the compile-time symbol DACS_VERSION_RELEASE

           DACS_BINDIR
               The location of the DACS bin directory

           DACS_SBINDIR
               The location of the DACS sbin directory

           DACS_SITE_CONF
               The full pathname for this jurisdiction's site.conf file , if
               any
                .RE

               DACS_SITE_CONF_SPEC
                   The pathname specification template used for this
                   jurisdiction's site.conf file, if any

               DACS_VERSION
                   The value of the compile-time symbol DACS_VERSION_NUMBER

               DOCUMENT_ROOT
                   Apache's DOCUMENT_ROOT environment variable

               EXE_SUFFIX
                   The file name extension for non-CGI executables

               FEDERATIONS_ROOT
                   The value of the corresponding build-time symbol

               HTTP_HOST
                   Apache's HTTP_HOST environment variable, obtained from the
                   HTTP Host request header

               JURISDICTION_URI
                   The initial part of the request URI, including scheme and
                   port number, that uniquely identifies the jurisdiction
                   receiving the service request (also see
                   JURISDICTION_URI_PREFIX)

               JURISDICTION_URI_PREFIX
                   The URI prefix that uniquely identifies the jurisdiction
                   receiving the service request (also see JURISDICTION_URI)

               OPENSSL_PROG
                   The full pathname of the openssl command, if available

               SERVER_ADDR
                   Apache's SERVER_ADDR environment variable

               SERVER_NAME
                   Apache's SERVER_NAME environment variable

               SERVER_PORT
                   Apache's SERVER_PORT environment variable

               URI_SCHEME
                   Set to https if the service request came over SSL (HTTPS ==
                   "on"), otherwise http

           Authentication and Roles
               This section unfortunately left blank.

SEE ALSO

       dacsconf(1)[2], dacs_conf(8)[3], dacs.exprs(5)[20]

BUGS

       There's 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.

AUTHOR

       Distributed Systems Software (http://www.dss.ca)

COPYING

       Copyright2003-2013 Distributed Systems Software. See the LICENSE[160]
       file that accompanies the distribution for licensing information.

NOTES

        1. dacs(1)
           http://dacs.dss.ca/man/dacs.1.html#key_concepts

        2. dacsconf(1)
           http://dacs.dss.ca/man/dacsconf.1.html

        3. dacs_conf(8)
           http://dacs.dss.ca/man/dacs_conf.8.html

        4. dacshttp(1)
           http://dacs.dss.ca/man/dacshttp.1.html

        5. dacs(1)
           http://dacs.dss.ca/man/dacs.1.html#dacsoptions

        6. dacs_acs(8)
           http://dacs.dss.ca/man/dacs_acs.8.html

        7. mod_auth_dacs
           http://dacs.dss.ca/man/mod_auth_dacs.html

        8. mod_vhost_alias
           http://httpd.apache.org/docs-2.2/mod/mod_vhost_alias.html

        9. LOG_FILE
           http://dacs.dss.ca/man/#LOG_FILE

       10. pathname()
           http://dacs.dss.ca/man/dacs.exprs.5.html#pathname

       11. Jurisdiction section's
           http://dacs.dss.ca/man/#jurisdiction_section

       12. Configuration.dtd
           http://dacs.dss.ca/man/../dtd-xsd/Configuration.dtd

       13. Stack category
           http://dacs.dss.ca/man/#directive_categories

       14. namespace
           http://dacs.dss.ca/man/dacs.exprs.5.html#variables

       15. EVAL directive
           http://dacs.dss.ca/man/#EVAL

       16. undef()
           http://dacs.dss.ca/man/dacs.exprs.5.html#undef

       17. modifier flag
           http://dacs.dss.ca/man/dacs.exprs.5.html#variable_modifiers

       18. ACS_ERROR_HANDLER
           http://dacs.dss.ca/man/#ACS_ERROR_HANDLER

       19. effective jurisdictional URIs
           http://dacs.dss.ca/man/#jurisdiction_section_uri

       20. expression
           http://dacs.dss.ca/man/dacs.exprs.5.html

       21. configuration variables
           http://dacs.dss.ca/man/#config-vars

       22. example configuration
           http://dacs.dss.ca/man/#example_dacs.conf

       23. Jurisdiction Selection by URI
           http://dacs.dss.ca/man/#selection_by_uri

       24. string interpolation
           http://dacs.dss.ca/man/#interpolation

       25. access control rules
           http://dacs.dss.ca/man/dacs.acls.5.html

       26. INIT*
           http://dacs.dss.ca/man/dacs_authenticate.8.html#INIT*

       27. Auth clause
           http://dacs.dss.ca/man/dacs_authenticate.8.html#auth_clause

       28. section merging
           http://dacs.dss.ca/man/#merging

       29. dacs_auth_transfer(8)
           http://dacs.dss.ca/man/dacs_auth_transfer.8.html

       30. Authorization Caching
           http://dacs.dss.ca/man/dacs_acs.8.html#authorization_caching

       31. dacscookie(1)
           http://dacs.dss.ca/man/dacscookie.1.html

       32. dacsauth(1)
           http://dacs.dss.ca/man/dacsauth.1.html

       33. dacs_signout(8)
           http://dacs.dss.ca/man/dacs_signout.8.html

       34. The DACS_APPROVAL environment variable
           http://dacs.dss.ca/man/dacs_acs.8.html#dacs_approval

       35. description of the ErrorDocument directive
           http://httpd.apache.org/docs-2.2/mod/core.html#errordocument

       36. redirect()
           http://dacs.dss.ca/man/dacs.exprs.5.html#redirect

       37. access control rules
           http://dacs.dss.ca/man/dacs.acls.5.html#elements

       38. Bug 3641
           http://issues.apache.org/bugzilla/show_bug.cgi?id=36411

       39. Bug 42430
           http://issues.apache.org/bugzilla/show_bug.cgi?id=42430

       40. dacs_select_credentials(8)
           http://dacs.dss.ca/man/dacs_select_credentials.8.html

       41. ACS_TRACK_ACTIVITY
           http://dacs.dss.ca/man/#ACS_TRACK_ACTIVITY

       42. SetDACSAuthPostBuffer
           http://dacs.dss.ca/man/mod_auth_dacs.html#SetDACSAuthPostBuffer

       43. SERVICE_ARGS_TRUNCATED
           http://dacs.dss.ca/man/dacs_acs.8.html#SERVICE_ARGS_TRUNCATED

       44. HTTP_AUTH
           http://dacs.dss.ca/man/#HTTP_AUTH

       45. syntactically valid username
           http://dacs.dss.ca/man/dacs.1.html#dacs_identity

       46. current jurisdiction
           http://dacs.dss.ca/man/dacs.1.html#current_jurisdiction

       47. ACS_AUTHENTICATED_ONLY
           http://dacs.dss.ca/man/#ACS_AUTHENTICATED_ONLY

       48. dacs_authenticate(8)
           http://dacs.dss.ca/man/dacs_authenticate.8.html#Roles

       49. DACS_ACS
           http://dacs.dss.ca/man/dacs_acs.8.html#dacs_acs_argument

       50. dacs_authenticate(8)
           http://dacs.dss.ca/man/dacs_authenticate.8.html

       51. on_success()
           http://dacs.dss.ca/man/dacs.exprs.5.html#on_success

       52. counter
           http://dacs.dss.ca/man/dacs.exprs.5.html#counter

       53. current federation
           http://dacs.dss.ca/man/dacs.1.html#current_federation

       54. ACS_INACTIVITY_LIMIT_SECS
           http://dacs.dss.ca/man/#ACS_INACTIVITY_LIMIT_SECS

       55. FEDERATION_NAME
           http://dacs.dss.ca/man/#FEDERATION_NAME

       56. dacs_admin()
           http://dacs.dss.ca/man/dacs.exprs.5.html#dacs_admin

       57. NAME_COMPARE
           http://dacs.dss.ca/man/#NAME_COMPARE

       58. auth_reply.dtd
           http://dacs.dss.ca/man/../dtd-xsd/auth_reply.dtd

       59. dacs_auth_reply.dtd
           http://dacs.dss.ca/man/../dtd-xsd/dacs_auth_reply.dtd

       60. AUTH_ERROR_HANDLER
           http://dacs.dss.ca/man/#AUTH_ERROR_HANDLER

       61. cookie name
           http://dacs.dss.ca/man/dacs_authenticate.8.html#credentials

       62. dacs_auth_agent(8)
           http://dacs.dss.ca/man/dacs_auth_agent.8.html

       63. ACS_CREDENTIALS_LIMIT
           http://dacs.dss.ca/man/#ACS_CREDENTIALS_LIMIT

       64. AUTH_SUCCESS_HANDLER
           http://dacs.dss.ca/man/#AUTH_SUCCESS_HANDLER

       65. mitigate the risk of information disclosure with a cross-site
           scripting (XSS) attack
           http://msdn.microsoft.com/en-us/library/ms533046%28VS.85%29.aspx

       66. are known
           http://www.webappsec.org/lists/websecurity/archive/2006-05/msg00025.html

       67. Netscape HTTP Cookies Specification
           http://web.archive.org/web/20070805052634/http://wp.netscape.com/newsref/std/cookie_spec.html

       68. RFC 2965
           http://www.rfc-editor.org/rfc/rfc2965.txt

       69. dacs.install(7)
           http://dacs.dss.ca/man/dacs.install.7.html

       70. FORMAT web service argument
           http://dacs.dss.ca/man/dacs.services.8.html#FORMAT

       71. Advanced Techniques
           http://dacs.dss.ca/man/#advanced

       72. RFC 1035
           http://www.rfc-editor.org/rfc/rfc1035.txt

       73. dacs.groups(5)
           http://dacs.dss.ca/man/dacs.groups.5.html#group_syntax

       74. dacs.conf(5)
           http://dacs.dss.ca/man/dacs.conf.5.html#jurisdiction_section_overview

       75. JURISDICTION_NAME
           http://dacs.dss.ca/man/#JURISDICTION_NAME

       76. dacs(1)
           http://dacs.dss.ca/man/dacs.1.html#naming

       77. RFC 2617
           http://www.rfc-editor.org/rfc/rfc2617.txt

       78. HTTP Authentication
           http://dacs.dss.ca/man/dacs_acs.8.html#http_authentication

       79. HTTP_AUTH_ENABLE
           http://dacs.dss.ca/man/#HTTP_AUTH_ENABLE

       80. ACS_PRE_AUTH
           http://dacs.dss.ca/man/#ACS_PRE_AUTH

       81. see below
           http://dacs.dss.ca/man/#http_auth_syn2

       82. authentication styles
           http://dacs.dss.ca/man/dacs_authenticate.8.html#STYLE

       83. chmod(2)
           http://www.freebsd.org/cgi/man.cgi?query=chmod&apropos=0&esektion=2&emanpath=FreeBSD+9.1-RELEASE&format=html

       84. dacs_prenv(8)
           http://dacs.dss.ca/man/dacs_prenv.8.html

       85. dacsexpr(1)
           http://dacs.dss.ca/man/dacsexpr.1.html

       86. encode()
           http://dacs.dss.ca/man/dacs.exprs.5.html#encode

       87. LDAP authentication
           http://dacs.dss.ca/man/dacs_authenticate.8.html#local_ldap_authenticate

       88. dacs_current_credentials(8)
           http://dacs.dss.ca/man/dacs_current_credentials.8.html

       89. regex(3)
           http://www.freebsd.org/cgi/man.cgi?query=regex&apropos=0&esektion=3&emanpath=FreeBSD+9.1-RELEASE&format=html

       90. dacs_sts(8)
           http://dacs.dss.ca/man/dacs_sts.8.html

       91. dacs_managed_infocard(8)
           http://dacs.dss.ca/man/dacs_managed_infocard.8.html

       92. XML Schema Part 2: Datatypes Second Edition
           http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/datatypes.html#dateTime

       93. INFOCARD_CARD_LIFETIME_SECS
           http://dacs.dss.ca/man/#INFOCARD_CARD_LIFETIME_SECS

       94. VFS URI
           http://dacs.dss.ca/man/#VFS

       95. CARD_IMAGE_URL
           http://dacs.dss.ca/man/dacs_managed_infocard.8.html#CARD_IMAGE_URL

       96. INFOCARD_CARD_DATETIME_EXPIRES
           http://dacs.dss.ca/man/#INFOCARD_CARD_DATETIME_EXPIRES

       97. INFOCARD_CARDID_BASE_URL
           http://dacs.dss.ca/man/#INFOCARD_CARDID_BASE_URL

       98. INFOCARD_CARD_OUTPUTDIR
           http://dacs.dss.ca/man/#INFOCARD_CARD_OUTPUTDIR

       99. INFOCARD_CARDID_SUFFIX
           http://dacs.dss.ca/man/#INFOCARD_CARDID_SUFFIX

       00. RFC 2396
           http://www.rfc-editor.org/rfc/rfc2396.txt

       01. dacs_infocard(8)
           http://dacs.dss.ca/man/dacs_infocard.8.html

       02. PASSWORD_DIGEST
           http://dacs.dss.ca/man/#PASSWORD_DIGEST

       03. INFOCARD_IP_PRIVACY_URL
           http://dacs.dss.ca/man/#INFOCARD_IP_PRIVACY_URL

       04. dacs_mex(8)
           http://dacs.dss.ca/man/dacs_mex.8.html

       05. INFOCARD_STS_PASSWORD_METHOD
           http://dacs.dss.ca/man/#INFOCARD_STS_PASSWORD_METHOD

       06. INFOCARD_STS_CERTFILE
           http://dacs.dss.ca/man/#INFOCARD_STS_CERTFILE

       07. dacsinfocard(1)
           http://dacs.dss.ca/man/dacsinfocard.1.html

       08. local_infocard_authenticate
           http://dacs.dss.ca/man/dacs_authenticate.8.html#local_infocard_authenticate

       09. INFOCARD_STS_KEYFILE_PASSWORD
           http://dacs.dss.ca/man/#INFOCARD_STS_KEYFILE_PASSWORD

       10. INFOCARD_STS_KEYFILE
           http://dacs.dss.ca/man/#INFOCARD_STS_KEYFILE

       11. INFOCARD_REQUIRE_APPLIES_TO
           http://dacs.dss.ca/man/#INFOCARD_REQUIRE_APPLIES_TO

       12. INFOCARD_AUDIENCE
           http://dacs.dss.ca/man/#INFOCARD_AUDIENCE

       13. wildcard certificate
           http://wiki.cacert.org/wiki/WildcardCertificates

       14. syslog(3)
           http://www.freebsd.org/cgi/man.cgi?query=syslog&apropos=0&sektion=3&manpath=FreeBSD+9.1-RELEASE&format=html

       15. LOG_LEVEL
           http://dacs.dss.ca/man/#LOG_LEVEL

       16. regex(3)
           http://www.freebsd.org/cgi/man.cgi?query=regex&apropos=0&sektion=3&manpath=FreeBSD+9.1-RELEASE&format=html

       17. print()
           http://dacs.dss.ca/man/dacs.exprs.5.html#print

       18. printf()
           http://dacs.dss.ca/man/dacs.exprs.5.html#printf

       19. LOG_SENSITIVE
           http://dacs.dss.ca/man/#LOG_SENSITIVE

       20. dacs(1)
           http://dacs.dss.ca/man/dacs.1.html#logging

       21. LOG_FILTER
           http://dacs.dss.ca/man/#LOG_FILTER

       22. debug_dacs
           http://dacs.dss.ca/man/dacs_acs.8.html#debug_dacs

       23. mod_log_config
           http://httpd.apache.org/docs/2.2/mod/mod_log_config.html

       24. dacs_notices(8)
           http://dacs.dss.ca/man/dacs_notices.8.html

       25. Secure Mode
           http://dacs.dss.ca/man/dacs_notices.8.html#secure_mode

       26. local_pam_authenticate
           http://dacs.dss.ca/man/dacs_authenticate.8.html#local_pam_authenticate

       27. pamd(8)
           http://dacs.dss.ca/man/pamd.8.html

       28. dacs_passwd(8)
           http://dacs.dss.ca/man/dacs_passwd.8.html

       29. dacspasswd(1)
           http://dacs.dss.ca/man/dacspasswd.1.html

       30. dacstoken(1)
           http://dacs.dss.ca/man/dacstoken.1.html

       31. PASSWORD_AUDIT
           http://dacs.dss.ca/man/dacs_authenticate.8.html#PASSWORD_AUDIT

       32. ispunct(3)
           http://www.freebsd.org/cgi/man.cgi?query=ispunct&apropos=0&sektion=3&manpath=FreeBSD+9.1-RELEASE&format=html

       33. dacs_admin(8)
           http://dacs.dss.ca/man/dacs_admin.8.html

       34. crypt(3)
           http://www.freebsd.org/cgi/man.cgi?query=crypt&apropos=0&sektion=3&manpath=FreeBSD+9.1-RELEASE&format=html

       35. MD5 function
           http://www.rfc-editor.org/rfc/rfc1321.txt

       36. FIPS 180-3
           http://csrc.nist.gov/publications/fips/fips180-3/fips180-3_final.pdf

       37. ADMIN_IDENTITY
           http://dacs.dss.ca/man/#ADMIN_IDENTITY

       38. Rlink
           http://dacs.dss.ca/man/dacs_acs.8.html#rlinks

       39. VFS specification
           http://dacs.dss.ca/man/dacs.conf.5.html#VFS

       40. sslclient(1)
           http://dacs.dss.ca/man/sslclient.1.html

       41. DACS-Status-Line
           http://dacs.dss.ca/man/dacs_acs.8.html#dacs_status_line

       42. DACS_HOME
           http://dacs.dss.ca/man/#var_dacs_home

       43. role descriptor string
           http://dacs.dss.ca/man/dacs.1.html#roles

       44. user()
           http://dacs.dss.ca/man/dacs.exprs.5.html#user

       45. dacs_uproxy(8)
           http://dacs.dss.ca/man/dacs_uproxy.8.html

       46. from()
           http://dacs.dss.ca/man/dacs.exprs.5.html#from

       47. dacs.vfs(5)
           http://dacs.dss.ca/man/dacs.vfs.5.html

       48. dacsvfs(1)
           http://dacs.dss.ca/man/dacsvfs.1.html

       49. RFC 3986
           http://www.rfc-editor.org/rfc/rfc3986.txt

       50. dacs(1)
           http://dacs.dss.ca/man/dacs.1.html#gloss_item_type

       51. dacskey(1)
           http://dacs.dss.ca/man/dacskey.1.html

       52. get()
           http://dacs.dss.ca/man/dacs.exprs.5.html#get

       53. Berkeley DB
           http://www.oracle.com/database/berkeley-db/db/index.html

       54. dbm(3)
           http://www.freebsd.org/cgi/man.cgi?query=dbm&apropos=0&sektion=3&manpath=FreeBSD+9.1-RELEASE&format=html

       55. GNU gdbm
           http://www.gnu.org/software/gdbm/gdbm.html

       56. SQLite
           http://www.sqlite.org

       57. dacs_vfs(8)
           http://dacs.dss.ca/man/dacs_vfs.8.html

       58. local_passwd_authenticate
           http://dacs.dss.ca/man/dacs_authenticate.8.html#local_passwd_authenticate

       59. dacs_authenticate(8)
           http://dacs.dss.ca/man/dacs_authenticate.8.html#roles_clause

       60. LICENSE
           http://dacs.dss.ca/man/../misc/LICENSE