Apache Cookbook-Apache Cookbook

Recipe 6.7 Managing .htpasswd Files

Problem

You wish to create password files for use with Basic HTTP authentication.

Solution

Use the htpasswd utility to create your password file, as in Table 6-1.

Table 6-1. Managing password files with htpasswd

Command

Action

% htpasswd -c user.pass waldo

Create a new password file called user.pass with this one new entry for user waldo. Will prompt for password.

% htpasswd user.pass ralph

Add an entry for user ralph in password file user.pass. Will prompt for password.

% htpasswd -b user.pass ralph mydogspot

Add a user ralph to password file user.pass with password mydogspot.

Or, use the Perl module Apache::Htpasswd to manage the file programmatically:

use Apache::Htpasswd;
$pass = new Apache::Htpasswd("/usr/local/apache/passwords/user.pass") or
die "Couldn't open password file.";

# Add an entry    
$pass->htpasswd("waldo", "emerson");

# Delete entry
$pass->htDelete("waldo");

Discussion

The htpasswd utility, which comes with Apache, is located in the bin subdirectory.

On some third-party distributions of Apache, the htpasswd program has been copied into a directory in your path, but ordinarily it will not be in your path; you will either have to put it there, or provide the full path to the program in order to run it, such as /usr/local/apache/bin/htpasswd.

The first line of the Solution creates a new password file at the specified location. That is, in the example given, it creates a new password file called user.pass, containing a username and password for a user waldo. You will be prompted to enter the desired password, and then prompted to repeat the password for confirmation.

The -c flag creates a new password file, even if a file of that name already exists, so make sure that you only use this flag the first time. After that, using it causes your existing password file to be obliterated and replaced with the (almost empty) new one.

The second line in the Solution adds a password to an existing password file. As before, the user is prompted to enter the desired password, and then prompted to confirm it by typing it again.

The examples given here create a password file using the crypt algorithm by default on all platforms other than Windows, Netware, and TPF. On those platforms, the MD5 algorithm is used by default.

For platforms that use crypt, each line of the password file looks something like:

waldo:/z32oW/ruTI8U

The portion of the line following the username and colon is the encrypted password. Other usernames and passwords appear one per line.

The htpasswd utility provides other options, such as the ability to use the MD5 algorithm to encrypt the password (the -m flag), provide the password on the command line rather than being prompted for it (the -b flag), or print the results to stdout, rather than altering the password file (the -n flag).

The -b flag can be particularly useful when using the htpasswd utility to create passwords in some scripted fashion, rather than from an interactive prompt. The third line of the recipe above illustrates this syntax.

As of Apache 2.0.46, the -D flag lets you delete an existing user from the password file:

% htpasswd -D  user.pass waldo

whereas in previous versions, you would need to use some alternate method to remove lines from the file. For example, you could remove a line using grep, or simply open the file in a text editor:

% egrep -v '^waldo:' user.pass >!  user.pass

Apache::Htpasswd, written by Kevin Meltzer, is available from CPAN (http://cpan.org/) and gives a Perl interface to Apache password files. This allows you to modify your password files from CGI programs or via other mechanisms, using just a few lines of Perl code as shown in the recipe.

In addition to the methods demonstrated in this recipe, there are also methods for checking a particular password against the contents of the password file, obtaining a list of users from the file, or retrieving the encrypted password for a particular user, among other things. See the documentation for this fine module for the full details on its many features.

One final note about your password file. We strongly recommend that you store your password file in some location that is not accessible through the Web (i.e., outside of your document directory). By putting it in your document directory, you run the risk of someone downloading the file and running a brute-force password cracking algorithm against it, which will eventually yield your passwords for them to use.

Recipe 6.7 Managing .htpasswd Files

Problem

Solution

Table 6-1. Managing password files with htpasswd

Discussion

See Also