svn commit: r1846448 - /spamassassin/trunk/lib/Mail/SpamAssassin/Plugin/AuthRes.pm

[he...@apache.org]

Author: hege
Date: Mon Nov 12 17:09:35 2018
New Revision: 1846448

URL: http://svn.apache.org/viewvc?rev=1846448&view=rev
Log:
Clarify documentation, recommend authres_networks all / authres_trusted_authserv combo.

Modified:
    spamassassin/trunk/lib/Mail/SpamAssassin/Plugin/AuthRes.pm

Modified: spamassassin/trunk/lib/Mail/SpamAssassin/Plugin/AuthRes.pm
URL: http://svn.apache.org/viewvc/spamassassin/trunk/lib/Mail/SpamAssassin/Plugin/AuthRes.pm?rev=1846448&r1=1846447&r2=1846448&view=diff
==============================================================================
--- spamassassin/trunk/lib/Mail/SpamAssassin/Plugin/AuthRes.pm (original)
+++ spamassassin/trunk/lib/Mail/SpamAssassin/Plugin/AuthRes.pm Mon Nov 12 17:09:35 2018
@@ -25,6 +25,9 @@ Mail::SpamAssassin::Plugin::AuthRes - us
 
 loadplugin     Mail::SpamAssassin::Plugin::AuthRes
 
+authres_trusted_authserv  myserv.example.com
+authres_networks  all
+
 =head1 DESCRIPTION
 
 This plugin parses Authentication-Results header fields and can supply the
@@ -112,16 +115,18 @@ sub set_config {
 
 Process Authenticated-Results headers set by servers from these networks
 (refers to SpamAssassin *_networks zones).  Any header outside this is
-completely ignored and affects any module settings.
+completely ignored (affects all module settings).
 
  internal   = internal_networks
  trusted    = internal_networks + trusted_networks
  all        = all above + all external
 
-Setting "all" makes sense only if your MX servers filter properly all
-incoming A-R headers.  Even then it might be safer to just extend SA
-trusted_networks to any external servers whose A-R you want to see, and use
-the "trusted" setting.
+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).
 
 =cut
 
@@ -144,17 +149,21 @@ the "trusted" setting.
     }
   });
 
-=item authres_ignored_authserv authservid1 id2 ...   (default: none)
+=item authres_trusted_authserv authservid1 id2 ...   (default: none)
 
-Ignored authentication server IDs (the domain-name-like first word of
+Trusted authentication server IDs (the domain-name-like first word of
 Authentication-Results field, also known as C<authserv-id>).
 
-Any A-R header is ignored if match is found.
+Note that if set, ALL A-R headers are ignored unless a match is found.
+
+Use strongly recommended, possibly along with authres_networks all.
+
+=back
 
 =cut
 
   push (@cmds, {
-    setting => 'authres_ignored_authserv',
+    setting => 'authres_trusted_authserv',
     is_admin => 1,
     default => {},
     type => $Mail::SpamAssassin::Conf::CONF_TYPE_HASH_KEY_VALUE,
@@ -164,24 +173,25 @@ Any A-R header is ignored if match is fo
         return $Mail::SpamAssassin::Conf::MISSING_REQUIRED_VALUE;
       }
       foreach my $id (split(/\s+/, lc $value)) {
-        $self->{authres_ignored_authserv}->{$id} = 1;
+        $self->{authres_trusted_authserv}->{$id} = 1;
       }
     }
   });
 
-=item authres_trusted_authserv authservid1 id2 ...   (default: none)
+  $conf->{parser}->register_commands(\@cmds);
+}
 
-Trusted authentication server IDs (the domain-name-like first word of
-Authentication-Results field, also known as C<authserv-id>).
+=item authres_ignored_authserv authservid1 id2 ...   (default: none)
 
-Note that if set, ALL A-R headers are ignored unless a match is found.
+Ignored authentication server IDs (the domain-name-like first word of
+Authentication-Results field, also known as C<authserv-id>).
 
-=back
+Any A-R header is ignored if match is found.
 
 =cut
 
   push (@cmds, {
-    setting => 'authres_trusted_authserv',
+    setting => 'authres_ignored_authserv',
     is_admin => 1,
     default => {},
     type => $Mail::SpamAssassin::Conf::CONF_TYPE_HASH_KEY_VALUE,
@@ -191,14 +201,11 @@ Note that if set, ALL A-R headers are ig
         return $Mail::SpamAssassin::Conf::MISSING_REQUIRED_VALUE;
       }
       foreach my $id (split(/\s+/, lc $value)) {
-        $self->{authres_trusted_authserv}->{$id} = 1;
+        $self->{authres_ignored_authserv}->{$id} = 1;
       }
     }
   });
 
-  $conf->{parser}->register_commands(\@cmds);
-}
-
 =head1 METADATA
 
 Parsed headers are stored in $pms-E<gt>{authres_parsed}, as a hash of array