Courier::Filter::Module::SPF (3pm)

    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 ],
        ...
    );

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

The point of inbound \s-1SPF\s0 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 \s-1SPF\s0 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 \s-1SPF\s0 check is to be performed. Defaults to 'mfrom'. See \*(L"scope\*(R" in Mail::SPF::Request for a detailed explanation.

match_on

A reference to an array containing the set of \s-1SPF\s0 result codes which should cause the filter module to match a message. Possible result codes are \*(C`pass\*(C', \*(C`fail\*(C', \*(C`softfail\*(C', \*(C`neutral\*(C', \*(C`none\*(C', \*(C`permerror\*(C', and \*(C`temperror\*(C'. See the \s-1SPF\s0 specification for details on the meaning of those. If \*(C`temperror\*(C' is listed, a \*(C`temperror\*(C' result will by definition never cause a permanent rejection, but only a temporary one. Defaults to ['fail', 'permerror', 'temperror']. Note: With early \s-1SPF\s0 specification drafts as well as the obsolete Mail::SPF::Query module, the \*(C`permerror\*(C' and \*(C`temperror\*(C' result codes were known as \*(C`unknown\*(C' and \*(C`error\*(C', 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 \*(C`match_on\*(C' option includes the result code of the \s-1SPF\s0 check (by default when a message fails the \s-1SPF\s0 check). However, this default response is used only if the (claimed) \s-1MAIL\s0 \s-1FROM\s0 or \s-1HELO\s0 domain does not provide a result explanation of its own. See \*(L"default_authority_explanation\*(R" in Mail::SPF::Server for more information. \s-1SPF\s0 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 \*(L"new\*(R" in Mail::SPF::Server for the supported options. If any of Mail::SPF::BlackMagic's additional options, such as \*(C`default_policy\*(C' (best-guess) or \*(C`tfwl\*(C' (\*(C`trusted-forwarder.org\*(C' accreditation checking), are specified, a black-magic \s-1SPF\s0 server object will be created instead.

fallback_guess

trusted_forwarders

Deprecated. These options should now be specified as \*(C`default_policy\*(C' and \*(C`tfwl\*(C' keys of the \*(L"spf_options\*(R" 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 \*(L"new\*(R" in Courier::Filter::Module for their descriptions.

Instance methods

See \*(L"Instance methods\*(R" in Courier::Filter::Module for a description of the provided instance methods.

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

For \s-1AVAILABILITY\s0, \s-1SUPPORT\s0, and \s-1LICENSE\s0 information, see Courier::Filter::Overview.

\s-1SPF\s0 website (Sender Policy Framework)

<http://www.openspf.org>

\s-1SPF\s0 specification

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

Julian Mehnle <[email protected]>