Insert a literal percent character

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

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

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

Insert the port number of the virtual host (SERVER_PORT)

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:

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

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

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

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

All other characters are inserted verbatim

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

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.

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

These directives may appear at most once after merging.

These directives may appear zero or more times after merging.

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.

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.

If "yes", ACS's access token mechanism will be enabled. By default, this feature is disabled. Please see Authorization Caching for details.

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 for details.

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 for details.

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

By default the lifetime of credentials is determined by the authenticating jurisdiction (which created the credentials) and recorded using a timestamp within the credentials (see AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS). Credentials with a lifetime that has elapsed have expired and are unusable. This directive allows a jurisdiction to specify an additional lifetime constraint on credentials - credentials that it receives with a timestamp before the specified date and time will be treated as expired.

This directive and ACS_CREDENTIALS_LIFETIME_SECS may both be used. They do not override or replace the default lifetime and they apply to both normal and admin credentials. If two or more types of lifetime constraints are applied, the shortest lifetime (including the default lifetime) is used to determine expiration.

The date and time must be specified in one of the following formats (see strftime(3)):

"%Y-%m-%dT%H:%M:%S"
"%Y-%m-%dT%H:%M:%S%z"
"%Y-%m-%dT%H:%M:%SZ"

"%d %b %Y %T%z"
"%d %b %Y %T %z"
"%d %b %Y %T %Z"

"%d-%b-%Y %T%z"
"%d-%b-%Y %T %z"
"%d-%b-%Y %T %Z"

"%d %b %Y %T"
"%d-%b-%Y %T"

For example:

ACS_CREDENTIALS_INVALID_BEFORE_DATETIME "20-May-2024 00:00:01"
ACS_CREDENTIALS_INVALID_BEFORE_DATETIME "2024-03-20T12:00:00"

The jurisdiction's timezone is used if none is specified. This feature depends on an appropriate level of clock synchronization at all participating jurisdictions.

This directive is similar to ACS_CREDENTIALS_INVALID_BEFORE_DATETIME except that the lifetime of credentials is expressed as the number of seconds since the credentials were created. For example, to ignore credentials older than 24 hours:

ACS_CREDENTIALS_LIFETIME_SECS "86400"

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

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 for details.

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.

Also refer to the description of the redirect() 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 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 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:

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 '\"<em>Today is</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.

If dacs_acs denies access, the given expression is evaluated just before the ACS_ERROR_HANDLER 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.

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

There are two cases. If an activity tracking cookie is not sent with the current request (see ACS_TRACK_ACTIVITY), 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), access is denied and an INACTIVITY error (909) is raised; see ACS_ERROR_HANDLER. 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.

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

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), this directive tells dacs_acs(8) what to do. The following keywords are recognized values:

Similar to the pre-authorization authentication feature configured through the HTTP_AUTH 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, credentials are created that (normally) exist only for the duration of the authorization check and which are associated with the current jurisdiction. 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. 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)). 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 argument, its value is ${Args::RNAME}.

Unlike when authentication is done through dacs_authenticate(8), 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.

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

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) if no web service request is made within a certain time period (also at any jurisdiction where it is enabled within the current federation). See ACS_INACTIVITY_LIMIT_SECS. 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) 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). Activity tracking may be enabled without enabling inactivity detection (via ACS_INACTIVITY_LIMIT_SECS). This feature depends on an appropriate level of clock synchronization at all participating jurisdictions.

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 are implied. The usernames "unauth" and "unauthenticated" are disallowed, whether qualified with a jurisdiction or not. The function dacs_admin() 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 directive.

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

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.

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

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.

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) or by setting ${Auth::CREDENTIALS_LIFETIME_SECS} (see dacs_authenticate(8)).

If dacs_authenticate(8) 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.

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

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.

If dacs_authenticate fails to authenticates a user, the given expression is evaluated just before the AUTH_ERROR_HANDLER 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}.

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.

