This document was originally written in 2001. Since then many updates and new additions have been made. Thanks to all the people who submitted updates and corrections.

The XML source of this document is available at http://www.xml-dev.com:8080/cocoon/mount/docbook/Apache-WebDAV-LDAP-HOWTO.xml.

The latest version of the document is available at http://www.xml-dev.com:8080/cocoon/mount/docbook/Apache-WebDAV-LDAP-HOWTO.html.

If you like to contribute to the HOWTO, you can d/l the XML source from http://www.xml-dev.com:8080/cocoon/mount/docbook/Apache-WebDAV-LDAP-HOWTO.xml , and send in the updated source to saqib@seagate.com ALONG WITH YOUR NAME IN THE LIST OF AUTHORS AND REVISION HISTORY :). That makes it easier for me contact the person if there are any updates/corrections. Thanks.

The Apache HTTP Server is an open-source HTTP server for modern operating systems including UNIX and Windows NT. It provides HTTP services in sync with the current HTTP standards.

Thei Apache WebServer is available for free download from http://httpd.apache.org/

WebDAV stands for Web enabled Distributed Authoring and Versioning. It provides a collaborative environment for users to edit/manage files on web-servers. Technically DAV is an extension to the http protocol.

Here is a brief description of the extensions provided by DAV:

Overwrite Protection: Lock and Unlock mechanism to prevent the "lost update problem". DAV protocol support both shared and exclusive locks.

Properties: Metadata (title, subject, creater, etc)

Name-space management: Copy, Rename, Move and Deletion of files

Access Control: Limit access to various resources. Currently DAV assumes access control is already in place, and does not provide strong authentication mechanism.

Versioning: Revision control for the documents. Versioning is not implemented yet.

PHP (recursive acronym for "PHP: Hypertext Preprocessor") is a widely-used Open Source general-purpose scripting language that is especially suited for Web development and can be embedded into HTML.

PHP is available from http://www.php.net

MySQL, the most popular Open Source SQL database, is developed, distributed, and supported by MySQL AB

mySQL DB Engine can be downloaded from http://www.mysql.com/

The tools needed to achieve this objective are:

This document assumes that you have the following already installed on your system.

You will need a machine running Solaris / Linux and GCC Compiler. GNU gnzip and GNU tar is also needed.

Apache is the HTTP server, it will be used to run the Web Application Server. Please download the Apache 2.0.46 source code from http://www.apache.org/dist/httpd/.

You will need to download the OpenSSL from http://www.openssl.org/source/ . Please download the latest version. OpenSSL installation will be used for SSL libraries for compiling mod_ssl with Apache, and for managing SSL certificates on the WebServer. Please download the OpenSSL source code gzipped file into /tmp/downloads

Download the iPlanet LDAP SDK from http://wwws.sun.com/software/download/products/3ec28dbd.html. We will use iPlanet LDAP SDK, because it includes libraries for ldaps:// (LDAP over SSL)

mod_auth_ldap will be used for compiling LDAP support into Apache. Please download mod_auth_ldap from http://www.muquit.com/muquit/software/mod_auth_ldap/mod_auth_ldap_apache2.html

Download the appropriate mySQL build for your platform from http://www.mysql.com/downloads/index.html

Download the PHP source code from http://www.php.net/downloads.php

The application server as we plan to install, requires the SSL libraries and LDAP libraries. SSL engine is also required for managing the SSL certs for Apache 2.x

$ su -

# mkdir /usr/local/iplanet-ldap-sdk.5
# cp /tmp/downloads/ldapcsdk5.08-Linux2.2_x86_glibc_PTH_OPT.OBJ.tar /usr/local/iplanet-ldap-sdk.5
# cd /usr/local/iplanet-ldap-sdk.5
# tar -xvf ldapcsdk5.08-Linux2.2_x86_glibc_PTH_OPT.OBJ.tar

 # cd /tmp/download
# gzip -d openssl.x.x.tar.gz
# tar -xvf openssl.x.x.tar
# cd openssl.x.x
# make
# make test
# make install

Installaing mySQL is quite simple. The downloaded binaries have to be place in appropriate directory.

We start creating a user:group for mysql daemon, and copying the files to appropriate directories.

 # groupadd mysql
# useradd -g mysql mysql
# cd /usr/local
# gunzip < /path/to/mysql-VERSION-OS.tar.gz | tar xvf - 
# ln -s full-path-to-mysql-VERSION-OS mysql

