dacs.readme(7) DACS README

DESCRIPTION

This file is part of the DACS suite.

Other important documents in this release:

• for a brief description of this release, and possibly last minute updates, please refer to m[blue]READMEm[][1]

• for a technical overview of the system, please see m[blue]dacs(1)m[][2]

• for information about licensing, please refer to m[blue]LICENSEm[][3]

• for information about installation, please refer to m[blue]dacs.install(7)m[][4]

• for the Quick Start tutorial, please refer to m[blue]dacs.quick(7)m[][5]

• for important release notes, please visit m[blue]http://dacs.dss.ca/download.htmlm[]


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.

DACS At a Glance

DACS is:

• a light-weight, open source single sign-on system;

• a flexible and powerful role-based access control system;

• a set of feature-rich authentication methods;

• an m[blue]Apachem[][6] 2.0, 2.2, 2.4 module and suite of CGI programs;

• able to apply coarse-grained access control to web service requests made using standard web browsers;

• able to provide fine-grained access control functionality to almost any program or script;

• a collection of web services that can provide access control and identity management functionality to your middleware;

• a C/C++ toolkit for building new authentication and access control functionality into programs, whether web-based or not;

• for Unix-type platforms, such as GNU/Linux, Mac OS X, and FreeBSD.

For developers, DACS makes access control functionality available through the command line, allowing scripts (Perl, PHP, shell, etc.) to make data-driven access control decisions rather than program-driven ones. This can be used completely independently of the web functionality and without dealing with run-time configuration of DACS. Please see m[blue]dacscheck(1)m[][7]. DACS also provides web services from which single sign-on systems can be constructed.

For web sites, DACS can help manage access to web resources in many situations, whether you have just one web server, several web servers at one site, or many web servers spread across the Internet. You may find it to be useful simply as a universal authentication mechanism for a single Apache server or as a full-fledged, single sign-on multi-server identity management and access control system.


Tip

If you are interested in m[blue]dacscheck(1)m[][7] or the general-purpose DACS utilities (e.g., m[blue]dacshttp(1)m[][8], m[blue]sslclient(1)m[][9]) but are not interested in web services or Apache, refer to the instructions in m[blue]dacs.install(7)m[][4].

The DACS home page is at m[blue]http://dacs.dss.cam[]. DACS is hosted as a m[blue]SourceForgem[][10] project at m[blue]http://sourceforge.net/projects/dacsm[].

Supported Platforms

DACS is currently developed and tested:

• with m[blue]Apachem[][6] 2.2.23 and 2.4.3 (support for 2.4.X is relatively recent; 2.0.64 and newer 2.0.X releases are deprecated and untested)

• on platforms:

• m[blue]FreeBSDm[][11] 9.1 (amd64)

• m[blue]CentOSm[][12] 5.9 (x86_64, Linux 2.6.X, built from m[blue]Red Hat Enterprise Linuxm[][13] 5.9)

• m[blue]Mac OS Xm[][14] 10.8.2 (Mountain Lion, Intel Core i7, x86_64)

• using GCC 4.2 (and newer) compilers

• using recent Firefox browsers, and Internet Explorer 8 browsers

FreeBSD 9.1 is the primary development platform. For this reason, references to Unix manual pages throughout the DACS documentation cite the FreeBSD documentation. This should not matter much if you are using a different platform, but keep this in mind.

Most DACS installations are on Linux or FreeBSD platforms. Support for Mac OS X is relatively recent.


Note

• When building DACS for use with Apache2.2, you will probably need to specify the --with-apache-apr flag, and perhaps other Apache-related flags, to configure.

Apache 1.3 is not supported (please refer to the m[blue]FAQm[][15]).

DACS has not been tested with Apache 2.1.

Other Platforms

DACSis not officially supported on platforms other than those mentioned above. Recent releases have built and worked correctly on other platforms, but because we do not have ready access to them, or due to lack of interest, we no longer test on them.

Up to and including version 1.4.25, DACS was tested and used on m[blue]Solaris 10m[][16] (m[blue]OpenSolarism[][17] 2008.11, SunOS 5.11, m[blue]x86m[][18]). Solaris is no longer supported. Early versions of DACS were used on Solaris 8 (SPARC) and Solaris 10 (SPARC) platforms. A wide variety of build, install, and run-time problems were encountered with third-party packages on the OpenSolaris and SPARC platforms. Depending on which third-party software your DACS configuration requires, or if you are prepared to try older versions of third-party software or devote extra effort, you may have some success running DACS on these platforms, but in general we cannot recommend using these platforms for DACS in production settings and they are no longer officially supported. Comments specific to Solaris remain in the DACS documentation but will likely be removed in a future release, as will configuration and build capabilities.

