Apache Directory Services
=========================

**WARNING:** *This directory service implementation is experimental,
incomplete and not supported.*

The Apache directory services provide principal information that is
read from configuration files in the `same formats`_ as used by the
`Apache HTTP server`_, allowing you to easily share user and group
information with an Apache server.

.. _same formats: http://httpd.apache.org/docs/2.3/howto/auth.html
.. _Apache HTTP server: http://httpd.apache.org/

The Apache directory services provide principal information for users
and groups. They do not provide principal information for locations or
resources.

Configuring the Calendar Server
-------------------------------

The full name of the service is either
``twistedcaldav.directory.apache.BasicDirectoryService`` or
``twistedcaldav.directory.apache.DigestDirectoryService``. These
services implement `basic and digest HTTP authentication`_,
respectively.

.. _basic and digest HTTP authentication: http://www.ietf.org/rfc/rfc2617.txt

Both services take a ``userFile`` parameter which contains the name of
the file to read user principal information from and an optional
``groupFile`` parameter which contains the name of the file to read
group principal information from.

For example, if you are using digest:

::

  <!--  Apache-style Digest Directory Service -->
  <key>DirectoryService</key>
  <dict>
    <key>type</key>
    <string>twistedcaldav.directory.apache.DigestDirectoryService</string>
  
    <key>params</key>
    <dict>
      <key>userFile</key>
      <string>conf/digest</string>
      <key>groupFile</key>
      <string>conf/group</string>
    </dict>
  </dict>

The service re-reads the user and group files if either file's
timestamp changes, so edits to the files do not require a server
restart.

Note that basic authentication is highly insecure because it sends
password information in plain text over the network (where is may be
intercepted) and should not be enabled on a server unless all
connections are somehow secured by another means, such as by enabling
SSL and disabling non-SSL connections.

Configuring Principals
----------------------

In the case of ``BasicDirectoryService``, the user file must be in the
form generated by the Apache ``htpasswd`` command; in the case of
``DigestDirectoryService``, the user file must be in the form
generated by the Apache ``htdigest`` command.

Both user file formats contain a single entry per line, with fields
separated by the colon (``:``) character. The basic format has two
fields, one containing a user identifier and the second containing the
user's password in the UNIX crypt format. The digest format has three
fields: a user identifier, a realm name, and the user's hashed
password.

An example basic user file:

::

  wsanchez:Cytm0Bwm7CPJs
  cdaboo:I.Ef5FJl5GVh2
  dreid:LVhqAv4qSrYPs
  lecroy:/7/5VDrkrLxY.

And an example digest user file:

::

  wsanchez:Test:decbe233ab3d997cacc2fc058b19db8c
  cdaboo:Test:61164bf3d607d072fe8a7ac420b24aac
  dreid:Test:8ee67801004b2752f72b84e7064889a6
  lecroy:Test:60d4feb424430953be045738041e51be

The group file is in a similar format, with one entry of
colon-separated field per line. Each line has two fields: a group
identifier, and a comma- (``,``) separated list of user identifiers
which identify the members of the group.

And example group file:

::

  managers: lecroy
  grunts: wsanchez, cdaboo, dreid
  right_coast: cdaboo
  left_coast: wsanchez, dreid, lecroy

The user files should be edited using the ``htpasswd`` and
``htdigest`` tools. The group file is typically edited by hand.