Next run the install_db script, and change permission on the files

 # cd mysql
# scripts/mysql_install_db
# chown -R mysql .

 # bin/mysqld_safe --user=mysql &

# ps -ef | grep mysql
root      3237     1  0 May29 ?        00:00:00 /bin/sh bin/safe_mysqld
mysql     3256  3237  0 May29 ?        00:06:58 /usr/local/mysql/bin/mysqld --defaults-extra-file=/usr/local/mysql/data/my.cnf --basedir=/usr/local/mysql --datadir=/usr/local/mysql/data --user=mysql --pid-file=/usr/local/mysql/data/downloa

# cd /usr/local/mysql
# ./bin/mysqladmin -u root -p shutdown

# /usr/local/mysql/bin/mysqladmin variables -u root --password={your_password} | grep datadir

Start by setting some FLAGS for the compiler

# export LDFLAGS="-L/usr/local/iplanet-ldap-sdk.5/lib/ -R/usr/local/iplanet-ldap-sdk.5/lib/:/usr/local/lib"
# export CPPFLAGS="-I/usr/local/iplanet-ldap-sdk.5/include"

Next UNTAR the apache 2.0 source files, and execute the configure script.

# cd /tmp/download
# gzip -d httpd-2.0.46.tar.gz 
# tar -xvf httpd-2.0.46.tar
# cd httpd-2.0.46
#./configure --enable-so  --with-ssl --enable-ssl  --enable-rewrite   --enable-dav

Next run the make command

# make
# make install

# /usr/local/apache2/bin/apachectl start

# /usr/local/apache2/bin/apachectl stop

Untar modauthldap_apache2.tar.gz

cd /tmp/download
# gzip -d modauthldap_apache2.tar.gz
# tar -xvf modauthldap_apache2.tar
# cd modauthldap_apache2

Now configure and install mod_auth_ldap

# ./configure --with-apxs=/usr/local/apache2/bin/apxs  --with-ldap-dir=/usr/local/iplanet-ldap-sdk.5/
# make
# make install

You will also need to get the cert7.db and key7.db from http://www.xml-dev.com/xml/key3.db and http://www.xml-dev.com/xml/cert7.db and place it in the /usr/local/apache2/sslcert/directory.

Unzip the PHP Source Files

gzip -d php-xxx.tar.gz
tar -xvf php-xxx.tar

Configure and run the make command

cd php-xxx
./configure --with-mysql --with-apxs=/usr/local/apache2/bin/apxs

Compile the source code

# make 
# make install

Copy the php.ini file to the appropriate directory

cp php.ini-dist /usr/local/lib/php.ini

Please verify that the following Apache directive appears in the /usr/local/apache/conf/httpd.conf :

  Addmodule mod_dav.c

If it does not please add it. This directive informs Apache about DAV capability. The directive must be placed outside any container.

Next we must specify where Apache should store the DAVLockDB file. DAVLockDB is a lock database for the WebDAV. This directory should be writable by the httpd process.

I store the DAVLock file under /usr/local/apache/var. I use this directory for other purposes as well. Please add the following line to your /usr/local/apache/conf/httpd.conf to specify that the DAVLockDB file will be under /usr/local/apache/var :

  DAVLockDB      /usr/local/apache/var/DAVLock 

The directive must be placed outside any container.

As mentioned above a directory must be created for DAVLockDB that can be written by the web server process. Usually web server process runs under the user 'nobody' . Please verify this for your system using the command:

ps -ef | grep httpd

Under /usr/local/apache create the directory and set the permissions on it using the following commands:

  # cd /usr/local/apache
  # mkdir var
  # chmod -R 755 var/
  # chown -R nobody var/
  # chgrp -R nobody var/

Enabling DAV is a trivial task. To enable DAV for a directory under Apache root, just add the following directive in the container for that particular directory:

  DAV On

This directive will enable DAV for the directory and its sub-directories.

The following is a sample configuration that will enable WebDAV and LDAP authentication on /usr/local/apache/htdocs/DAVtest. Place this in the /usr/local/apache/conf/httpd.conf file.

 DavLockDB /tmp/DavLock