Earlier releases of DACS compiled and (mostly) installed cleanly on WinXP/m[blue]Cygwinm[][19] 1.7.5 and later with GCC 4.3, but starting with DACS 1.4.26, m[blue]Cygwinm[][19] is no longer used for testing DACS. Comments specific to Cygwin that remain in the DACS documentation will likely be removed in a future release, as will configuration and build capabilities. Regarding Cygwin and earlier versions of DACS:

mod_auth_dacs does not build as a shared module

• there were problems building Expat 2.0.0 from source (2.0.1 is ok)

• only limited testing has been performed on this platform

• you can't execute src/config.nice; copy it to some other filename and execute that instead

• when doing "make install", try the username and group "Administrators" or "Administrator" when prompted if you don't know what else to use (the install procedure should use those names as defaults

We expect that DACS will also run on other varieties of Unix and with other browsers. No testing is done with very old browsers, however. We would appreciate reports of problems encountered while building or running DACS on unofficial platforms so that we can address portability issues and support these platforms better.

Warnings

Please read this section carefully!


Security

1. After obtaining a DACS release, please verify all checksums for the file you downloaded. Do not use a download if any checksum for it does not match. Checksums are posted at m[blue]http://dacs.dss.ca/download.htmlm[] immediately after a new release is distributed.

OpenSSL'sdgst command can be used to compute checksums; for example,

% openssl dgst -md5 dacs-1.4.22.tgz
% openssl dgst -sha1 dacs-1.4.22.tgz

2. Improper installation, configuration, or use of DACS may leave your system open to various kinds of attacks and exploits.

Many other systems and software components, including Apache and OpenSSL, can also compromise system security if not properly installed, configured, and administered; they give similar admonishments. Please take appropriate care.

A DACS administrator ought to have some experience with Apache configuration (including its authentication and access control directives, and building httpd), and basic knowledge of security issues on the installation platform.

3. The security of DACS depends on the security of the underlying operating system, third party software, build, installation, and configuration parameters, human factors, and more. In particular, ensure that file ownership and modes are appropriate for run-time accessible DACS configuration and data files (dacs.conf, site.conf, encryption keys, access control rules, group files, etc.).

4. Users of your DACS-wrapped services are responsible for maintaining the secrecy of information used to sign on (such as passwords) and authentication and authorization information sent to them by DACS (such as HTTP cookies). Spyware, and browser modifications or improper settings, may compromise security - DACS cannot prevent improper use or intentional misuse.

5. After access is granted to a resource, DACS does nothing to stop a user from redistributing whatever is returned by the web server. Therefore, strictly speaking, DACS is neither a copyright enforcement system nor is it a m[blue]Digital Rights Management (DRM) systemm[][20], although it may be possible to apply DACS in those domains. DACS does have the ability to force a user to view and acknowledge a copyright notice or license, however.

6. Making routine backup copies of your current DACS configuration and data files is strongly encouraged. A procedure should be established for periodically creating copies of your DACS installation and keeping them in a secure, off-site location. This is especially important for encryption keys and account files, which cannot be recreated if lost.

7. Please review Section 15 ("Security Considerations") of m[blue]RFC 2616m[][21].

8. Be sure to check for new releases of DACS regularly. New releases may address important bugs and security issues, so keeping your installation current is important. You can m[blue]subscribe to email notificationsm[][22].

You should likewise stay alert to new releases of third-party packages that your install of DACS uses.

9. Note that, because of the enormous number of combinations of platforms, versions, third-party packages, build options, run-time options, and so on, not every possible DACS deployment that can be created and enabled is actually built or tested. This is presumably true for nearly every large software package but it's worth emphasizing. Therefore, make sure you test carefully before putting your DACS deployment into production and after making changes to it.

10. Reiterating, test carefully after making changes to your DACS configuration. In particular, make sure that new access control rules and user authentication work as you expect.

11. For DACS to be a secure system, all communication between DACS and its users, components, and middleware must take place over a secure connection (typically using SSL and the m[blue]HTTPSm[][23] method) to safeguard account names, passwords, DACS credentials, and so on. DACS does not require secure network connections, however, and can function without them in situations where a lower standard of security is acceptable. See m[blue]SECURE_MODEm[][24].

Note that if a client connects from an insecure subnet, various m[blue]man-in-the-middle attacksm[][25] are possible, even when it appears that SSL is being used (for example, see m[blue]sslstripm[][26]).

12. In the event of an emergency situation that might be related to DACS, you may, of course, stop all Apache processes. It is sufficient to make dacs.conf inaccessible to Apache, however, whether by renaming the file, changing its ownership, or changing its permissions. (Or, you may make the DACS web services unavailable using the same methods.) All DACS web services must be able to read dacs.conf, so this will effectively turn DACS off. More selective ways of limiting access are available, such as through the revocation list.

