NAME

Email::Auth::AddressHash - Authentication based on email address extension hash

SYNOPSIS

use Email::Auth::AddressHash;

my $auth = Email::Auth::AddressHash->new('hashlen' => 8, 'secret' = 'My Secret');

my $is_valid = $auth->check_hash('myuser@theirdomain.com', '83c3dac5');

my $correct_answer = $auth->generate_hash('myuser@theirdomain.com');

my $parts = $auth->split_address('myaddr+38274dc9@mydomain.com');

my $passedhash = $parts->{'hash'};

DESCRIPTION

This is a relatively simple module designed for applications which receive email. It provides a mechanism for authenticating email requests, by checking that the To: address, which should be in the form "username+hash@mydomain.com", contains the correct hash value for that particular sender. It uses the sender address and a locally-set secret string to determine the correct hash for the user. A single AddressHash object may be used for multiple authentication checks within the same system.

METHODS

Email::Auth::AddressHash->new($secret, $hashlen, $prefix, $hashtype)

Takes four arguments. They are listed with their defaults. They are described more fully in the ACCESSORS section. 'secret' - PLEASE set this; the default is stupid on purpose. 'hashlen' - Default is 6. 'prefix' - Default is no prefix. 'hashtype' - Default (and only supported type) is md5.

If you do use a hash prefix, you may skip setting the 'prefix' variable if you wish, just realize that you will have to strip the prefix yourself before passing your hash to check_auth, instead of letting the split_address method (see below) do it for you.

$authenticator->check_hash($sender_address, $hashstring)

Takes two arguments, the sender's address and the email extension that the sender sent his/her request to. Returns true or false, indicating whether the given hash matches the calculated hash.

$authenticator->generate_hash($sender_address, $with_prefix)

Takes a single argument, the sender's address. Returns the correctly calculated hash for the given sender. If $with_prefix is set to a true value, the instance prefix (if any) is prepended.

$partsref = $authenticator->split_address($address)

$rcvdhash = $authenticator->split_address($address)->{'extension'}

A convenience method. Takes an email address and returns a reference to a hash containing the keys 'username', 'extension', and 'domain'. Returns undef if parsing failed. This is a fine way to isolate the hash to test against.

INSTANCE VARIABLES AND THEIR ACCESSORS

$authenticator->set_secret('My Secret')

$authenticator->get_secret()

The authenticator secret is a string that is used in the hashing algorithm. It should be set locally in your program. It should not change too often, unless you like annoying your users by changing the email address they should use for your program all the time.

$authenticator->set_prefix('ma')

$authenticator->get_prefix()

The prefix is a fixed string that you expect to appear at the beginning of every email extension received by your application. You may not need this, but it is useful if you expect a single email account to be able to run several different programs, and want to differentiate the requests via something like procmail. In the above example, with the prefix set to 'ma', users should send all requests to an address like myprog+ma38c319@mydomain.com.

$authenticator->set_hashlen($length)

$authenticator->get_hashlen()

This is the length you expect your authentication hashes to be, not counting any prefix you have set. The default length is 6.

$authenticator->set_hashtype($type)

$authenticator->get_hashtype()

This is the hashing algorithm that the module should use. Currently the only supported algorithm is md5.

AUTHOR

Tara L Andrews <tla@mit.edu>

SEE ALSO

Digest::MD5