Setting up digest authentication

Digest authentication avoids transmitting passwords by exchanging character strings (digests) that prove both the user and the Web server know the password. This requires passwords for all users to be stored on the server. It is very important to ensure that these passwords cannot be exposed to unauthorized users. Drupal should be able to store passwords without being able to retrieve them.

Secure Site provides scripts that can handle stored passwords securely when properly set up. These scripts are contained in the digest_md5 directory. There are two scripts in this directory:

stored_passwords.php

Add, delete, and update user passwords.

digest_md5.php

Perform digest authentication.

You can get help for these scripts by typing the script name followed by --help on the command line. You must be able to run PHP from the command line. Some configuration is required to make the scripts work properly:

1. Set up a secure database

   You can set up a password database in the same way you create a Drupal database. Your password database should have its own user. No other database users should have access to the password database.

2. Edit the configuration file

   Configuration settings for the scripts are in the digest_md5.conf.php file in the digest_md5 directory. You must set $db_url to point to your password database. If you want to be able to use the scripts from the command-line, you must set $drupal to the absolute path of your Drupal installation. When you are done editing the configuration file, make it read-only.

3. Control access to the scripts

   The first thing you can do to secure the scripts is to move the digest_md5 directory to a location that is not accessible from the Internet. The configuration file especially needs protection, because it contains information that allows access to the password database. On the Secure Site settings page, change the digest authentication script and password storage script to point to the new location. For example, if you moved the digest_md5 directory to /usr/local, you would use

   /usr/local/digest_md5/digest_md5.php
   /usr/local/digest_md5/stored_passwords.php
   

   If the sudo command is available on your system, you can change the file system permissions on the all the files in the digest_md5 directory so that only adminstrators have access to them. You would then add the user your Web server runs as to the sudoers file. A sample sudoers file is provided in the digest_md5 directory for comparison. The important lines are

   Defaults:apache	!authenticate
   Defaults:apache	!lecture
   apache	ALL=/usr/local/digest_md5/stored_passwords.php [A-z]*
   apache	ALL=/usr/local/digest_md5/digest_md5.php [A-z]*
   

   This allows apache to use sudo only to run stored_passwords.php and digest_md5.php. Replace apache with the name of the Web server user on your system, and replace /usr/local with the directory in which you placed the digest_md5 directory. On the Secure Site settings page, add sudo at the beginning of the line for the digest authentication script and the password storage script:

   sudo /usr/local/digest_md5/digest_md5.php
   sudo /usr/local/digest_md5/stored_passwords.php
   

   If the rest of your system is secure, Drupal can now store passwords without having the ability to retrieve them.