Provided by: dacs_1.4.38a-2build1_amd64 
NAME
dacs - a distributed access control system
SYNOPSIS
dacs [-v | --verbose] [--checkdigest digest-desc] [--dumpenv] [--digests [digest-name]] [--license]
[--version]
dacs dacs-command [dacsoptions[1]] [...]
dacs-command [-u uri-prefix | -uj jurisdiction-name | -un | -up jurisdiction-name | -us] [-c dacs.conf]
[-sc site.conf] [-ll logging-level] [-format fmt] [-q] [-t] [-Dname=value]
[-v | --verbose] [--checkdigest digest-desc] [--digests [digest-name]] [--dumpenv]
[--enable-dump] [--license] [--std] [--version]
DESCRIPTION
This program is part of the DACS suite.
DACS is a general-purpose, Web-based authentication and access control system. It provides single sign-on
functionality and flexible access control to content and services provided by web servers. DACS consists
of an Apache module (mod_auth_dacs[2]) through which Apache communicates with DACS to make access control
decisions, a suite of CGI programs that provide DACS web services, and a collection of utility commands
that provide various support and administrative functions for DACS. Some of these utilities, such as
dacshttp(1)[3] and sslclient(1)[4], are completely general-purpose.
The DACS access control engine and authentication components can also be used from the command line,
within a CGI environment or completely independently of the Web.
For important information about DACS, including installation instructions, please see dacs.readme(7)[5]
and dacs.install(7)[6].
About DACS
NO WARRANTY
This software is provided by Dss "as is" and any express or implied warranties, including, but not
limited to, the implied warranties of merchantability, fitness for a particular purpose, or
non-infringement, are disclaimed. In no event shall Dss be liable for any direct, indirect,
incidental, special, exemplary, or consequential damages (including, but not limited to, procurement
of substitute goods or services; loss of use, data, or profits; or business interruption) however
caused and on any theory of liability, whether in contract, strict liability, or tort (including
negligence or otherwise) arising in any way out of the use of this software, even if advised of the
possibility of such damage.
By convention, the names of all DACS web services begin with the prefix "dacs_" (e.g., dacs_conf).
Starting with release 1.4.17, all commands that implement DACS functionality begin with the prefix "dacs"
(e.g., dacsconf). Many DACS web services have command analogues. The names of web services that are used
internally by DACS (i.e., they are never called directly by users) begin with "local_" (e.g.,
local_passwd_authenticate). General-purpose web services and commands do not follow a naming convention,
other than not using any of the previously mentioned prefixes.
The document type definitions (DTDs) that are maintained in the dtd-xsd directory are used to document
file formats or describe the arguments to a DACS web service or its reply. In the current implementation,
these DTD files are not used during XML validation. Attributes of type CDATA may have additional
constraints on their values; consult the relevant documentation. The files are technically not valid
DTDs, because they lack a document type declaration (DOCTYPE); an appropriate DOCTYPE is generated
programmatically at the time a DTD is emitted.
Important
DACS does not prevent certain kinds of attacks against web sites, such as Denial of service
attacks[7], Cross-site scripting (XSS)[8] or Cross-site request forgery (CSRF)[9]. When combined with
appropriate web site protective measures, however, DACS does provide mechanisms to make these types
of attacks more difficult.
About the Manual Pages
The technical documentation for DACS is provided as a set of manual pages. From XML source files, HTML,
nroff/troff, and nroff output collections are generated during the installation procedure. In the HTML
collection, an index page[10] includes a table of contents, links to special annotations within the
technical documentation, and lists of variables, configuration directives, and XML Document Type
Definitions.
Tip
Each HTML manual page contains a font size selection tool near its bottom. If JavaScript is enabled,
the currently selected font size can be changed and a global preference set. To choose a font size
for the current page, click on one of the four boxes. To make the current selection your preference
across manual pages, site visits, and browser sessions, click on the "set" button, which will set an
HTTP cookie. If a preference has not been set in this way (i.e., there is no cookie) and a manual
page is visited with the query parameter DACSMANFONT set to 0, 1, 2, or 3 (representing smallest to
largest point sizes), the corresponding font will be selected and the preference automatically set
(if a preference has been set, the parameter is ignored).
Tip
The output of man(1)[11] for these manual pages is likely to contain ANSI escape sequences (e.g., for
bold face mark up). For these pages to be rendered in a terminal window as intended, the pager used
for this purpose may need to be given an appropriate flag, such as -R for less(1)[12].
Areas of the documentation labeled "Security" discuss important security considerations; please pay
special attention to them. Areas labeled "Tip" provide pointers to time-saving (and sometimes
aggravation-reducing) techniques and recommended practices.
In pathnames and URLs that appear in examples, the text "..." represents text that has been omitted
because it is not relevant to the discussion at hand, or which may vary depending on configuration
details, such as where something has been installed (e.g., .../dacs/bin/dacshttp).
Unless otherwise stated, URLs used in examples are fictitious and most likely will not work. The reserved
domain name example.com is often used (RFC 2606[13]).
In instructions and examples, a '%' is generally used to signify a command line prompt:
% date
Sun Apr 1 15:33:11 PDT 2007
Sometimes another character is used to signify a prompt, however, such as when demonstrating the
interactive mode of dacsexpr(1)[14]:
> 1 + 1
2
An extended form of BNF notation[15] is used to describe syntax concisely. We hope it is both
understandable and familiar, but some inconsistencies and ambiguities may occur throughout the
documentation; this is being improved slowly. A term in a production may include a regular expression
type specification, with '+' meaning one or more occurrences of the term, and '*' zero or more
occurrences. Any one of a set of characters is specified within square brackets, and a range of
consecutive characters (in ASCII code sequence) is separated by a hyphen (e.g., [A-Za-z0-9\-_]+ means
"one or more alphabetic characters, digits, hyphens, or underscores"). In other contexts, square brackets
indicate an optional term. Single and double quotes specify literal characters. Note that XML DTDs use
their own syntax, which is somewhat different, and in some cases grammars followed in relevant RFCs are
respected for clarity or in examples.
Key Concepts
Some of the key concepts used throughout the DACS documentation are defined in this section.
account
A record, usually persistent, that associates an identity (or username) with state information (such
as whether authentication is enabled or disabled), information that is required to authenticate the
identity (such as a digest of a password string), and possibly other sign-on related information.
DACS does not provide mechanisms to administer "foreign" account types. For instance, although it can
authenticate against them, DACS cannot create, modify, delete, or list Unix or Windows accounts. Note
that DACS identities do not necessarily have a corresponding account.
authentication
The procedure by which a person or program obtains credentials that represent a DACS identity,
usually by asserting a DACS username that represents an identity and providing information that only
that identity is likely to know or possess. After successful authentication, a person or program is
said to have authenticated. DACS can interface with a wide variety of authentication methods and
provides some of its own; new methods can easily be added.
authorization
The procedure that determines, in a particular context, whether a request for a given resource or
object should be allowed. If an identity is authorized to perform a certain operation on the object,
access is granted, otherwise it is denied. Access control rules are one method of describing which
identity or identities should be granted - or denied - access to a particular resource.
Coarse-grained access control involves making a high-level decision of whether access to an object
should be granted; this is usually an all-or-nothing decision. Fine-grained access control is used
within a program to decide whether access to a lower-level resource (some data, an administrative
function, a menu) should be granted.
Note that unlike some systems, DACS does not predetermine which resources a particular user
(identity) can and cannot access; that is, an administrator does not make a list of what rights each
user has. Authorization is always determined by rule evaluation, in real time, when a user requests a
resource. The only exemptions to this are some optional features: Authorization Caching[16] and
Rlinks[17].
credentials
If authentication is successful, DACS returns information that can be used in subsequent operations
to represent the authenticated identity. Credentials contain information about the identity, such as
its name, and meta information, such as the time at which the credentials expire and become invalid.
Credentials are protected cryptographically so that they are difficult to forge or alter. They must
be kept secret, so that the identity cannot be used by anyone other than its owner, and must
accompany a request made to a server so that DACS knows who is making the request. The particular
mechanism used for this is not important provided credentials cannot be copied and reused;
transporting credentials using the payload of an HTTP cookie over an SSL/TLS connection is typical,
although sending credentials as the value of an HTTP extension header is another possibility.
Although there is no specific limit on the size of credentials as far as DACS is concerned, since
they can be encapsulated within an HTTP cookie and returned to a browser, constraints on cookies
imposed by browsers should be carefully considered.
Any jurisdiction can understand credentials produced by any other jurisdiction within the same
federation. Therefore, a user only needs to be authenticated once to access web services at any
jurisdiction using that identity.
Note that in DACS, credentials do not give their owner any rights or convey any authorization; DACS
is not a capability-based system[18]. Credentials simply represent a DACS identity.
Refer to dacs_authenticate(8)[19] for details.
current request
The event that has triggered the authorization check being processed by dacs_acs(8)[20] is referred
to as the current request. For a request for a DACS-wrapped web resource, this will be the HTTP
request that is received by the web server for the resource. In situations where dacs_acs is not
involved, such as when dacscheck(1)[21] or dacsexpr(1)[14] are used, the current request and its
context are specified by command line arguments or are obtained from the execution environment[22].
dacs_acs uses ${DACS::URI} as the path component of the current request. It is obtained from the uri
element of the current request_rec within httpd. This is the string that is used to match against
access control rules.
Other DACS components determine the current HTTP request by examining several environment variables:
HTTP_HOST (or SERVER_NAME and SERVER_PORT), REQUEST_URI, QUERY_STRING, and HTTPS.
The value of ${DACS::URI} and the path component of ${Env::REQUEST_URI} are not necessarily the same.
After an internal redirect, for example, the latter's value is from the original URL, while the
former's is from the target of the redirection.
The current request string is important because it may be used to determine the current
federation[23] and current jurisdiction[24], and because it is used when searching for the access
control rule to apply to the request.
DACS
Consisting of CGI-based web services, an Apache 2.2/2.4 module, and a collection of utilities, DACS
provides authentication and authorization functionality. Transparent, coarse-grained attribute-based
access control is available for web resources.
Programmatic, general-purpose access control is available for virtually any program (using
dacscheck(1)[21]). This is completely decoupled from Apache.
DACS administrator
An individual (or individuals) responsible for managing the operation of DACS is called a DACS
administrator (sometimes just "the administrator"). This individual is not necessarily a system
administrator (e.g., superuser or root), although a small number of optional components of DACS must
execute as user or group root. The DACS administrator need not be an Apache administrator; once
Apache has been configured for DACS it typically requires very few modifications thereafter. The DACS
administrator is responsible for configuring and testing DACS (probably installing and upgrading it,
too), managing user accounts and access control rules, safeguarding security, backing up
configuration and data files, and so on. The design of DACS allows some delegation of responsibility,
largely based on file permissions. When invoked as a web service, each of the identities configured
as a ADMIN_IDENTITY[25] is effectively a DACS administrator; in this context, the system superuser
has no significance.
DACS identity
Each authenticated user is assigned a name that consists of the name of the authenticating
jurisdiction, its federation name, and a username. Each of these naming components must be
syntactically correct. In some contexts the federation name is implicit; sometimes the jurisdiction
name is also implicit. Entities such as individuals (people, but also programs, devices, etc.),
federations, jurisdictions, and groups have names. It is the responsibility of jurisdictions to
authenticate users. The syntax, meanings, and uniqueness of names is also a jurisdictional issue, and
perhaps a federation-wide issue as well.
Each real world entity typically has a unique DACS identity, but this is left up to authenticating
jurisdictions. Two or more identities are distinct if they do not refer to the same real world
individual. Federated identity or single sign-on (SSO) is the ability to recognize a user identity
across jurisdictions and even across federations.
Important
Keep in mind that regardless of the authentication method and account information used, two
identical usernames (relative to the same jurisdiction and taking into account NAME_COMPARE[26])
are implicitly assumed to refer to the same identity by DACS. For instance, someone who
authenticated as auggie by providing the correct Unix password is virtually indistinguishable
from someone who authenticated as auggie using an Information Card. User credentials include
information about the authentication method involved in their creation and the user()[27]
function can be used to obtain this information, but it would be unwise to base identities on
this. It is strongly advised that a new DACS jurisdiction carefully develop an extensible plan
for user naming.
DACS-wrapped
A web resource is said to be DACS-wrapped if the web server responsible for the resource calls DACS
(more specifically, dacs_acs(8)[20]) to make an access control decision whenever it receives a
request for the resource.
federation
A DACS federation consists of one or more jurisdictions. The jurisdictions comprising a federation
coordinate information sharing through light-weight business practices implemented as a requirement
of membership in a DACS federation; in other words, the members of a federation typically agree to
observe certain rules of conduct to preserve overall security and so that users can obtain maximum
benefit. A federation consisting of just one jurisdiction is not unusual.
item type
An item type is a name that maps to a VFS[28] (virtual filestore) specification that configures how
and where data is stored. The level of indirection that they provide means that access control rules,
for example, can be configured to be in regular files, a Berkeley DB database, a remote database
accessed by HTTP, and so on - all that is required is that the item type acls be properly configured.
Some item types (like acls) are reserved and have special meaning to DACS, while others can be used
by a DACS administrator for other purposes. An item type name is case sensitive and consists of
alphanumerics, hyphens, and underscores, but must begin with an alphabetic character.
jurisdiction
A DACS jurisdiction is an autonomous administrative entity that authenticates its users, provides web
services, or both. It may correspond to an organization, department, web server, or virtual host.
Jurisdictions are sometimes created simply as an administrative convenience. Each jurisdiction is
assigned a unique name within a federation.
A user's home jurisdiction is a jurisdiction that can authenticate that user. In situations where a
user has multiple credentials obtained from different jurisdictions, the effective home jurisdiction
for a request depends on which credentials are selected during authorization processing.
Configuration directives are available to restrict the number of sets of credentials that may
accompany a request.
user agent
A user agent is client-side software that interacts with other software (a server application,
typically) on behalf of a user. A user is often a person but can also be software. A web browser,
which is used to interact with a web server, is an example of a user agent.
Naming
DACS needs to name a variety of things so that they can be referred to in expressions, access control
rules, configuration directives, and so on. While the URI syntax is used to name some kinds of objects
within DACS, DACS also has its own concise naming schemes.
Note
The terms current federation (current jurisdiction) and this federation (this jurisdiction) are used
in the documentation to refer to the federation (jurisdiction) associated with the configuration
context in effect while DACS processes a request.
In general, the federation-name component of a name is optional; if absent, the current federation is
assumed. Similarly, the jurisdiction-name may be elided and the current jurisdiction is implied.
Federations
Syntax:
federation-name::
Example:
DEMO::
The federation-name (usually obtained from a FEDERATION_NAME[29] configuration directive) must begin
with an alphabetic character and is followed by zero or more alphanumerics, hyphens, and underscores.
A federation-name is ordinarily treated case sensitively (but see the NAME_COMPARE[26] configuration
directive and the user()[27] function for alternate behaviours). There is no a priori limit on its
length.
The FEDERATION_DOMAIN[30] directive specifies the domain name suffix common to all jurisdictions in a
federation.
Jurisdictions
Syntax:
[[federation-name:: | [::]] jurisdiction-name:
Examples:
DEMO::DSS:
::DSS:
DSS:
The jurisdiction-name (usually obtained from a JURISDICTION_NAME[31] configuration directive) must
begin with an alphabetic character and is followed by zero or more alphanumerics, hyphens, and
underscores. A jurisdiction-name is ordinarily treated case sensitively (but see the NAME_COMPARE[26]
configuration directive and the user()[27] function for alternate behaviours). There is no a priori
limit on its length.
Users
Syntax:
[[[federation-name:: | [::]] jurisdiction-name]:username
Examples:
DEMO::DSS:auggie
::DSS:auggie
DSS:auggie
:auggie
A full DACS identity includes a federation name component and a jurisdiction name component, in
addition to the username. It is provided to DACS-wrapped programs as the value of the
DACS_IDENTITY[32] environment variable.
The username component, which is available to CGI programs as the value of the DACS_USERNAME[33]
environment variable, consists of one or more ASCII characters from the set of upper and lower case
alphabetics, digits, and the following punctuation characters:
! # $ % & ' - . ; ? @ [ ^ _ ` { }
All characters having a value less than 041 (octal) or greater than 0176 (octal) are invalid, as are
the following characters:
* , : + ( ) ~ < > = | \ / "
Notes
• In addition to the alphanumeric characters, RFC 2396[34] allows only the following characters
("pchar") to appear in the path component of a URI:
- _ . ! ~ * ' ( ) % : @ & = + $ ,
• Some valid email addresses are not valid DACS usernames. For example, *bob*@example.com,
"(bob)"@example.com, and \(bob\)@example.com are valid mailbox names as defined by RFC
822[35] (Appendix D) and discussed in RFC 3696[36] (Section 3), but both are invalid as DACS
usernames. Unless quoted, the local-part component of an email address, which precedes the
"@" character in the addr-spec, may not contain any of:
( ) < > @ , ; : \ " . [ ]
Additionally, the space and all US-ASCII control characters (octets 0 - 31) and DEL (127) are
disallowed. Without quotes, the local-part may consist of any combination of alphabetics,
digits, or any of the following characters:
! # $ % & ' * + - / = ? ^ _ ` . { | } ~
A period (".") may be used, but may not start or end the local-part, nor may two or more
consecutive periods appear. Within double quotes, any ASCII character may appear if properly
quoted (e.g., Auggie." ".O."\'".Doggie@example.com). The maximum length of the local-part is
64 characters, and the maximum length of the domain component that appears after the "@"
character is 255 characters.
There is currently no way to "quote" a DACS username, so some safe encoding method or
transformation must be applied to these names.
• DACS may create identities for internal use having username components that include
characters that are normally invalid.
• A username is case sensitive (but see the NAME_COMPARE[26] configuration directive and the
user()[27] function for alternate behaviours). There is no a priori limit on its length.
• The recommended practice is for jurisdictions to map their DACS usernames to lower case
during the authentication procedure where possible and when the mappings are unique. The
EXIT*[37] directive may be used for this purpose.
Groups
Syntax:
[[federation-name:: | [::]] %[jurisdiction-name]:groupname
A groupname must begin with an alphabetic character and may be followed by any number of
alphanumeric, hyphen ("-"), and underscore ("_") characters.
Examples:
%DEMO::DSS:friends
%::DSS:friends
%DSS:friends
%:friends
Roles and Role Descriptors
Syntax:
Role-Descriptor -> Empty-String | Role-List
Role-List -> Role | Role "," Role-List
Role -> Basic-Role | Composite-Role
Basic-Role -> [A-Za-z0-9\-_]+
Composite-Role -> Basic-Role "/" Basic-Role | Basic-Role "/" Composite-Role
Empty-String -> ""
A role descriptor string (also called a role string or a role descriptor) consists of a comma
separated list of roles. The name of a role (a Basic-Role) is constructed from upper and lower case
letters, digits, hyphens, and underscores. A Composite-Role is constructed from two or more
Basic-Role terms, separated by a slash character. Here are three examples of a role descriptor:
admin,wheel,root
admin/hardware
networks/programming,computer-science/systems/Project_X
Note
A role descriptor string contains no white space characters and may not begin or end with a comma
or slash character. Two or more consecutive commas are illegal, as are two or more consecutive
slashes.
The setvar()[38] function can be used to separate a composite role into its basic roles.
Please refer to dacs.groups(5)[39] for additional information.
Concise User Syntax
Syntax:
ident -> '{' kwv-list '}' | user
kwv-list -> kwv [',' kwv]*
kwv -> kwv-user | kwv-group | kwv-attr | kwv-ip | kwv-expires
kwv-user -> 'u=' [Q] user [Q]
kwv-group -> 'g=' [Q] groups [Q]
kwv-attr -> 'a=' [Q] attr [Q]
kwv-expires -> 'e=' [Q] expires [Q]
kwv-ip -> 'ip=' [Q] ip-addr [Q]
user -> simple-name | DACS-identity
groups -> group [',' group]*
group -> groupname | role-descriptor
attr -> any-alphabetic
ip-addr -> any-IP-addr
expires -> +rel-secs | date
where:
• Q is an optional (matched) quote character;
• whitespace may optionally precede most tokens;
• a DACS-identity is a full or abbreviated DACS identity[40]
• a simple-name is the username component of a DACS identity (i.e., without any colons);
consequently in this context a "special" name, such as auth, is treated as :auth
• role-descriptor must be a valid DACS role string and groupname must be a valid DACS group name
(see dacs_authenticate(8)[41] and dacs.groups(5)[42]);
• an IP address is expressed in the Internet standard numeric dot notation (e.g., 10.0.0.1); and
• the lifetime of credentials derived from the identity can be expressed either as a given number
of seconds (e.g, "e=+3600") or a given date in one of the following formats (see
strptime(3)[43]):
%a, %d-%b-%Y %H:%M:%S GMT
%d-%b-%Y
%b %d, %Y
%b %d
%Y-%m-%dT%H:%M:%SZ
When necessary, dates are interpreted relative to the current time or date. The lifetime is
converted to its canonical form, which is the absolute time and date in seconds since the Epoch,
based on the jurisdiction's clock. A date in the past can be specified; this might be useful for
testing, for instance. If the identity is not used to create credentials, the expiry date is
ignored, although it must be syntactically correct.
• the only supported attribute value is "a", which means that the identity should be treated as an
ADMIN_IDENTITY[25] (refer to the -admin flag of dacscheck(1)[21]).
A name expressed in the concise syntax, gives a username and, optionally, roles and attributes for
the identity. It is used by dacscheck(1)[21], for instance.
The dacs Utility
DACS utility commands are usually installed as separate binaries, but DACS can (also or instead) be built
with most of them combined into a single binary that is installed as dacs. The various utility programs
may then be run as:
% dacs dacs-command [dacsoptions] [command-options]
For example:
% dacs license
% dacs dacskey -u j1.example.com outfile
% dacs checkdigest "pbkdf2[a=sha256,count=4098, dklen=20]"
% dacs checkdigest 14
Running the dacs utility without arguments will show the list of available sub-commands.
Start-up Processing
Most DACS programs perform the following actions when they start:
1. Determine the "mode" in which they should operate; for example, if the REMOTE_ADDR environment
variable is present, programs will in general assume they should run as a web application rather than
as a utility command
2. Process a standard set of command line arguments (dacsoptions[44])
3. Set the process umask to 007 to disallow world access for any created files
4. Disable a core dump so that sensitive information cannot be revealed by examining them (but see
--enable-dump[45])
5. Refuse to operate if any configuration file cannot be found or has an error
6. For web services, make the DACS home directory the current working directory
7. If "secure mode" has been enabled, web services will only process HTTPS requests
8. Verify that the version required by a request is compatible with the version of DACS receiving the
request
9. Process any program-specific command line arguments.
DACS programs make an effort to destroy sensitive information (such as passwords) as soon as it is no
longer needed and not to write potentially sensitive information to log files unless specifically
configured to do so.
Internals
Some DACS components may call other components using HTTP (possibly over SSL/TLS, depending on
configuration). For example, authentication modules may be invoked as web services by
dacs_authenticate(8)[41]. In all cases, these "internal" HTTP calls may not result in a redirection, such
as through a 302 Found status code. Although this can sometimes be an inconvenience, it is, in part, a
security measure.
Tip
When debugging a problem that may involve an internal HTTP request (especially related to
authentication), verify that DACS is not receiving a redirect. Internal HTTP requests may also fail
mysteriously because of incorrect or incomplete configuration of SSL/TLS parameters. Internal HTTP
requests over SSL/TLS use sslclient(1)[4], as does the dacshttp(1)[3] command. If you suspect that an
https-schemed URL may not be working, debug the problem using sslclient and then dacshttp.
To maintain data consistency, DACS creates exclusive locks using the fcntl(2)[46] system call on files
written in the directory configured through the TEMP_DIRECTORY[47] directive.
Logging
Most DACS services and utilities write various kinds of messages to one or more log files. These messages
can be invaluable when trying to figure out what DACS is doing, for security audits, or to see which
DACS-wrapped resources are being accessed and in what ways.
Please refer to dacs.conf(5)[48] for information about configuration directives related to logging. An
assortment of command line flags, described below, are also related to logging.
Note
• DACS can emit log messages before configuration processing is complete and configuration
directives associated with logging are not in effect during this startup interval (see --enab
le-hush-startup-logging[49]).
• Because mod_auth_dacs[2] is an Apache module, the Apache logging directives apply to it (and not
the DACS directives) and its log messages are written to Apache log files.
• Log files can quickly become large, especially when the logging level is set to debug or trace
levels. Consider daily rotation or truncation.
• The text of a log message may occasionally span several lines.
The default value of the LOG_FORMAT[50] directive, which controls the appearance of log messages, is
defined in include/local.h as LOG_FORMAT_DEFAULT_WEB for DACS web services and LOG_FORMAT_DEFAULT_CMD for
everything else. Here is a typical log message:
[Wed Jul 12 12:37:09 2006] [trace] [83648,1060,-] [dacs_acs:"acslib"] Allow
clause grants access
Audit-Class Log Messages
In the case of audit-class messages, a string within parentheses may sometimes follow an identity, as
in the examples below. This string, called a tracker, associates log messages with a particular
origin and can be used to trace a user's sequence of service requests using log messages throughout a
federation. This can be useful when debugging, looking for security problems, or forensic analysis.
For an unauthenticated user, the tracker can only be derived heuristically, from elements of the
execution context. The user's IP address, user agent string, and SSL client certificate, when
available, are used. If two of these tracker strings differ, the requests are typically coming from
different hosts, browsers, or users, but this is not necessarily always the case. Similarly, if the
same tracker string is associated with two log messages, the service requests are not necessarily
being issued by the same user.
For an authenticated user, the tracker string consists of the heuristically-derived string, followed
by a comma, followed by a string uniquely associated with the user's credentials. This tracker has a
high probability of being unique and having a one-to-one mapping with a particular user.
Consider these (condensed) log file entries:
[Wed Jul 12 15:56:24 2006] [notice] [83963,1067,A] [dacs_acs:"authlib"]
*** Access granted to unauthenticated user (7vJLWzv5) from 10.0.0.124
for /cgi-bin/dacs/dacs_current_credentials
[Wed Jul 12 15:56:27 2006] [notice] [83965,1073,A] [dacs_acs:"authlib"]
*** Access granted to unauthenticated user (7vJLWzv5) from 10.0.0.124
for /cgi-bin/dacs/dacs_authenticate
[Wed Jul 12 15:56:27 2006] [debug] [83966,172,A] [dacs_authenticate:"authlib"]
Authentication succeeded for HOME:bobo (7vJLWzv5,wA/Pudyp3f0)
[Wed Jul 12 15:56:30 2006] [notice] [83973,1078,A] [dacs_acs:"authlib"]
*** Access granted to DSS::HOME:bobo (7vJLWzv5,wA/Pudyp3f0)
from 10.0.0.124 for /cgi-bin/dacs/dacs_current_credentials
In the first two of the log messages above, the tracker 7vJLWzv5 appears, meaning that the two
requests probably came from the same (unauthenticated) user. With the third log message, the user has
been authenticated and the tracker 7vJLWzv5,wA/Pudyp3f0 is used. Because these trackers all share the
same prefix, the first two requests probably also came from someone who authenticated as
DSS::HOME:bobo. The last request, for /cgi-bin/dacs/dacs_current_credentials, definitely came from
that user. If this user were to signout and then issue more service requests anywhere in the
federation DSS, each log message would contain the tracker 7vJLWzv5.
Security
Tracking the requests of anonymous users reliably is difficult to do well. A cookie-based
approach may do better in some situations but has its own drawbacks (such as being totally
ineffective when the user has disabled cookies).
Tracking User Activity
DACS includes a feature, enabled as a build-time option (see dacs.install(7)[51]), whereby a jurisdiction
can track the activity of all of its users (i.e., those users that authenticate at the jurisdiction).
Each successful authentication event, explicit signout event, and user-submitted web service request
event can be recorded at the user's home jurisdiction in the format defined by dacs_user_info.dtd[52].
This information can be valuable for better understanding what is happening throughout a federation,
including helping to diagnose performance and security issues. It is the basis of features like displays
of recent account activity, and it might also be used to create new capabilities, such as a concurrent
login limit or an adaptive authentication component to implement layered authentication or risk-based
authentication.
To specify where and how a home jurisdiction should maintain these records, the user_info item type must
be defined at that jurisdiction; if it is not defined, no records will be written at that jurisdiction,
although the jurisdiction will still try to send event records to other jurisdictions. For maximum
benefit, the feature should be enabled at all jurisdictions in a federation; all user activity throughout
the federation can then be logged.
If a jurisdiction wants to monitor the activity of its users at other jurisdictions, it must allow those
jurisdictions to invoke its dacs_vfs(8)[53] service by adding an appropriate access control rule.
Security
It is critical for any such rule to require the dacs_admin()[54] predicate.
Note
• Because the records are currently not keyed, at present only the file item type is supported for
this purpose. A configuration directive similar to the following would be used:
VFS "[user_info]file://${Conf::FEDERATIONS_ROOT}/${Conf::FEDERATION_DOMAIN}/${Conf::JURISDICTION_NAME}/user_info"
• The dacs_admin(8)[55] tools provides an interface to these records. It should eventually be
extended to collect and organize records found at all jurisdictions in a federation to facilitate
analysis. Because they are text files with a relatively simple format, administrators should not
find it difficult to apply common text processing tools or write short, custom programs for this
purpose. Commands analogous to last(1)[56], who(1)[57], and sa(8)[58] are being considered.
• Each jurisdiction should write records to its own place (i.e., jurisdictions should not share the
same VFS object for user_info).
• This database will grow indefinitely; an administrator is responsible for rotating or truncating
it. If previous and active sign on information is important (see
dacs_current_credentials(8)[59]), prune only the request records (i.e., the acs elements).
Another acceptable method is to discard (or archive) some proportion of older records (say, half)
and keep some of the newer records.
• The data format is subject to change.
• A directive to enable or disable this feature at run-time may be added.
• Internal administrative events are not recorded.
• Because signing off (via dacs_signout(8)[60]) is optional, the end of a session can sometimes
only be inferred or approximated from the expiry of credentials or the time of the last recorded
event.
OPTIONS
DACS programs and web services get much of their run-time configuration information by reading
configuration files and examining environment variables. Some configuration information can be provided
at compile-time. Several command line flags may be used to override default behaviour.
Note
• All dacsoptions flags are processed left-to-right and must appear before any command-specific
flag or argument. The first flag or argument that is not recognized as one of the dacsoptions
terminates the list.
• The most important dacsoptions are those that specify the location of configuration files and
identify the jurisdiction section to use within a configuration file. Depending on the program
and how it is used, configuration information may not be needed, may be optional, or may be
required.
• At most one of the command line flags to select a jurisdiction section can be specified. Refer to
dacs.conf(5)[48] for additional information on the configuration file and configuration
processing.
Many DACS utilities recognize the following standard options, which are called dacsoptions:
-c dacs.conf
This tells DACS where it can find a configuration file for the jurisdiction on whose behalf it is
acting. If this argument is not present, depending on how it was built, DACS may either try to use a
compile-time specified file or it will try to use the value of the environment variable
DACS_CONF[61]. For details, refer to Locating dacs.conf and site.conf[62].
-Dname=value
The effect of this flag is to define variable name (which must be syntactically valid) in the DACS
namespace to have the value value. Any quotes around value are retained, provided the shell has not
already stripped them off. This flag may be repeated. These variables can subsequently be tested
during configuration processing and rule processing; for example, the value of a configuration
directive might depend on the value of a dacsoptions flag. Defining a name that happens to correspond
to a dacsoptions flag has no effect other than to create the variable.
All dacsoptions flags (excluding this one) are automatically added to the DACS namespace as they are
processed. A flag that is a "singleton" (e.g., -q) is initially assigned a value of one and is
incremented on each subsequent appearance. A flag of the form -flag value is equivalent to
-D-flag=value. Unused flags are undefined; if -q is not given, ${DACS::-q} will not be defined. For
those flags that have synonyms, a variable for each synonym is created. If the name is used,
explicitly or implicitly, later values replace earlier ones.
For example, if the dacsoptions are:
-c www.example.com -v --verbose -Dfoo="baz" -ll debug -D-ll=trace
then variables will be defined as follows:
${DACS::-c} is "www.example.com"
${DACS::-v} is "2"
${DACS::--verbose} is "2"
${DACS::foo} is "\"baz\""
${DACS::-ll} is "trace"
The debugging level will be debug and not trace.
--checkdigest digest-desc
Validate the syntax of digest descriptor digest-desc, as it might appear as the value of the
PASSWORD_DIGEST[63] directive. In addition to the digest name, the given argument names and values
are checked. A numeric algorithm identifier can be given as a synonym for the algorithm name. The
descriptor is printed in canonical form.
--digests [digest-name]
With no digest-name, list information about all available cryptographic digest algorithms, otherwise
only digest-name. The information includes:
• the canonical name for the digest
• the digest's block size, in bytes ("bsize"),
• the digest size, in bytes ("dsize"),
• the internal password algorithm identifier ("alg", an unsigned integer), and
• its attributes: whether the algorithm can be used with PASSWORD_DIGEST[63] ("Password"), HMAC
constructs ("HMAC"), digital signatures ("Sign"), scrypt ("scrypt"), PBKDF2 ("PBKDF2"), if it
requires parameters ("Parameters"), whether it produces a variable-length digest ("Varlen"), and
its implementation ("OpenSSL", "DACS", or "System").
A digest size of zero also indicates that there is a variable-length output, which may depend on any
of the arguments to the digest function. After printing to stdout, the program exits immediately. For
convenience, --digest is a synonym.
--dumpenv
Print all environment variables to stdout and then exit immediately.
--enable-dump
By default, DACS web services and most commands disable core dump generation as a security
precaution. Because a core dump can be useful when debugging, this flag allows it to be created. As
programs that are allowed to produce a core dump must change to the DACS_HOME directory, core dumps
will be written there. Use this flag with care.
-format fmt
The output format is set to fmt, which is one of the following keywords (case insensitive): file,
html, json, php, plain, text, xml, xmldtd, xmlsimple, xmlschema, uri, or url. Not all output formats
are supported by all programs. This flag overrides any FORMAT[64] argument to a web service, which in
turn overrides a program's default format. The default format depends on the particular program and
way it is invoked. For additional information, refer to the description of the FORMAT argument[64].
-ll logging-level
The logging level is set to log-level, which is one of the keywords recognized by the LOG_FILTER[65]
directive.
--license
Print the license for DACS to stdout and then exit immediately.
-q
Be quiet. This is equivalent to setting the logging level to warn.
-sc site.conf
This tells DACS that it can find a configuration file for the jurisdiction on whose behalf it is
acting. If this argument is not present, depending on how it was built, DACS may either try to use a
compile-time specified file or it will try to use the value of the environment variable
DACS_CONF[61]. For details, refer to Locating dacs.conf and site.conf[62].
--std
This flags the end of the common arguments. The next command line argument, if any, is specific to
the program.
-t
Emit tracing information. This is equivalent to setting the logging level to trace. (Also see
debug_dacs[66].)
-u config-uri
This instructs DACS to use config-uri to select the jurisdiction section to use in the configuration
file. For details, refer to The Jurisdiction Section[67].
-uj jurisdiction-name
This instructs DACS to use the jurisdiction name jurisdiction-name to select the jurisdiction section
to use in the configuration file. For details, refer to The Jurisdiction Section[67].
-un
This instructs DACS not to process site.conf or dacs.conf. This may only be used with a small number
of commands, such as dacsacl(1)[68] and sslclient(1)[4].
-up jurisdiction-name
NOT IMPLEMENTED. This instructs DACS to use the jurisdiction name jurisdiction-name to select the
jurisdiction section to use in the configuration file and tells it that the web server is acting as a
forward proxy; that is, jurisdiction-name does not necessarily "own" the requested URL. For details,
refer to The Jurisdiction Section[67].
-us
This instructs DACS to use the one-and-only jurisdiction section that appears in the configuration
file. That is, the configuration file must contain exactly one jurisdiction section and that is the
one that should be used. For details, refer to The Jurisdiction Section[67].
-v
--verbose
Be more verbose, relative to the current logging level. This flag may be repeated.
--version
Print version information to stderr immediately and then exit. If the -v (--verbose) flag appeared
earlier on the command line, also print version information for each DACS source code file used by
this program that was compiled with a recognized revision identifier string. This information can be
helpful when debugging suspected build problems.
Note
Complete version information is available only for statically linked programs. Also see
dacsversion(1)[69] and dacs_version(8)[70].
Tip
If no command line flag is given to specify the jurisdiction section, the value of the environment
variable DEFAULT_JURISDICTION will be used as if given with the -uj flag. This can be particularly
useful when a host has only one jurisdiction configured because it makes it unnecessary to always
specify the jurisdiction for DACS commands.
ENVIRONMENT
SERVER_NAME, SERVER_PORT, REQUEST_URI
May be used to determine the applicable jurisdiction.
FILES
dacs.conf
site.conf
SEE ALSO
DACS manual pages[71], dacs_admin(8)[55], dacs.install(7)[6], dacs.readme(7)[5], dacs.services(8)[72]
NOTES
Whether using DACS, Apache, or both for authentication and authorization, always test that resources are
being protected according to your requirements. This is especially important when upgrading or
reconfiguring DACS or Apache.
Compatibility and interoperability with Apache authentication/authorization features and configuration
may change as Apache evolves. For a particular set of DACS-wrapped resources (e.g., URLs in the scope of
a given Location section), it is easiest, safest, and most predictable if as much as possible is
delegated to DACS rather than combining DACS with Apache authentication/authorization modules and
directives beyond the minimal configuration. Non-minimal combinations may cause DACS or Apache to
function incorrectly, so they should be avoided or used with care. This is particularly important with
respect to Apache 2.4, which has greatly expanded the number of directives associated with authentication
and authorization.
BUGS
There should be some assistance for administering user activity records[73].
AUTHOR
Distributed Systems Software (www.dss.ca[74])
COPYING
Copyright2003-2016 Distributed Systems Software. See the LICENSE[75] file that accompanies the
distribution for licensing information.
NOTES
1. dacsoptions
http://dacs.dss.ca/man/dacs.1.html#dacsoptions
2. mod_auth_dacs
http://dacs.dss.ca/man/mod_auth_dacs.html
3. dacshttp(1)
http://dacs.dss.ca/man/dacshttp.1.html
4. sslclient(1)
http://dacs.dss.ca/man/sslclient.1.html
5. dacs.readme(7)
http://dacs.dss.ca/man/dacs.readme.7.html
6. dacs.install(7)
http://dacs.dss.ca/man/dacs.install.7.html
7. Denial of service attacks
http://en.wikipedia.org/wiki/Denial-of-service_attack
8. Cross-site scripting (XSS)
http://en.wikipedia.org/wiki/Cross-site_scripting
9. Cross-site request forgery (CSRF)
http://en.wikipedia.org/wiki/Cross-site_request_forgery
10. index page
http://dacs.dss.ca/man/index.html
11. man(1)
http://www.freebsd.org/cgi/man.cgi?query=man&apropos=0&sektion=1&manpath=FreeBSD+10.3-RELEASE&format=html
12. less(1)
http://www.freebsd.org/cgi/man.cgi?query=less&apropos=0&sektion=1&manpath=FreeBSD+10.3-RELEASE&format=html
13. RFC 2606
http://www.rfc-editor.org/rfc/rfc2606.txt
14. dacsexpr(1)
http://dacs.dss.ca/man/dacsexpr.1.html
15. BNF notation
http://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form
16. Authorization Caching
http://dacs.dss.ca/man/dacs_acs.8.html#authorization_caching
17. Rlinks
http://dacs.dss.ca/man/dacs_acs.8.html#rlinks
18. capability-based system
http://en.wikipedia.org/wiki/Capabilities
19. dacs_authenticate(8)
http://dacs.dss.ca/man/dacs_authenticate.8.html#credentials
20. dacs_acs(8)
http://dacs.dss.ca/man/dacs_acs.8.html
21. dacscheck(1)
http://dacs.dss.ca/man/dacscheck.1.html
22. execution environment
http://www.freebsd.org/cgi/man.cgi?query=environ&apropos=0&sektion=7&manpath=FreeBSD+10.3-RELEASE&format=html
23. current federation
http://dacs.dss.ca/man/#current_federation
24. current jurisdiction
http://dacs.dss.ca/man/#current_jurisdiction
25. ADMIN_IDENTITY
http://dacs.dss.ca/man/dacs.conf.5.html#ADMIN_IDENTITY
26. NAME_COMPARE
http://dacs.dss.ca/man/dacs.conf.5.html#NAME_COMPARE
27. user()
http://dacs.dss.ca/man/dacs.exprs.5.html#user
28. VFS
http://dacs.dss.ca/man/dacs.conf.5.html#VFS
29. FEDERATION_NAME
http://dacs.dss.ca/man/dacs.conf.5.html#FEDERATION_NAME
30. FEDERATION_DOMAIN
http://dacs.dss.ca/man/dacs.conf.5.html#FEDERATION_DOMAIN
31. JURISDICTION_NAME
http://dacs.dss.ca/man/dacs.conf.5.html#JURISDICTION_NAME
32. DACS_IDENTITY
http://dacs.dss.ca/man/dacs_acs.8.html#var_env_dacs_identity
33. DACS_USERNAME
http://dacs.dss.ca/man/dacs_acs.8.html#var_env_dacs_username
34. RFC 2396
http://www.rfc-editor.org/rfc/rfc2396.txt
35. RFC 822
http://www.rfc-editor.org/rfc/rfc822.txt
36. RFC 3696
http://www.rfc-editor.org/rfc/rfc3696.txt
37. EXIT*
http://dacs.dss.ca/man/dacs_authenticate.8.html#auth_directive_index
38. setvar()
http://dacs.dss.ca/man/dacs.exprs.5.html#setvar
39. dacs.groups(5)
http://dacs.dss.ca/man/dacs.groups.5.html#roles
40. DACS identity
http://dacs.dss.ca/man/#dacs_identity
41. dacs_authenticate(8)
http://dacs.dss.ca/man/dacs_authenticate.8.html
42. dacs.groups(5)
http://dacs.dss.ca/man/dacs.groups.5.html
43. strptime(3)
http://www.freebsd.org/cgi/man.cgi?query=strptime&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html
44. dacsoptions
http://dacs.dss.ca/man/#dacsoptions
45. --enable-dump
http://dacs.dss.ca/man/#enable-dump-arg
46. fcntl(2)
http://www.freebsd.org/cgi/man.cgi?query=fcntl&apropos=0&sektion=2&manpath=FreeBSD+10.3-RELEASE&format=html
47. TEMP_DIRECTORY
http://dacs.dss.ca/man/dacs.conf.5.html#TEMP_DIRECTORY
48. dacs.conf(5)
http://dacs.dss.ca/man/dacs.conf.5.html
49. --enab le-hush-startup-logging
http://dacs.dss.ca/man/dacs.install.7.html#build_flag_--enable-hush-startup-logging
50. LOG_FORMAT
http://dacs.dss.ca/man/dacs.conf.5.html#LOG_FORMAT
51. dacs.install(7)
http://dacs.dss.ca/man/dacs.install.7.html#configure_options
52. dacs_user_info.dtd
http://dacs.dss.ca/man/../dtd-xsd/dacs_user_info.dtd
53. dacs_vfs(8)
http://dacs.dss.ca/man/dacs_vfs.8.html
54. dacs_admin()
http://dacs.dss.ca/man/dacs.exprs.5.html#DACS_ADMIN
55. dacs_admin(8)
http://dacs.dss.ca/man/dacs_admin.8.html
56. last(1)
http://www.freebsd.org/cgi/man.cgi?query=last&apropos=0&sektion=1&manpath=FreeBSD+10.3-RELEASE&format=html
57. who(1)
http://www.freebsd.org/cgi/man.cgi?query=who&apropos=0&sektion=1&manpath=FreeBSD+10.3-RELEASE&format=html
58. sa(8)
http://www.freebsd.org/cgi/man.cgi?query=sa&apropos=0&sektion=8&manpath=FreeBSD+10.3-RELEASE&format=html
59. dacs_current_credentials(8)
http://dacs.dss.ca/man/dacs_current_credentials.8.html
60. dacs_signout(8)
http://dacs.dss.ca/man/dacs_signout.8.html
61. DACS_CONF
http://dacs.dss.ca/man/dacs_acs.8.html#var_env_dacs_conf
62. Locating dacs.conf and site.conf
http://dacs.dss.ca/man/dacs.conf.5.html#locating_dacs.conf
63. PASSWORD_DIGEST
http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_DIGEST
64. FORMAT
http://dacs.dss.ca/man/dacs.services.8.html#FORMAT
65. LOG_FILTER
http://dacs.dss.ca/man/dacs.conf.5.html#logging_levels
66. debug_dacs
http://dacs.dss.ca/man/dacs_acs.8.html#debug_dacs
67. The Jurisdiction Section
http://dacs.dss.ca/man/dacs.conf.5.html#jurisdiction_section
68. dacsacl(1)
http://dacs.dss.ca/man/dacsacl.1.html
69. dacsversion(1)
http://dacs.dss.ca/man/dacsversion.1.html
70. dacs_version(8)
http://dacs.dss.ca/man/dacs_version.8.html
71. DACS manual pages
http://dacs.dss.ca/man/../man/index.html
72. dacs.services(8)
http://dacs.dss.ca/man/dacs.services.8.html
73. user activity records
http://dacs.dss.ca/man/#tracking_user_activity
74. www.dss.ca
http://www.dss.ca
75. LICENSE
http://dacs.dss.ca/man/../misc/LICENSE