The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Apache2::AuthenDBMCache - Authentication caching

SYNOPSIS

 # In your httpd.conf

 PerlModule Apache2::AuthenDBMCache

 # In httpd.conf or .htaccess:

 AuthName Name
 AuthType Basic

 PerlAuthenHandler Apache2::AuthenDBMCache <Primary Authentication Module>

 # Typical constraints one of these

 require valid-user
 require user larry moe curly
 require group stooges

 # Optional parameters/Defaults are listed to the right.

 PerlSetVar AuthenDBMCache_File /file-path # Default: /var/cache/authen-web
 PerlSetVar AuthenDBMCache_TTL         900 # Default: 3600 sec
 PerlSetVar AuthenDBMCache_Debug        On # Default: Off

DESCRIPTION

Apache2::AuthenDBMCache implements a caching mechanism in order to speed up authentication and to reduce the usage of system resources. It must be used in conjunction with a regular mod_perl2 authentication module (we use it to accelerate AuthenURL and AuthenMSAD methods but it can be used with any perl authentication module).

When a authorization request is received this handler uses a DBM data base cache to answer the request. Each entry in the cache is indexed by a key which is a hash of user name, the authentication "realm", the authentication parameters and the password. The value at the key is an expiration date. If the supplied user name and password hash to a key which exists and has not expired then the handler returns OK and clears the downstream Authen handlers from the stack. Otherwise, it returns DECLINED and allows the next PerlAuthenHandler in the stack to be called.

After the primary authentication handler completes with an OK, AuthenDBMCache adds the new hash to the cache with an appropriate expiration date.

CONFIGURATION OPTIONS

The following variables can be defined within the configuration of Directory, Location, or Files blocks or within .htaccess files.

PerlSetVar AuthenDBMCache_File /var/file/path

The AuthenDBMCache_File variable specifices an alternate cache location. The default is /var/cache/authen-web/cache -- the cache database and the direcotries containing the cache need to be protected.

PerlSetVar AuthenDBMCache_TTL 3600

The AuthenDBMCache_TTL variable contains the "Time to Live" in seconds of entries within the cache. The default value is one hour (3600 seconds). When entries are created in the cache they're marked with an expiration date calculated from the TTL value.

PerlSetVar AuthenDBMCache_Debug off

If the AuthenDBMCache_Debug variable is set to "on" some debugging messages are logged.

FUNCTIONS

The function Apache2::AuthenDBMCache::ExpireCache will expire all cache entries that are no longer current. However, it's much easier to just clobber the cache file.

BUGS/BEWARE

The cache and directory holding the cache (in the /var/cache/authen-web directory) should exist and belong to the userid of the web server. They should be protected so that nobody else can read them. The module will croak if it cannot access the cached authentication data.

We make no effort to lock the database. The worst case that can happen is we return a false negative and that has no serious consequences.

Other processes are required to purge the cache of entries which have expired -- you can clear the entire cache periodically (ie. remove the file or clear it with /dev/null) or use the Apache2::AuthenDBMCache::ExpireCache function to clear entries in the cache.

A caching mechanism is vulnerable to cache-poisoning -- we have made an effort to prevent that but you should be cautious. Especially on multi-user systems with users who aren't trustworthy.

The cache is not indexed by "userid" and the key is a one way hash that includes the userid, password and more -- that is intentional. We don't want bad guys cracking passwords out of the cache.

SEE ALSO

httpd(8), mod_perl2(1), Digest::MD5

AUTHORS

Reg Quinton <reggers@uwaterloo.ca> from AuthenCache by Jason Bodnar and Christian Gilmore.

COPYRIGHT

Copyright (C) 2002-2006, Reg Quinton. AuthenCache Copyright (C) 1998-2001, Jason Bodnar.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.