.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mail::SpamAssassin::Plugin::AuthRes 3pm"
.TH Mail::SpamAssassin::Plugin::AuthRes 3pm "2022-09-10" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mail::SpamAssassin::Plugin::AuthRes \- use Authentication\-Results header fields
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.SS "SpamAssassin configuration:"
.IX Subsection "SpamAssassin configuration:"
loadplugin     Mail::SpamAssassin::Plugin::AuthRes
.PP
authres_trusted_authserv  myserv.example.com
authres_networks  all
.SH "DESCRIPTION"
.IX Header "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.
.SH "ADMINISTRATOR OPTIONS"
.IX Header "ADMINISTRATOR OPTIONS"
.IP "authres_networks internal/trusted/all    (default: internal)" 4
.IX Item "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).
.Sp
.Vb 3
\& internal   = internal_networks
\& trusted    = internal_networks + trusted_networks
\& all        = all above + all external
.Ve
.Sp
Setting \*(L"all\*(R" is safe only if your \s-1MX\s0 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).
.IP "authres_trusted_authserv authservid1 id2 ...   (default: none)" 4
.IX Item "authres_trusted_authserv authservid1 id2 ... (default: none)"
Trusted authentication server IDs (the domain-name-like first word of
Authentication-Results field, also known as \f(CW\*(C`authserv\-id\*(C'\fR).
.Sp
Note that if set, \s-1ALL A\-R\s0 headers are ignored unless a match is found.
.Sp
Use strongly recommended, possibly along with authres_networks all.
.IP "authres_ignored_authserv authservid1 id2 ...   (default: none)" 4
.IX Item "authres_ignored_authserv authservid1 id2 ... (default: none)"
Ignored authentication server IDs (the domain-name-like first word of
Authentication-Results field, also known as \f(CW\*(C`authserv\-id\*(C'\fR).
.Sp
Any A\-R header is ignored if match is found.
.SH "METADATA"
.IX Header "METADATA"
Parsed headers are stored in \f(CW$pms\fR\->{authres_parsed}, as a hash of array
of hashes where results are collected by method.  For example, the header
field:
.PP
.Vb 4
\&  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
.Ve
.PP
Produces the following structure:
.PP
.Vb 10
\& $pms\->{authres_parsed} = {
\&   \*(Aqdkim\*(Aq => [
\&     {
\&       \*(Aqproperties\*(Aq => {
\&         \*(Aqheader\*(Aq => {
\&           \*(Aqi\*(Aq => \*(Aq@example.org\*(Aq
\&         }
\&       },
\&       \*(Aqauthserv\*(Aq => \*(Aqserver.example.com\*(Aq,
\&       \*(Aqresult\*(Aq => \*(Aqpass\*(Aq,
\&       \*(Aqversion\*(Aq => 1,
\&       \*(Aqreason\*(Aq => \*(Aq\*(Aq
\&     },
\&     {
\&       \*(Aqproperties\*(Aq => {
\&         \*(Aqheader\*(Aq => {
\&           \*(Aqi\*(Aq => \*(Aq@another.signing.domain.example\*(Aq
\&         }
\&       },
\&       \*(Aqresult\*(Aq => \*(Aqfail\*(Aq,
\&       \*(Aqauthserv\*(Aq => \*(Aqserver.example.com\*(Aq,
\&       \*(Aqversion\*(Aq => 1,
\&       \*(Aqreason\*(Aq => \*(Aq\*(Aq
\&     },
\&   ],
\& }
.Ve
.PP
Within each array, the order of results is the original, which should be most
recent results first.
.PP
For checking result of methods, \f(CW$pms\fR\->{authres_result} is available:
.PP
.Vb 4
\& $pms\->{authres_result} = {
\&   \*(Aqdkim\*(Aq => \*(Aqpass\*(Aq,
\&   \*(Aqspf\*(Aq => \*(Aqfail\*(Aq,
\& }
.Ve
.SH "EVAL FUNCTIONS"
.IX Header "EVAL FUNCTIONS"
.IP "header \s-1RULENAME\s0 eval:check_authres_result(method, result)" 4
.IX Item "header RULENAME eval:check_authres_result(method, result)"
Can be used to check results.
.Sp
.Vb 12
\&  ifplugin Mail::SpamAssassin::Plugin::AuthRes
\&  ifplugin !(Mail::SpamAssassin::Plugin::SPF)
\&    header  SPF_PASS      eval:check_authres_result(\*(Aqspf\*(Aq, \*(Aqpass\*(Aq)
\&    header  SPF_FAIL      eval:check_authres_result(\*(Aqspf\*(Aq, \*(Aqfail\*(Aq)
\&    header  SPF_SOFTFAIL  eval:check_authres_result(\*(Aqspf\*(Aq, \*(Aqsoftfail\*(Aq)
\&    header  SPF_TEMPFAIL  eval:check_authres_result(\*(Aqspf\*(Aq, \*(Aqtempfail\*(Aq)
\&  endif
\&  ifplugin !(Mail::SpamAssassin::Plugin::DKIM)
\&    header  DKIM_VERIFIED  eval:check_authres_result(\*(Aqdkim\*(Aq, \*(Aqpass\*(Aq)
\&    header  DKIM_INVALID   eval:check_authres_result(\*(Aqdkim\*(Aq, \*(Aqfail\*(Aq)
\&  endif
\&  endif
.Ve