<Directory "/usr/local/apache2/htdocs/DAVtest">
Options Indexes FollowSymLinks
AllowOverride None
order allow,deny
allow from all
AuthName "SMA Development server"
AuthType Basic
LDAP_Debug On
#LDAP_Protocol_Version 3
#LDAP_Deref NEVER
#LDAP_StartTLS On
LDAP_Server you.ldap.server.com 
#LDAP_Port 389
# If SSL is on, must specify the LDAP SSL port, usually 636
LDAP_Port 636
LDAP_CertDbDir /usr/local/apache2/sslcert
Base_DN "o=SDS"
UID_Attr uid
DAV On
#require valid-user
require valid-user 
#require roomnumber "123 Center Building"
#require filter "(&(telephonenumber=1234)(roomnumber=123))"
#require group cn=rcs,ou=Groups
</Directory>

As mentioned in a earlier section, all DAV directories have to be writable by the WebServer process. In this example we assume WebServer is running under username 'nobody'. This is usually the case. To check httpd is running under what user, please use:

# ps -ef | grep httpd

Create a test directory called 'DAVtest' under /usr/local/apache2/htdocs :

# mkdir /usr/local/apache/htdocs/DAVtest

Change the permissions on the directory to make it is read-writable by the httpd process. Assuming the httpd is running under username 'nobody', use the following commands:

  # cd /usr/local/apache/htdocs
  # chmod -R 755 DAVtest/
  # chown -R nobody DAVtest/
  # chgrp -R nobody DAVtest/

Finally you must run the configuration test routine that comes with Apache to verify the syntax in httpd.conf :

# /usr/local/apache/bin/apachectl configtest

If you get error messages please verify that you followed all of the above mentioned steps correctly. If you can not figure out the error message feel free to email me with the error message (saqib@seagate.com).

If the configtest is successful start the apache web-server:

# /usr/local/apache/bin/apachectl restart

Now you have WebDAV enabled Apache Server with LDAP authentication and SSL encryption.

It is very important that the WebDAV that we just implemented be fully complaint with the WebDAV-2 protocol. If it is not fully compatible, the client side WebDAV applications will not function properly.

To test the complaince we will use a tool called Litmus. Litmus is a WebDAV server protocol compliance test suite, which aims to test whether a server is compliant with the WebDAV protocol as specified in RFC2518.

Please download the Litmus source code from http://www.webdav.org/neon/litmus/ and place it in the /tmp/downloads directory.

Then use gzip and tar to extract the files:

# cd /tmp/downloads
# gzip -d litmus-0.6.x.tar.gz
# tar -xvf litmus-0.6.x.tar
# cd litmus-0.6.x

Compiling and installing Litmus is easy:

# ./configure
# make
# make install

make install will install the Litmus binary files under /usr/local/bin and the help files under /usr/local/man

To the test the complaince of the WebDAV server that you just installed, please use the following command

# /usr/local/bin/litmus http://you.dav.server/DAVtest userid passwd

In the previous section when we created the DAVtest share, we used the LDAP for authentication purposes. However anyone who can authenticates using their LDAP useri/passwd will be able to access that folder.

Using the require directive in the httpd.conf file, we can limit access to certain individuals or groups of individuals.

If we look at the DAVtest configuration from the previosu section:

  <Directory /usr/local/apache/htdocs/DAVtest>
  Dav On
  #Options Indexes FollowSymLinks

  AllowOverride None
  order allow,deny
  allow from all
  AuthName "LDAP_userid_password_required"
  AuthType Basic
  <Limit GET PUT POST DELETE PROPFIND PROPPATCH MKCOL COPY MOVE LOCK UNLOCK>
  Require valid-user
  </Limit>
  LDAP_Server ldap.server.com
  LDAP_Port 389
  Base_DN "o=ROOT"

  UID_Attr uid
  </Directory>

We see that the require is set to valid-user. Which means any valid authenticated user has access to this folder.

It maybe be required that the editting for the resources on the DAV shares be restricted to certain individual, however anyone can view the resources. This can be easily done using the <Limit> tags in the httpd.conf file

  <Directory /usr/local/apache/htdocs/DAVtest>
  Dav On
  #Options Indexes FollowSymLinks

  AllowOverride None
  order allow,deny
  allow from all
  AuthName "LDAP_userid_password_required"
  AuthType Basic
  <Limit GET PUT POST DELETE PROPFIND PROPPATCH MKCOL COPY MOVE LOCK UNLOCK>
  Require valid-user
  </Limit>
  LDAP_Server ldap.server.com
  LDAP_Port 389
  Base_DN "o=ROOT"

  UID_Attr uid
  </Directory>

You restrict write access to certain individuals by changing the <limit> to

  <Limit PUT POST DELETE PROPPATCH MKCOL COPY MOVE LOCK UNLOCK>
  Require 334455
  </Limit>

