NAME

       Courier::Filter::Module::SPF - SPF filter module for the Courier::Filter framework

SYNOPSIS

           use Courier::Filter::Module::SPF;

           my $module = Courier::Filter::Module::SPF->new(
               scope               => 'mfrom' || 'helo',
               match_on            => ['fail', 'permerror', 'temperror'],
               default_response    => $default_response_text,
               spf_options         => {
                   # any Mail::SPF::Server options
               },

               logger      => $logger,
               inverse     => 0,
               trusting    => 0,
               testing     => 0,
               debugging   => 0
           );

           my $filter = Courier::Filter->new(
               ...
               modules     => [ $module ],
               ...
           );

DESCRIPTION

       This class is a filter module class for use with Courier::Filter.  By default, it matches a message if
       the sending machine's IP address is not authorized to send mail from the envelope sender's (MAIL FROM)
       domain according to that domain's SPF (Sender Policy Framework) DNS record.  This is classic inbound SPF
       checking.

       The point of inbound SPF checking is for receivers to protect themselves against forged envelope sender
       addresses in messages sent by others.

   Constructor
       The following constructor is provided:

       new(%options): returns Courier::Filter::Module::SPF
           Creates a new SPF filter module.

           %options is a list of key/value pairs representing any of the following options:

           scope
               A  string  denoting  the  authorization  scope,  i.e.,  identity, on which the SPF check is to be
               performed.  Defaults to 'mfrom'.  See "scope" in Mail::SPF::Request for a detailed explanation.

           match_on
               A reference to an array containing the set of SPF result codes  which  should  cause  the  filter
               module  to  match  a  message.   Possible result codes are "pass", "fail", "softfail", "neutral",
               "none", "permerror", and "temperror".  See the SPF specification for details on  the  meaning  of
               those.  If "temperror" is listed, a "temperror" result will by definition never cause a permanent
               rejection, but only a temporary one.  Defaults to ['fail', 'permerror', 'temperror'].

               Note:   With  early SPF specification drafts as well as the obsolete Mail::SPF::Query module, the
               "permerror" and "temperror" result codes were known as "unknown" and "error",  respectively;  the
               old codes are now deprecated but still supported for the time being.

           default_response
               A string that is to be returned as the module's match result in case of a match, that is when the
               "match_on"  option includes the result code of the SPF check (by default when a message fails the
               SPF check).  However, this default response is used only if  the  (claimed)  MAIL  FROM  or  HELO
               domain  does not provide a result explanation of its own.  See "default_authority_explanation" in
               Mail::SPF::Server for more information.

               SPF macro substitution is performed on the default response, just like on  explanations  provided
               by domain owners.  If undef, Mail::SPF's default explanation will be used.  Defaults to undef.

           spf_options
               A  hash-ref  specifying  options for the Mail::SPF server object used by this filter module.  See
               "new" in  Mail::SPF::Server  for  the  supported  options.   If  any  of  Mail::SPF::BlackMagic's
               additional  options,  such  as  "default_policy"  (best-guess) or "tfwl" ("trusted-forwarder.org"
               accreditation checking), are specified, a black-magic SPF server object will be created instead.

           fallback_guess
           trusted_forwarders
               Deprecated.  These options should now be specified as "default_policy" and  "tfwl"  keys  of  the
               "spf_options"  option  instead,  although these legacy options will continue to work for the time
               being.  Furthermore, due to the move from the obsolete Mail::SPF::Query module to  the  Mail::SPF
               reference  implementation,  the Mail::SPF::BlackMagic extension module is now required when using
               these non-standard options.

           All options of the Courier::Filter::Module constructor are  also  supported.   Please  see  "new"  in
           Courier::Filter::Module for their descriptions.

   Instance methods
       See "Instance methods" in Courier::Filter::Module for a description of the provided instance methods.

SEE ALSO

       Courier::Filter::Module, Courier::Filter::Overview, Mail::SPF.

       For AVAILABILITY, SUPPORT, and LICENSE information, see Courier::Filter::Overview.

REFERENCES

       SPF website (Sender Policy Framework)
           <http://www.openspf.org>

       SPF specification
           <http://www.openspf.org/Specifications>

AUTHOR

       Julian Mehnle <julian@mehnle.net>

perl v5.20.2                                       2015-11-28                  Courier::Filter::Module::SPF(3pm)