By default, each set of credentials that is returned in an HTTP cookie is assigned a cookie name 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), dacs_auth_agent(8), and dacs_auth_transfer(8). Also see ACS_CREDENTIALS_LIMIT.

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.

If dacs_authenticate successfully authenticates a user, the given expression is evaluated just before the AUTH_SUCCESS_HANDLER 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() 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}'

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.

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

The optional keywords are treated case-insensitively.

Each use of this directive identifies a target federation and the corresponding URL of a program to invoke the TOKEN operation phase of the protocol in that federation. The federation identifier is simply a label (case-sensitive) that must be a syntactically valid federation name. Whitespace separates the federation name from the URL. Please refer to dacs_auth_transfer(8) for details.

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

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.

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". This attribute is not recognized by all browsers but these browsers should ignore it. The default is "no".

By default, DACS creates HTTP cookies with names having a particular syntax, using colon characters to separate components of the cookie's name: application name (e.g., "DACS"), federation name, jurisdiction name, and username. The strings that are used by default to terminate the first three components of the cookie name can be changed using this directive. If the directive's value is:

Any other directive value is rejected. It is not possible to escape a comma in the directive value. No terminator may be the null string. This directive is honoured in all contexts where DACS produces or parses an HTTP cookie name, such as by dacscookie(1) or dacs_notices(8). See COOKIE_SYNTAX for additional information.

Consider this directive:

COOKIE_NAME_TERMINATORS "~"

This will result in cookie names that look like:

DACS~federation-name~~[jurisdiction-name]~[username][~special]

Here is another example:

COOKIE_NAME_TERMINATORS "~,::,~,:"

This will result in cookie names that look like:

DACS~federation-name::[jurisdiction-name]~[username][:special]

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

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, RFC 2965, and RFC 6265 for details.

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) for additional information about use of the Alias directive.

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.

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

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

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

This directive is used to perform user authentication at access control time rather than in a separate sign-on step. This mode of authentication is triggered through DACS's internal implementation of HTTP Basic or Digest authentication (see RFC 2617). 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. By default, the resulting identity is associated with the current jurisdiction.

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 for additional information about this feature and how it is used. Also refer to the HTTP_AUTH_ENABLE 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:

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:

One important difference between the two mechanisms is that while the post-authorization mechanism works by redirecting the user to dacs_authenticate(8) 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 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) for details).

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

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

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:

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

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

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

Authorization: Basic Z3Vlc3Q6YXBhc3N3b3Jk

-header Authorization "Basic Z3Vlc3Q6YXBhc3N3b3Jk"

The example that follows shows how LDAP authentication 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)), 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}"

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

This directive's value must be one of:

Refer to HTTP_AUTH for additional details.

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

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.

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

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

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

Also see INFOCARD_CARD_LIFETIME_SECS.

This optional directive is used by dacs_managed_infocard(8) 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.

This optional directive is used by dacs_sts(8) 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.

This directive is required by dacs_managed_infocard(8). It is the initial part of a DACS VFS URI 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 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.

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

If a managed InfoCard generated by dacs_managed_infocard(8) 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.

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

This directive is required by dacs_managed_infocard(8). 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, 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.

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

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

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

This directive is required by dacs_managed_infocard(8) and specifies the URL of the Identity Provider's PrivacyNotice. A default notice is configured.

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

This optional directive, which may be repeated, is used by dacs_managed_infocard(8) 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".

This directive, used by dacs_managed_infocard(8), specifies the URL of the WS-MetadataExchange responder for managed InfoCards. Also see dacs_mex(8).

Used optionally by dacs_managed_infocard(8), 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)) 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:

Used optionally by dacs_managed_infocard(8), 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.

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

This directive, which is required by dacs_managed_infocard(8), specifies the filename of the certificate authority's PEM-encoded X.509 certificate for INFOCARD_STS_CERTFILE.

