NAME
   Mail::SRS - Interface to Sender Rewriting Scheme

SYNOPSIS
           use Mail::SRS;
           my $srs = new Mail::SRS(
                   Secret     => [ .... ],    # scalar or array
                   MaxAge     => 49,          # days
                   HashLength => 4,           # base64 characters: 4 x 6bits
                   HashMin    => 4,           # base64 characters
                           );
           my $srsaddress = $srs->forward($sender, $alias);
           my $sender = $srs->reverse($srsaddress);

DESCRIPTION
   The Sender Rewriting Scheme preserves .forward functionality in an
   SPF-compliant world.

   SPF requires the SMTP client IP to match the envelope sender
   (return-path). When a message is forwarded through an intermediate
   server, that intermediate server may need to rewrite the return-path to
   remain SPF compliant. If the message bounces, that intermediate server
   needs to validate the bounce and forward the bounce to the original
   sender.

   SRS provides a convention for return-path rewriting which allows
   multiple forwarding servers to compact the return-path. SRS also
   provides an authentication mechanism to ensure that purported bounces
   are not arbitrarily forwarded.

   SRS is documented at http://spf.pobox.com/srs.html and many points about
   the scheme are discussed at http://www.anarres.org/projects/srs/

   For a better understanding of this code and how it functions, please run
   the interactive walkthrough in eg/simple.pl in this distribution. To run
   this from the build directory, type "make teach".

METHODS
 $srs = new Mail::SRS(...)
   Construct a new Mail::SRS object and return it. Available parameters
   are:

   Secret => $string
       A key for the cryptographic algorithms. This may be an array or a
       single string. A string is promoted into an array of one element.

   MaxAge
       The maximum number of days for which a timestamp is considered
       valid. After this time, the timestamp is invalid.

   HashLength => $integer
       The number of bytes of base64 encoded data to use for the
       cryptographic hash. More is better, but makes for longer addresses
       which might exceed the 64 character length suggested by RFC2821.
       This defaults to 4, which gives 4 x 6 = 24 bits of cryptographic
       information, which means that a spammer will have to make 2^24
       attempts to guarantee forging an SRS address.

   HashMin => $integer
       The shortest hash which we will allow to pass authentication. Since
       we allow any valid prefix of the full SHA1 HMAC to pass
       authentication, a spammer might just suggest a hash of length 0. We
       require at least HashMin characters, which must all be correct.
       Naturally, this must be no greater than HashLength and will default
       to HashLength unless otherwise specified.

   Separator => $character
   Some subclasses require other parameters. See their documentation for
   details.

 $srsaddress = $srs->forward($sender, $alias)
   Map a sender address into a new sender and a cryptographic cookie.
   Returns an SRS address to use as the new sender.

   There are alternative subclasses, some of which will return SRS
   compliant addresses, some will simply return non-SRS but valid RFC821
   addresses. See the interactive walkthrough for more information on this
   ("make teach").

 $sender = $srs->reverse($srsaddress)
   Reverse the mapping to get back the original address. Validates all
   cryptographic and timestamp information. Returns the original sender
   address.

 $srs->compile($sendhost, $senduser)
   This method, designed to be overridden by subclasses, takes as
   parameters the original host and user and must compile a new username
   for the SRS transformed address. It is expected that this new username
   will be joined on $SRSSEP, and will contain a hash generated from
   $self->hash_create(...), and possibly a timestamp generated by
   $self->timestamp_create().

 $srs->parse($srsuser)
   This method, designed to be overridden by subclasses, takes an
   SRS-transformed username as an argument, and must reverse the
   transformation produced by compile(). It is required to verify any hash
   and timestamp in the parsed data, using $self->hash_verify($hash, ...)
   and $self->timestamp_check($timestamp).

 $srs->timestamp_create([$time])
   Return a two character timestamp representing 'today', or $time if
   given. $time is a Unix timestamp (seconds since the aeon).

 $srs->timestamp_check($timestamp)
   Return 1 if a timestamp is valid, undef otherwise. There are 4096
   possible timestamps, used in a cycle. At any time, $srs->{MaxAge}
   timestamps in this cycle are valid, the last one being today. A
   timestamp from the future is not valid, neither is a timestamp from too
   far into the past. Of course if you go far enough into the future, the
   cycle wraps around, and there are valid timestamps again, but the
   likelihood of a random timestamp being valid is 4096/$srs->{MaxAge},
   which is usually quite small: 1 in 132 by default.

 $srs->time_check($time)
   Similar to $srs->timestamp_check($timestamp), but takes a Unix time, and
   checks that an alias created at that Unix time is still valid. This is
   designed for use by subclasses with storage backends.

 $srs->hash_create(@data)
   Returns a cryptographic hash of all data in @data. Any piece of data
   encoded into an address which must remain inviolate should be hashed, so
   that when the address is reversed, we can check that this data has not
   been tampered with. You must provide at least one piece of data to this
   method (otherwise this system is both cryptographically weak and there
   may be collision problems with sender addresses).

 $srs->hash_verify($hash, @data)
   Verify that @data has not been tampered with, given the cryptographic
   hash previously output by $srs->hash_create(); Returns 1 or undef. All
   known secrets are tried in order to see if the hash was created with an
   old secret.

 $srs->set_secret($new, @old)
   Add a new secret to the rewriter. When an address is returned, all
   secrets are tried to see if the hash can be validated. Don't use "foo".

 $srs->get_secret()
   Return the list of secrets. These are secret. Don't publish them.

 $srs->separator()
   Return the initial separator, which follows the SRS tag. This is only
   used as the initial separator, for the convenience of administrators who
   wish to make srs0 and srs1 users on their mail servers and require to
   use + or - as the user delimiter. All other separators in the SRS
   address must be "=".

EXPORTS
   Given :all, this module exports the following variables.

   $SRSSEP
       The SRS separator. The choice of "=" as internal separator was
       fairly arbitrary. It cannot be any of the following:

       / + Used in Base64.

       -   Used in domains.

       ! % Used in bang paths and source routing.

       :   Cannot be used in a Windows NT or Apple filename.

       ; | *
           Shell or regular expression metacharacters are probably to be
           avoided.

   $SRS0TAG
       The SRS0 tag.

   $SRS1TAG
       The SRS1 tag.

   $SRSTAG
       Deprecated, equal to $SRS0TAG.

   $SRSWRAP
       Deprecated, equal to $SRS1TAG.

EXTENDING Mail::SRS
   Write a subclass. If people mail me asking for callbacks with the hash
   data from the standard subclasses, I will provide them. Callback hooks
   have not been provided in this release candidate.

WARNING: MINOR CHANGES since v0.18
   $SRSTAG and $SRSWRAP are deprecated.

   You must use $SRS0RE and $SRS1RE to detect SRS addresses.

WARNING: MAJOR CHANGES since v0.15
   The separator character is now "=".
   The cryptographic scheme is now HMAC with SHA1.
   Only a prefix of the MAC is used.

   This API is still a release candidate and should remain relatively
   stable.

BUGS
   Email address parsing for quoted addresses is not yet done properly.

   More error checking should be done for invalid SRS addresses.

SEE ALSO
   Mail::SRS::Guarded, Mail::SRS::DB, Mail::SRS::Reversable, "make teach",
   eg/*, http://www.anarres.org/projects/srs/

AUTHOR
           Shevek
           CPAN ID: SHEVEK
           [email protected]
           http://www.anarres.org/projects/

COPYRIGHT
   Copyright (c) 2004 Shevek. All rights reserved.

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.