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: OffDESCRIPTION
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.