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>