File: //usr/local/ssl/local/share/man/man3/Mail::SpamAssassin::Plugin::DomainKeys.3
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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. | will give a
.\" real vertical bar. \*(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-|\(bv\*(Tr
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.\"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Mail::SpamAssassin::Plugin::DomainKeys 3"
.TH Mail::SpamAssassin::Plugin::DomainKeys 3 "2008-01-05" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Mail::SpamAssassin::Plugin::DomainKeys \- perform DomainKeys verification tests
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& loadplugin Mail::SpamAssassin::Plugin::DomainKeys [/path/to/DomainKeys.pm]
.Ve
.PP
Signature:
header \s-1DK_SIGNED\s0 \fIeval:check_domainkeys_signed()\fR
header \s-1DK_VERIFIED\s0 \fIeval:check_domainkeys_verified()\fR
.PP
Policy:
Note that \s-1DK\s0 policy record is only fetched if \s-1DK_VERIFIED\s0 is
false to save a signing domain from unnecessary \s-1DNS\s0 queries,
as recommended (\s-1SHOULD\s0) by draft\-delany\-domainkeys\-base.
Rules DK_POLICY_* should preferably not be relied upon when
\s-1DK_VERIFIED\s0 is true, although they will return false in current
implementation when a policy record is not fetched, except for
\s-1DK_POLICY_TESTING\s0, which is true if t=y appears in a public key
record \s-1OR\s0 in a policy record (when available).
header \s-1DK_POLICY_TESTING\s0 \fIeval:check_domainkeys_testing()\fR
header \s-1DK_POLICY_SIGNSOME\s0 \fIeval:check_domainkeys_signsome()\fR
header \s-1DK_POLICY_SIGNALL\s0 \fIeval:check_domainkeys_signall()\fR
.PP
Whitelisting based on verified signature:
header \s-1USER_IN_DK_WHITELIST\s0 \fIeval:check_for_dk_whitelist_from()\fR
header \s-1USER_IN_DEF_DK_WL\s0 \fIeval:check_for_def_dk_whitelist_from()\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is the DomainKeys plugin and it needs lots more documentation.
.PP
Note that if the \f(CW\*(C`Mail::SpamAssassin::Plugin::DKIM\*(C'\fR plugin is installed with
\&\f(CW\*(C`Mail::DKIM\*(C'\fR version 0.20 or later, that plugin will also perform Domain Key
lookups on DomainKey-Signature headers, in which case this plugin is redundant.
.PP
Here is author's note from module \f(CW\*(C`Mail::DomainKeys\*(C'\fR version 1.0:
.PP
.Vb 1
\& THIS MODULE IS OFFICIALLY UNSUPPORTED.
.Ve
.PP
.Vb 1
\& Please move on to DKIM like a responsible Internet user. I have.
.Ve
.PP
.Vb 4
\& I will leave this module here on CPAN for a while, just in case someone
\& has grown to depend on it. It is apparent that DK will not be the way
\& of the future. Thus, it is time to put this module to ground before it
\& causes any further harm.
.Ve
.PP
.Vb 2
\& Thanks for your support,
\& Anthony
.Ve
.SH "USER SETTINGS"
.IX Header "USER SETTINGS"
.IP "whitelist_from_dk add@ress.com [signing domain name]" 4
.IX Item "whitelist_from_dk add@ress.com [signing domain name]"
Use this to supplement the whitelist_from addresses with a check to make sure
the message has been signed by a DomainKeys signature that can be verified
against the From: domain's DomainKeys public key.
.Sp
In order to support signing domain names that differ from the address domain
name, only one whitelist entry is allowed per line, exactly like
\&\f(CW\*(C`whitelist_from_rcvd\*(C'\fR. Multiple \f(CW\*(C`whitelist_from_dk\*(C'\fR lines are allowed.
File-glob style meta characters are allowed for the From: address, just like
with \f(CW\*(C`whitelist_from_rcvd\*(C'\fR. The optional signing domain name parameter must
match from the right-most side, also like in \f(CW\*(C`whitelist_from_rcvd\*(C'\fR.
.Sp
If no signing domain name parameter is specified the domain of the address
parameter specified will be used instead.
.Sp
The From: address is obtained from a signed part of the message (ie. the
\&\*(L"From:\*(R" header), not from envelope data that is possible to forge.
.Sp
Since this whitelist requires a DomainKeys check to be made, network tests must
be enabled.
.Sp
Examples:
.Sp
.Vb 2
\& whitelist_from_dk joe@example.com
\& whitelist_from_dk *@corp.example.com
.Ve
.Sp
.Vb 2
\& whitelist_from_dk bob@it.example.net example.net
\& whitelist_from_dk *@eng.example.net example.net
.Ve
.IP "def_whitelist_from_dk add@ress.com [signing domain name]" 4
.IX Item "def_whitelist_from_dk add@ress.com [signing domain name]"
Same as \f(CW\*(C`whitelist_from_dk\*(C'\fR, but used for the default whitelist entries
in the SpamAssassin distribution. The whitelist score is lower, because
these are often targets for spammer spoofing.
.SH "ADMINISTRATOR SETTINGS"
.IX Header "ADMINISTRATOR SETTINGS"
.IP "domainkeys_timeout n (default: 5)" 4
.IX Item "domainkeys_timeout n (default: 5)"
How many seconds to wait for a DomainKeys query to complete, before
scanning continues without the DomainKeys result.