13. DACS depends mainly on m[blue]OpenSSLm[][27], a third-party package that you need to obtain separately, for cryptographic functionality. Some library functions provided by your operating system (such as m[blue]crypt(3)m[][28]) are also used.

14. It is recommended that the Network Time Protocol (m[blue]RFC 1305m[][29]) or equivalent be used on any host that runs DACS commands or web services. A sudden, large change to a system's clock while DACS is operational may have undesirable effects and should be avoided.

15. If you are deploying DACS as part of a publicly accessible web site, consider including a notification on your site that it may issue cookies. This is commonly mentioned in a site's "Privacy" or "Security" page. DACS may not function as expected if a user's browser has disabled cookies or will not accept them; in particular, the single sign-on feature generally requires that users' browsers accept cookies.

16. The DACS distribution may include code, features, or functionality that is not described in the distribution's documentation, or is described as untested, partially implemented, or deprecated, or is accompanied by a warning. Such code, features, or functionality is subject to change or removal without notice and should not be used.


Important

DACS MAY INCLUDE ITS OWN CRYPTOGRAPHIC FUNCTIONS and may therefore fall under certain import, export, and/or use restrictions in other parts of the world, even though DACS is developed, maintained, and officially distributed from Canada.

Export and/or import and/or use of strong cryptography software, providing cryptography hooks, or merely communicating technical details about cryptographic software is illegal in some parts of the world. YOU ARE STRONGLY ADVISED to pay close attention to any laws that may apply when you import, export, or use DACS, or even communicate about it. We are not liable for any violations you make - it is your responsibility. For additional information, see the m[blue]Crypto Law Surveym[][30].

Roadmap

Stability, backward compatibility, portability across supported platforms, and keeping up to date with respect to third-party support packages are now the primary goals of DACS1.4 releases. A top priority is to fix all known bugs between releases and improve the documentation.

Please consult the DACSm[blue]web sitem[] for information on upcoming releases.

Upgrading


Security

Because DACS is security software, we strongly recommend that you upgrade to the newest release as soon as you are able.

Upgrading is neither a difficult nor a time consuming procedure most times. Sometimes an incompatible change in DACS will require you to change a DACS configuration file, but this should not be difficult to do and we will try to advise you of such changes.

The DACS 1.4 releases contain a great many changes and improvements, some incompatible with earlier releases of DACS. If you are upgrading from DACS 1.3.2 or another older release, you will need to become familiar with these changes. You must manually convert your old DACS configuration files to the new format, for example. You should not find upgrading to be a difficult or time consuming task.


Important

Making backup copies of your DACS installation immediately prior to upgrading is strongly recommended.

Some features available in earlier versions of DACS are not available in this release, but will be provided as soon as possible.

Note that DACS 1.4 may not interoperate with prior releases.

We aim to avoid making any backward incompatible changes within the DACS 1.4.x releases.

Administration

Once installed and configured, DACS requires very little administration.


Tip

At higher logging levels, DACS log files can become large quite quickly. You should therefore arrange for them to be rotated regularly (e.g., using m[blue]newsyslog(8)m[][31]). A built-in log rotation feature is being considered for DACS.

If you're creating DACS log files that have names based on their date of creation, to expire/rotate/compress them you might periodically run the m[blue]find(1)m[][32] command to identify old logs. For example, the command

% find /usr/local/dacs/logs -type f -a -mtime 2 -a -exec gzip {} \;

will compress any files in the log directory that haven't been modified for at least 24 hours.

There are also Apache modules available to do the rotation:

• m[blue]http://httpd.apache.org/modulesm[]

• m[blue]http://modules.apache.orgm[]

Related Software

A variety of other software and resources for DACS can be found in the m[blue]dacs-contribm[][33] project at m[blue]SourceForgem[][10].


The DACS Java Library (DJL)

The DJL is being developed to support the use of DACS in Java client applications. It implements Java wrapper classes for selected DACS services, and provides an HTTP client through which DACS services may be accessed and DACS credentials obtained and managed.


The FedAdmin Web Application

FedAdmin is an administrator console for managing the configuration of DACS federations and jurisdictions. It is deployed in a servlet container such as Tomcat, but must be accessed via an Apache+DACS proxy and deployed under a dedicated FEDADMINDACS application jurisdiction.

FedAdmin implements partial coverage of the most common DACS configuration tasks, including viewing federation and jurisdiction configuration directives, adding and deleting local DACS users, and creating, editing, and deleting ACL rules.

Support