This directive, which is required by dacsinfocard(1), dacs_infocard(8), and dacs_managed_infocard(8), specifies the filename of the PEM-encoded X.509 certificate for the Secure Token Service provided by dacs_sts(8).

This directive, which is required by dacsinfocard(1), local_infocard_authenticate, dacs_infocard(8), dacs_managed_infocard(8), and dacs_sts(8), 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 must be configured.

If INFOCARD_STS_KEYFILE is encrypted, this directive is required to specify the password.

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

This directive causes dacs_sts(8) 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. The syntax for this directive is identical to that of INFOCARD_AUDIENCE. 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.

This directive, used by dacs_managed_infocard(8), dacs_mex(8), and dacs_sts(8), specifies the URL of the Secure Token Service for managed InfoCards.

A security token (produced by dacs_sts(8), 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.

This directive, used by dacs_managed_infocard(8) and dacs_sts(8), 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.

This optional directive specifies the lifetime, in seconds, of a secure token created by dacs_sts(8). 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.

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

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

The name of the jurisdiction. The syntax is the same as for FEDERATION_NAME: 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) for additional information. Example: METALOGIC

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

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

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 module (see String Interpolation).

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

This directive configures a fine-grained way of specifying which messages will be written compared to the LOG_LEVEL 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, "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) 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() and printf() 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 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:

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:

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

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'

LOG_FILTER 'any audit trace +syslog'

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

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

Please refer to dacs(1) for general information about logging.

This directive is used to specify the format of the string that prefixes log messages produced by DACS. Interpolation is controlled by printf-like format specifiers, as follows:

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.

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 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, and trace is said to be the highest (or greatest) logging level. Refer to the LOG_FILTER directive for additional information.

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

By default, informational log messages are emitted almost immediately when most DACS web services begin execution. To suppress these messages, without regard to any other logging configuration, build DACS with --enable-hush-startup-logging.

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.

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

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

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.

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.

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.

The default prefix ("application name" component) of the name of the HTTP cookie bearing a notice acknowledgement token is "NAT-DACS". This directive can be used to override the default. This prefix may not contain the string used to terminate the cookie name's application name component (refer to COOKIE_NAME_TERMINATORS).

By default, dacs_notices(8) 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 of operation.

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.

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

When local_pam_authenticate is used, this may be used to specify the port number or service name on PAMD_HOST where the pamd(8) 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.

This directive describes requirements that must be met by new passwords created by dacs_passwd(8), 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) or dacstoken(1)), 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 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:

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.

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"

This directive specifies the cryptographic hash function or key derivation function used by dacspasswd(1), dacs_passwd(8), dacstoken(1), dacs_token(8), and dacs_admin(8) for computing password digests. The same specification syntax described here is used in other contexts throughout DACS where a digest function needs to be parameterized. Not all digest functions can be used in all contexts, however (see dacs(1)). By default, SHA-512 is used. Prior to version 1.4.34, the default was SHA-1.

In most cases only the name of the function is required, but functions that are parameterized (e.g., SCRYPT) require all configurable variables to be provided - there are no defaults.

The syntax for specifying a cryptographic digest is as follows:

digest-descriptor ::= dn ws* [ '[' arg-list ']' ]
arg-list ::= name '=' value [, arg-list ]

A digest-descriptor is a digest name (dn), optionally followed by whitespace, optionally followed by an argument string (arg-list) within square brackets. The argument string consists of one or more name=value pairs, separated by a comma. The order of the pairs is not significant. A name may not appear more than once and an unrecognized parameter name is not allowed. Nothing can follow the closing square bracket. Whitespace may precede a name, but everything following the '=' is part of the value. The value ends at a comma or the closing bracket, so embedded whitespace is possible (but should be avoided). Whitespace following a comma is ignored. A value may be surrounded by single or double quotes, but escaping is not allowed. Examples:

PASSWORD_DIGEST "scrypt[N=1024, r='8', p=16, dklen=32]"
PASSWORD_DIGEST "sha512/t[t=72]"
PASSWORD_DIGEST "pbkdf2[a=sha256,count=4098, dklen=20]"

