DACS(1) | DACS Commands Manual | DACS(1) |
dacs - a distributed access control system
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]
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].
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.
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.
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.
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).
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.
Some of the key concepts used throughout the DACS documentation are defined in this section.
account
authentication
authorization
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
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
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
Programmatic, general-purpose access control is available for virtually any program (using dacscheck(1)[21]). This is completely decoupled from Apache.
DACS administrator
DACS identity
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.
DACS-wrapped
federation
item type
jurisdiction
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
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.
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
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
[[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
[[[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:
* , : + ( ) ~ < > = | \ / "
- _ . ! ~ * ' ( ) % : @ & = + $ ,
( ) < > @ , ; : \ " . [ ]
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.
Groups
[[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
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
Please refer to dacs.groups(5)[39] for additional information.
Concise User 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:
%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.
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.
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.
Most DACS programs perform the following actions when they start:
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.
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.
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.
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.
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.
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).
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.
It is critical for any such rule to require the dacs_admin()[54] predicate.
VFS "[user_info]file://${Conf::FEDERATIONS_ROOT}/${Conf::FEDERATION_DOMAIN}/${Conf::JURISDICTION_NAME}/user_info"
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.
Many DACS utilities recognize the following standard options, which are called dacsoptions:
-c dacs.conf
-Dname=value
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
--digests [digest-name]
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
--enable-dump
-format fmt
-ll logging-level
--license
-q
-sc site.conf
--std
-t
-u config-uri
-uj jurisdiction-name
-un
-up jurisdiction-name
-us
-v
--verbose
--version
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.
SERVER_NAME, SERVER_PORT, REQUEST_URI
dacs.conf
site.conf
DACS manual pages[71], dacs_admin(8)[55], dacs.install(7)[6], dacs.readme(7)[5], dacs.services(8)[72]
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.
There should be some assistance for administering user activity records[73].
Distributed Systems Software (www.dss.ca[74])
Copyright © 2003-2018 Distributed Systems Software. See the LICENSE[75] file that accompanies the distribution for licensing information.
02/19/2019 | DACS 1.4.40 |