An array of technical support is available from m[blue]DSSm[][34]. Please see the m[blue]support pagem[][35] for details.

Known Problems

There are a few defects in the DACS 1.4 releases that administrators should be aware of. These are not likely to be addressed in the near future.

1. If the HTTP data stream is compressed or encrypted (other than via SSL), DACS will not be able to access POST arguments and you should use the mod_auth_dacs module directive "SetDACSAuthPostBuffer 0".

2. In general, DACS does not support IPv6 addresses.

3. The group management service and group distribution utilities have not be tested with this release of DACS.

4. The man pages are generated from DocBook XML. The docbook-xsl used to create [nt]roff source is incomplete and/or buggy. As a result, the quality of the formatting is sometimes poor. You will find the HTML version of the documentation more readable.

5. Support for internationalization is poor.

6. Some configuration directives have global scope (i.e., they apply in several contexts) when it might be preferable to have context-specific versions of them. For example, the algorithm specified by m[blue]PASSWORD_DIGESTm[][36] is used for more than one purpose within DACS. On the other hand, this reduces the number of directives, and therefore helps to contain the complexity of DACS.

Bugs, Suggestions, and Feedback

Please see the m[blue]support pagem[][35] for details.

Some elements of DACS are less well-travelled than others and users may therefore experience problems with them. Please m[blue]let us knowm[][37] if you encounter bugs.

AUTHOR

Distributed Systems Software (m[blue]www.dss.cam[][34])

COPYING

Copyright2003-2013 Distributed Systems Software. See the m[blue]LICENSEm[][3] file that accompanies the distribution for licensing information.

NOTES

1.
README
http://dacs.dss.ca/man/../misc/README
2.
dacs(1)
http://dacs.dss.ca/man/dacs.1.html
3.
LICENSE
http://dacs.dss.ca/man/../misc/LICENSE
4.
dacs.install(7)
http://dacs.dss.ca/man/dacs.install.7.html
5.
dacs.quick(7)
http://dacs.dss.ca/man/dacs.quick.7.html
6.
Apache
http://httpd.apache.org
7.
dacscheck(1)
http://dacs.dss.ca/man/dacscheck.1.html
8.
dacshttp(1)
http://dacs.dss.ca/man/dacshttp.1.html
9.
sslclient(1)
http://dacs.dss.ca/man/sslclient.1.html
10.
SourceForge
http://www.sourceforge.net
11.
FreeBSD
http://www.freebsd.org
12.
CentOS
http://www.centos.org
13.
Red Hat Enterprise Linux
http://www.redhat.com/rhel
14.
Mac OS X
http://www.apple.com/macosx
15.
FAQ
http://dacs.dss.ca/faq.html
16.
Solaris 10
http://www.sun.com/software/solaris/10/index.jsp
17.
OpenSolaris
http://www.opensolaris.com
18.
x86
http://www.solaris-x86.org/
19.
Cygwin
http://cygwin.com/
20.
Digital Rights Management (DRM) system
http://en.wikipedia.org/wiki/Digital_rights_management
21.
RFC 2616
http://www.rfc-editor.org/rfc/rfc2616.txt
22.
subscribe to email notifications
http://freshmeat.net/projects/dacs/
23.
HTTPS
http://www.rfc-editor.org/rfc/rfc2818.txt
24.
SECURE_MODE
http://dacs.dss.ca/man/dacs.conf.5.html#SECURE_MODE
25.
man-in-the-middle attacks
http://en.wikipedia.org/wiki/Man-in-the-middle_attack
26.
sslstrip
http://www.thoughtcrime.org/software/sslstrip
27.
OpenSSL
http://www.openssl.org
28.
crypt(3)
http://www.freebsd.org/cgi/man.cgi?query=crypt&apropos=0&sektion=3&manpath=FreeBSD+9.1-RELEASE&format=html
29.
RFC 1305
http://www.rfc-editor.org/rfc/rfc1305.txt
30.
Crypto Law Survey
http://rechten.uvt.nl/koops/cryptolaw
31.
newsyslog(8)
http://www.freebsd.org/cgi/man.cgi?query=newsyslog&apropos=0&sektion=8&manpath=FreeBSD+9.1-RELEASE&format=html
32.
find(1)
http://www.freebsd.org/cgi/man.cgi?query=find&apropos=0&sektion=1&manpath=FreeBSD+9.1-RELEASE&format=html
33.
dacs-contrib
http://sourceforge.net/projects/dacs-contrib
34.
DSS
http://www.dss.ca
35.
support page
http://dacs.dss.ca/support.html
36.
PASSWORD_DIGEST
http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_DIGEST
37.
let us know
http://www.dss.ca/contactus.html