The digest name is matched against available password digest functions case-insensitively. Non-consecutive hyphens, underscores, and slashes in the digest name are treated as equivalent separators. A separator may be omitted if doing so would not join two digits. An initial or trailing separator is disallowed. For example:

"Sha224" matches "SHA-224"
"SHA/512" matches "SHA-512"
"pbkdf2sha512" matches "PBKDF2-SHA512"

Use the digests subcommand of dacs(1) to list available algorithms and checkdigest to validate a digest descriptor:

% dacs digests
% dacs checkdigest "pbkdf2[a=sha256,count=80000,dklen=32]"

The following cryptographic digest algorithms are available:

The following password-based key derivation algorithms are available:

The PBKDF2, scrypt, and Argon2 functions should be carefully parameterized to be computationally intensive and memory intensive, if applicable, for the platform on which the password-based authentication module is run. The goal is to make password hashing unavoidably inefficient. This makes it more difficult for an attacker that accesses a copy of a password file to guess passwords because each guess takes longer or requires more resources than a comparatively efficient algorithm. For additional information about these algorithms and their parameters, see argon2(), pbkdf2(), and scrypt().

The digest algorithm and parameters used are stored with a password entry when the password is set or changed. The algorithm or its parameters can therefore be reconfigured without voiding any pre-existing password entries. As processing power continues to increase, the strength of the configured PASSWORD_DIGEST should periodically be increased. An administrator can determine the digest method used for each password entry (see dacspasswd(1)), and a user that has an entry that employed a relatively weak method should be asked to re-register his password.

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 all other algorithms use all of the characters and impose no maximum password length.

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

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)). This may be of interest when PASSWORD_DIGEST is CRYPT because some versions of crypt(3) interpret the salt string.

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

Reserved for future use.

Reserved for future use.

Reserved for future use.

Reserved for future use.

Reserved for future use.

Reserved for future use.

This directive, which may be repeated, is used to determine whether the current request includes an Rlink. 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 that is evaluated at rule-processing time, and the second is a VFS specification 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:

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.

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) for additional information about roles.

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/TLS (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).

When dacs_signout(8) terminates, provided a fatal error was not encountered, the subsequent action can be customized using this directive. For instance, the system administrator can ask for the user's browser to be redirected to a login page. This capability can also be used to construct a chain of requests to signout a user from multiple federations.

The following syntaxes are supported:

The optional keywords are treated case-insensitively.

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

Additional command line arguments to be passed to SSL_PROG.

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.

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

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

A directory where DACS can create temporary files. If the value is not an absolute path, the location is relative to DACS_HOME. 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. Read and write access to this directory must be restricted to DACS.

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

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

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.

This directive is used to assign a role descriptor string to unauthenticated users. Association with these roles can be tested using the user() 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).

This directive is used by dacs_uproxy(8) 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

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.

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

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

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.

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

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

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

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

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

The item_type (see dacs(1)) 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) 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) and others), federation_keys and jurisdiction_keys (used by dacskey(1) and others), revocations (used by dacs.acls(5) and others), and stdin (used by get() 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:

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.

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., https://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 value of the corresponding build-time symbol

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

The location of the DACS bin directory

The value of the corresponding build-time symbol

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

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

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

The value of the compile-time symbol DACS_VERSION_RELEASE (e.g., "1.4.50")

The location of the DACS sbin directory

The full pathname for this jurisdiction's site.conf file

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

The value of the compile-time symbol DACS_VERSION_NUMBER (e.g., "1.4")

Apache's DOCUMENT_ROOT environment variable

The file name extension for non-CGI executables

The value of the corresponding build-time symbol

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

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)

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

The full pathname of the openssl command, if available

Apache's SERVER_ADDR environment variable

Apache's SERVER_NAME environment variable

Apache's SERVER_PORT environment variable

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