Basically we are limiting the PUT POST DELETE PROPPATH MKCOL COPY MOVE LOCK and UNLOCK to an individual who has the UID of 334455. Everyone else will be able to use the methods GET and PROPFIND on the resources, but not any other method.

SSL (Secure Socket Layer) is a protocol layer that exists between the Network Layer and Application layer. As the name suggest SSL provides a mechanism for encrypting all kinds of traffic - LDAP, POP, IMAP and most importantly HTTP.

The following is a over-simplified structure of the layers involved in SSL.

	+-------------------------------------------+
	|   LDAP   |    HTTP    |   POP   |   IMAP  |
	+-------------------------------------------+
	|                   SSL                     |
	+-------------------------------------------+
	|               Network Layer               |
	+-------------------------------------------+
	

            Sender's                 Receiver's
           PrivateKey                 PublicKey
          ,-.                     ,-.
         (   )..........         (   )..........
          `-' ''''|'|'||          `-' ''''''''||
                  | |                    |
                  | |                    |
   .----------.   | |    .----------.    |     .----------.
   |          |   V |    |          |    V     |          |
   |Clear Text|--------->|CipherText|--------->|CipherText|
   |          |  Step1   |    1     |  Step2   |    2     |\
   `----------'     |    `----------'          `----------' \    __
         |          |                                        \   [_'
         |          |                                   step5 \   |
         |Step3     |                                       __  --|--
         |          |                                  _.--'      |
         V          |                            _..-''          / \
    .---------.     |    .---------.       _..-''              Receiver
    |  SHA 1  |     V    | Digital | _..-''
    |MsgDigest|--------->|Signature|'            _
    `---------'  Step4   `---------'         _  (_)
        _____ ____   ____  ____ _   _ ____ _| |_ _  ___  ____
       | ___ |  _ \ / ___)/ ___) | | |  _ (_   _) |/ _ \|  _ \
       | ____| | | ( (___| |   | |_| | |_| || |_| | |_| | | | |
       |_____)_| |_|\____)_|    \__  |  __/  \__)_|\___/|_| |_|
                               (____/|_|
	

           Receiver's               Sender's
           PrivateKey               PublicKey
         ,-.                     ,-.
        (   )..........         (   )..........
         `-' ''''''''||          `-' '''''''|||
                |                      |    |
                |                      |    |
  .----------.  |       .----------.   |    | .----------.
  |          |  V       |          |   V    | |          |       .---#1----.
  |CipherText|--------->|CipherText|--------->|ClearText |------>|  SHA 1  |
  |    2     |  Step1   |    1     |  Step2 | |          | Step3 |MsgDigest|
  `----------'          `----------'        | `----------'       `---------'
                                            |                        ||
                                            |                        ||Step5
                                            |                        ||
                                            |                        ||
                               .---------.  |                    .---------.
                               | Digital |  V                    |  SHA 1  |
                               |Signature|---------------------->|MsgDigest|
                 _             `---------'  Step4     _          `---#2----'
                | |                               _  (_)
              __| |_____  ____  ____ _   _ ____ _| |_ _  ___  ____
             / _  | ___ |/ ___)/ ___) | | |  _ (_   _) |/ _ \|  _ \
            ( (_| | ____( (___| |   | |_| | |_| || |_| | |_| | | | |
             \____|_____)\____)_|    \__  |  __/  \__)_|\___/|_| |_|
                                    (____/|_|

While compiling Apache we created a test certificate. We used the makefile provided by mod_ssl to create this custom Certificate. We used the command:

# make certificate TYPE=custom

This certificate can be used for testing purposes.

For production use you will need a certificate from a Certificate Authority (hereafter CA). Certificate Authorities are certificate vendors, who are listed as a Trusted CA in the user's browser. As mentioned in the Encryption Algorithms section, if the CA is not listed as a trusted authority, your user will get a warning message when trying to connect to a secure location.

Similarly the test certificates will also cause a warning message to appear on the user's browser.

CSR or Certificate Signing Request must be sent to the trusted CA for signing. This section discusses howto create a CSR, and send it to the CA of your choice. # openssl req command can be used to a CSR as follows:

# cd /usr/local/apache/conf/
# /usr/local/ssl/bin/openssl req -new -nodes -keyout private.key -out public.csr
Generating a 1024 bit RSA private key
............++++++
....++++++
writing new private key to 'private.key'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:California
Locality Name (eg, city) []:San Jose
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Seagate 
Organizational Unit Name (eg, section) []:Global Client Server
Common Name (eg, YOUR name) []:xml.seagate.com
Email Address []:saqib@seagate.com

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:badpassword
An optional company name []:

# /usr/local/ssl/bin/openssl req -rand some_file.ext -new -nodes -keyout private.key -out public.csr 

At this point you will be asked several questions about your server to generate the Certificate Singning Request

Note: Your Common Name (CN) is the Fully Qualified DNS (FQDN) name of your webserver e.g. dav.server.com . If you put in anything else, it will NOT work. Remember the password that you use, for future reference.

Once the process is complete, you will have private.key and a public.csr . You will need to submit the public.csr to the Certification Authority. At this pointe the public.key is not encrypted. To encrypt:

 # mv private.key private.key.unecrpyted
# /usr/local/ssl/bin/openssl rsa -in private.key.unecrpyted -des3 -out private.key

Once the Certification Authority processes your request, they will send an encoded certificate (Digital Certificate) back to you. The Digital Certificate is in the format defined by X.509 v3. The following shows the structure of a typical X509 v3 Digital Certificate

# openssl verify server.crt
server.crt: OK 

# openssl x509 -text -in server.crt
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 312312312 (0x0)
        Signature Algorithm: md5WithRSAEncryption
	Issuer: C=US, O=GTE Corporation, CN=GTE CyberTrust Root
        Validity
            Not Before: Feb  8 03:25:50 2000 GMT
            Not After : Feb  8 03:25:50 2001 GMT
	    Subject: C=US, ST=New York, L=Pelham, O=xml-dev, OU=web, CN=www.xml-dev.com/Email=saqib@xml-dev.com
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
            RSA Public Key: (1024 bit)
                Modulus (1024 bit):
		............
		............
                Exponent: 65537 (0x10001)
    Signature Algorithm: md5WithRSAEncryption
    	............
	............

	

#   Server Certificate:
#   Point SSLCertificateFile at a PEM encoded certificate.  If
#   the certificate is encrypted, then you will be prompted for a
#   pass phrase.  Note that a kill -HUP will prompt again.  Keep
#   in mind that if you have both an RSA and a DSA certificate you
#   can configure both in parallel (to also allow the use of DSA
#   ciphers, etc.)
SSLCertificateFile /usr/local/apache2/conf/ssl.crt/server.crt
#SSLCertificateFile /usr/local/apache2/conf/ssl.crt/server-dsa.crt

#   Server Private Key:
#   If the key is not combined with the certificate, use this
#   directive to point at the key file.  Keep in mind that if
#   you've both a RSA and a DSA private key you can configure
#   both in parallel (to also allow the use of DSA ciphers, etc.)
SSLCertificateKeyFile /usr/local/apache2/conf/ssl.key/private.key
#SSLCertificateKeyFile /usr/local/apache2/conf/ssl.key/server-dsa.key

RSA Private Key stored on the webserver is usually encrypted, and you need a passphrase to parse the file. That is why you are prompted for a passphrase when start Apache with modssl:

# apachectl startssl
Apache/1.3.23 mod_ssl/2.8.6 (Pass Phrase Dialog)
Some of your private key files are encrypted for security reasons.
In order to read them you have to provide us with the pass phrases.
Server your.server.dom:443 (RSA)
Enter pass phrase:

Encrypting the RSA Private Key is very important. If a cracker gets hold of your "Unencrypted RSA Private Key" he/she can easily impersonate your webserver. If the Key is encrypted, the cracker can not do anything without brute forcing the passphrase. Use of a strong (ie: long) passphrase is encouraged.

However encrypting the Key can sometimes be nuisance, since you will be prompted for a passphrase everytime you start the web-server. Especially if you are using rc scripts to start the webserver at boot time. The prompt for a passphrase will stop the boot process, waiting for your input.

You can get rid of the passphrase prompt easily by decrypting the Key. However make sure that no one can hold of this Key. I would recommend Hardening and Securing guidelines be followed before decrypting the Key on the webserver.

To decrypt the Key:

First make a copy of the encrypted key

# cp server.key server.key.cryp

Then re-write the key with encryption. You will be prompted for the original encrypted Key passphrase

# /usr/local/ssl/bin/openssl rsa -in server.key.cryp -out server.key
read RSA key
Enter PEM pass phrase:
writing RSA key

One way to secure the decrypted Private Key is to make readable only by the root:

# chmod 400 server.key