NAME
    Mail::SpamAssassin::Plugin::AuthRes - use Authentication-Results header
    fields

SYNOPSIS
  SpamAssassin configuration:
    loadplugin Mail::SpamAssassin::Plugin::AuthRes

    authres_trusted_authserv myserv.example.com authres_networks all

DESCRIPTION
    This plugin parses Authentication-Results header fields and can supply
    the results obtained to other plugins, so as to avoid repeating checks
    that have been performed already.

ADMINISTRATOR SETTINGS
    authres_networks internal/trusted/all (default: internal)
        Process Authenticated-Results headers set by servers from these
        networks (refers to SpamAssassin *_networks zones). Any header
        outside this is completely ignored (affects all module settings).

         internal   = internal_networks
         trusted    = internal_networks + trusted_networks
         all        = all above + all external

        Setting "all" is safe only if your MX servers filter properly all
        incoming A-R headers, and you use authres_trusted_authserv to match
        your authserv-id. This is suitable for default OpenDKIM for example.
        These settings might also be required if your filters do not insert
        A-R header to correct position above the internal Received header
        (some known offenders: OpenDKIM, OpenDMARC, amavisd-milter).

    authres_trusted_authserv authservid1 id2 ... (default: none)
        Trusted authentication server IDs (the domain-name-like first word
        of Authentication-Results field, also known as "authserv-id").

        Note that if set, ALL A-R headers are ignored unless a match is
        found.

        Use strongly recommended, possibly along with authres_networks all.

    authres_ignored_authserv authservid1 id2 ... (default: none)
        Ignored authentication server IDs (the domain-name-like first word
        of Authentication-Results field, also known as "authserv-id").

        Any A-R header is ignored if match is found.

METADATA
    Parsed headers are stored in $pms->{authres_parsed}, as a hash of array
    of hashes where results are collected by method. For example, the header
    field:

      Authentication-Results: server.example.com;
        spf=pass smtp.mailfrom=bounce.example.org;
        dkim=pass header.i=@example.org;
        dkim=fail header.i=@another.signing.domain.example

    Produces the following structure:

     $pms->{authres_parsed} = {
       'dkim' => [
         {
           'properties' => {
             'header' => {
               'i' => '@example.org'
             }
           },
           'authserv' => 'server.example.com',
           'result' => 'pass',
           'version' => 1,
           'reason' => ''
         },
         {
           'properties' => {
             'header' => {
               'i' => '@another.signing.domain.example'
             }
           },
           'result' => 'fail',
           'authserv' => 'server.example.com',
           'version' => 1,
           'reason' => ''
         },
       ],
     }

    Within each array, the order of results is the original, which should be
    most recent results first.

    For checking result of methods, $pms->{authres_result} is available:

     $pms->{authres_result} = {
       'dkim' => 'pass',
       'spf' => 'fail',
     }

EVAL FUNCTIONS
    header RULENAME eval:check_authres_result(method, result)
        Can be used to check results.

        Reference of valid result methods and values:
        "https://www.iana.org/assignments/email-auth/email-auth.xhtml"

        Additionally the result value of 'missing' can be used to check if
        there is no result at all.

          ifplugin Mail::SpamAssassin::Plugin::AuthRes
          ifplugin !(Mail::SpamAssassin::Plugin::SPF)
            header  SPF_PASS      eval:check_authres_result('spf', 'pass')
            header  SPF_FAIL      eval:check_authres_result('spf', 'fail')
            header  SPF_SOFTFAIL  eval:check_authres_result('spf', 'softfail')
            header  SPF_TEMPFAIL  eval:check_authres_result('spf', 'tempfail')
          endif
          ifplugin !(Mail::SpamAssassin::Plugin::DKIM)
            header  DKIM_VERIFIED  eval:check_authres_result('dkim', 'pass')
            header  DKIM_INVALID   eval:check_authres_result('dkim', 'fail')
          endif
          endif