NAME

Authen::PluggableCaptcha::KeyManager

DESCRIPTION

This is the base class for managing captcha keys ( public facing captcha identifiers)

DESCRIPTION

This is the base class for managing captcha keys ( public facing captcha identifiers)

This class consolidates the routines previously available in the KeyGenerator and KeyValidator classes

By default , this class always returns true on validate_publickey There is no validation supported other than the timeliness provided by the key generation element.

This should be subclassed to provide for better implementations

This module supports the following functions:

        new
        validate_publickey
        generate_publickey
        expire_publickey

CONSTRUCTOR

new PARAMS: Returns a new Authen::PluggableCaptcha::KeyManager ( or dervied ) object constructed according to PARAMS, where PARAMS are name/value pairs.
PARAMS are required name/value pairs. Required PARAMS are:

"seed TYPE": seed used for key management. this could be a session id, a session id + url, an empty string, or any other defined value.
"site_secret TYPE": site_secret used for key management. this could be a shared value for your website.
"time_expiry INT": time_expiry - how many seconds is the captcha good for?
"time_expiry_future INT": time_expiry_future - how many seconds in the future can a captcha be valid for ( for use in clusters where clocks may not be in sync )
"time_now INT": time_now - current unix timestamp

OBJECT METHODS

validate_publickey

this is where you'd subclass and toss in functions that handles:

        is this key in the  right format ? ( regex )
        was this key ever used before? ( one time user )
        was this key accessed by more than one ip ?
        etc.

returns 1 : valid 0 : invalid -1 : error

expire_publickey

handle expiring the key here. this is a null function by default ( you shouldn't be able to expire a non-db backed key )

if this passed, we should do $self->EXPIRED(1); $self->INVALID(1);

so that the captcha won't be used again.

generate_publickey

Returns a hash to be used for creating captchas.

By default,this hash is based on the time , seed , and site_secrect.

It is implemented as a seperate function to be replaced by subclasses

init_existing hoook called when initializing an existing captcha

        returns:
                1 on valid key
                0 on expired/invalid  key
                -1 on error (wrong format , missing args )

DEBUGGING

Set the Following envelope variables for debugging

        $ENV{'Authen::PluggableCaptcha::KeyManager-DEBUG_FUNCTION_NAME'}

debug messages are sent to STDERR via the ErrorLoggingObject package