1Mail::SpamAssassin::PluUgsienr::CDoKnItMr(i3b)uted PerlMDaoiclu:m:eSnptaamtAisosnassin::Plugin::DKIM(3)
2
6 Mail::SpamAssassin::Plugin::DKIM - perform DKIM verification tests
7
9 loadplugin Mail::SpamAssassin::Plugin::DKIM [/path/to/DKIM.pm]
10 Taking into account signatures from any signing domains:
12 full DKIM_SIGNED eval:check_dkim_signed()
14 full DKIM_VALID eval:check_dkim_valid()
15 full DKIM_VALID_AU eval:check_dkim_valid_author_sig()
16 Taking into account signatures from specified signing domains only:
18 (quotes may be omitted on domain names consisting only of letters,
19 digits, dots, and minus characters)
20 full DKIM_SIGNED_MY1 eval:check_dkim_signed('dom1','dom2',...)
22 full DKIM_VALID_MY1 eval:check_dkim_valid('dom1','dom2',...)
23 full DKIM_VALID_AU_MY1 eval:check_dkim_valid_author_sig('d1','d2',...)
24 full __DKIM_DEPENDABLE eval:check_dkim_dependable()
26 Author Domain Signing Practices (ADSP) from any author domains:
28 header DKIM_ADSP_NXDOMAIN eval:check_dkim_adsp('N')
30 header DKIM_ADSP_ALL eval:check_dkim_adsp('A')
31 header DKIM_ADSP_DISCARD eval:check_dkim_adsp('D')
32 header DKIM_ADSP_CUSTOM_LOW eval:check_dkim_adsp('1')
33 header DKIM_ADSP_CUSTOM_MED eval:check_dkim_adsp('2')
34 header DKIM_ADSP_CUSTOM_HIGH eval:check_dkim_adsp('3')
35 Author Domain Signing Practices (ADSP) from specified author domains
37 only:
38 header DKIM_ADSP_MY1 eval:check_dkim_adsp('*','dom1','dom2',...)
40 describe DKIM_SIGNED Message has a DKIM or DK signature, not necessarily valid
42 describe DKIM_VALID Message has at least one valid DKIM or DK signature
43 describe DKIM_VALID_AU Message has a valid DKIM or DK signature from author's domain
44 describe __DKIM_DEPENDABLE A validation failure not attributable to truncation
45 describe DKIM_ADSP_NXDOMAIN Domain not in DNS and no valid author domain signature
47 describe DKIM_ADSP_ALL Domain signs all mail, no valid author domain signature
48 describe DKIM_ADSP_DISCARD Domain signs all mail and suggests discarding mail with no valid author domain signature, no valid author domain signature
49 describe DKIM_ADSP_CUSTOM_LOW adsp_override is CUSTOM_LOW, no valid author domain signature
50 describe DKIM_ADSP_CUSTOM_MED adsp_override is CUSTOM_MED, no valid author domain signature
51 describe DKIM_ADSP_CUSTOM_HIGH adsp_override is CUSTOM_HIGH, no valid author domain signature
52 For compatibility with pre-3.3.0 versions, the following are synonyms:
54 OLD: eval:check_dkim_verified = NEW: eval:check_dkim_valid
56 OLD: eval:check_dkim_signall = NEW: eval:check_dkim_adsp('A')
57 OLD: eval:check_dkim_signsome = NEW: redundant, semantically always true
58 The __DKIM_DEPENDABLE eval rule deserves an explanation. The rule
60 yields true when signatures are supplied by a caller, OR ELSE when
61 signatures are obtained by this plugin AND either there are no
62 signatures OR a rule __TRUNCATED was false. In other words:
63 __DKIM_DEPENDABLE is true when failed signatures can not be attributed
64 to message truncation when feeding a message to SpamAssassin. It can
65 be consulted to prevent false positives on large but truncated messages
66 with poor man's implementation of ADSP by hand-crafted rules.
67
69 This SpamAssassin plugin implements DKIM lookups as described by the
70 RFC 4871, as well as historical DomainKeys lookups, as described by RFC
71 4870, thanks to the support for both types of signatures by newer
72 versions of module Mail::DKIM.
73 It requires the "Mail::DKIM" CPAN module to operate. Many thanks to
75 Jason Long for that module.
76
78 The following tags are added to the set, available for use in reports,
79 header fields, other plugins, etc.:
80 _DKIMIDENTITY_
82 Agent or User Identifier (AUID) (the 'i' tag) from valid signatures;
83 _DKIMDOMAIN_
85 Signing Domain Identifier (SDID) (the 'd' tag) from valid signatures;
86 Identities and domains from signatures which failed verification are
88 not included in these tags. Duplicates are eliminated (e.g. when there
89 are two or more valid signatures from the same signer, only one copy
90 makes it into a tag). Note that there may be more than one signature
91 in a message - currently they are provided as a space-separated list,
92 although this behaviour may change.
93
95 "Mail::DKIM", "Mail::SpamAssassin::Plugin"
96 http://jason.long.name/dkimproxy/
98 http://tools.ietf.org/rfc/rfc4871.txt
99 http://tools.ietf.org/rfc/rfc4870.txt
100 http://tools.ietf.org/rfc/rfc5617.txt
101 http://ietf.org/html.charters/dkim-charter.html
102
104 whitelist_from_dkim author@example.com [signing-domain]
105 Works similarly to whitelist_from, except that in addition to
106 matching an author address (From) to the pattern in the first
107 parameter, the message must also carry a Domain Keys Identified
108 Mail (DKIM) signature made by a signing domain (SDID, i.e. the d=
109 tag) that is acceptable to us.
110 Only one whitelist entry is allowed per line, as in
112 "whitelist_from_rcvd". Multiple "whitelist_from_dkim" lines are
113 allowed. File-glob style characters are allowed for the From
114 address (the first parameter), just like with
115 "whitelist_from_rcvd". The second parameter does not accept
116 wildcards.
117 If no signing-domain parameter is specified, the only acceptable
119 signature will be an Author Domain Signature (sometimes called
120 first-party signature) which is a signature where the signing
121 domain (SDID) of a signature matches the domain of the author's
122 address (i.e. the address in a From header field).
123 Since this whitelist requires a DKIM check to be made, network
125 tests must be enabled.
126 Examples of whitelisting based on an author domain signature
128 (first-party):
129 whitelist_from_dkim joe@example.com
131 whitelist_from_dkim *@corp.example.com
132 whitelist_from_dkim *@*.example.com
133 Examples of whitelisting based on third-party signatures:
135 whitelist_from_dkim jane@example.net example.org
137 whitelist_from_dkim rick@info.example.net example.net
138 whitelist_from_dkim *@info.example.net example.net
139 whitelist_from_dkim *@* remailer.example.com
140 def_whitelist_from_dkim author@example.com [signing-domain]
142 Same as "whitelist_from_dkim", but used for the default whitelist
143 entries in the SpamAssassin distribution. The whitelist score is
144 lower, because these are often targets for abuse of public mailers
145 which sign their mail.
146 adsp_override domain [signing-practices]
148 Currently few domains publish their signing practices (RFC 5617 -
149 ADSP), partly because the ADSP rfc is rather new, partly because
150 they think hardly any recipient bothers to check it, and partly for
151 fear that some recipients might lose mail due to problems in their
152 signature validation procedures or mail mangling by mailers beyond
153 their control.
154 Nevertheless, recipients could benefit by knowing signing practices
156 of a sending (author's) domain, for example to recognize forged
157 mail claiming to be from certain domains which are popular targets
158 for phishing, like financial institutions. Unfortunately, as
159 signing practices are seldom published or are weak, it is hardly
160 justifiable to look them up in DNS.
161 To overcome this chicken-or-the-egg problem, the "adsp_override"
163 mechanism allows recipients using SpamAssassin to override
164 published or defaulted ADSP for certain domains. This makes it
165 possible to manually specify a stronger (or weaker) signing
166 practices than a signing domain is willing to publish (explicitly
167 or by default), and also save on a DNS lookup.
168 Note that ADSP (published or overridden) is only consulted for
170 messages which do not contain a valid DKIM signature from the
171 author's domain.
172 According to RFC 5617, signing practices can be one of the
174 following: "unknown", "all" and "discardable".
175 "unknown": The domain might sign some or all email - messages from
177 the domain may or may not have an Author Domain Signature. This is
178 a default if a domain exists in DNS but no ADSP record is found.
179 "all": All mail from the domain is signed with an Author Domain
181 Signature.
182 "discardable": All mail from the domain is signed with an Author
184 Domain Signature. Furthermore, if a message arrives without a
185 valid Author Domain Signature, the domain encourages the
186 recipient(s) to discard it.
187 ADSP lookup can also determine that a domain is "out of scope",
189 i.e., the domain does not exist (NXDOMAIN) in the DNS.
190 To override domain's signing practices in a SpamAssassin
192 configuration file, specify an "adsp_override" directive for each
193 sending domain to be overridden.
194 Its first argument is a domain name. Author's domain is matched
196 against it, matching is case insensitive. This is not a regular
197 expression or a file-glob style wildcard, but limited wildcarding
198 is still available: if this argument starts by a "*." (or is a sole
199 "*"), author's domain matches if it is a subdomain (to one or more
200 levels) of the argument. Otherwise (with no leading asterisk) the
201 match must be exact (not a subdomain).
202 An optional second parameter is one of the following keywords
204 (case-insensitive): "nxdomain", "unknown", "all", "discardable",
205 "custom_low", "custom_med", "custom_high".
206 Absence of this second parameter implies "discardable". If a domain
208 is not listed by a "adsp_override" directive nor does it explicitly
209 publish any ADSP record, then "unknown" is implied for valid
210 domains, and "nxdomain" for domains not existing in DNS. (Note:
211 domain validity is only checked with versions of Mail::DKIM 0.37 or
212 later (actually since 0.36_5), the "nxdomain" would never turn up
213 with older versions).
214 The strong setting "discardable" is useful for domains which are
216 known to always sign their mail and to always send it directly to
217 recipients (not to mailing lists), and are frequent targets of
218 fishing attempts, such as financial institutions. The "discardable"
219 is also appropriate for domains which are known never to send any
220 mail.
221 When a message does not contain a valid signature by the author's
223 domain (the domain in a From header field), the signing practices
224 pertaining to author's domain determine which of the following
225 rules fire and contributes its score: DKIM_ADSP_NXDOMAIN,
226 DKIM_ADSP_ALL, DKIM_ADSP_DISCARD, DKIM_ADSP_CUSTOM_LOW,
227 DKIM_ADSP_CUSTOM_MED, DKIM_ADSP_CUSTOM_HIGH. Not more than one of
228 these rules can fire for messages that have one author (but see
229 below). The last three can only result from a 'signing-practices'
230 as given in a "adsp_override" directive (not from a DNS lookup),
231 and can serve as a convenient means of providing a different score
232 if scores assigned to DKIM_ADSP_ALL or DKIM_ADSP_DISCARD are not
233 considered suitable for some domains.
234 RFC 5322 permits a message to have more than one author - multiple
236 addresses may be listed in a single From header field. RFC 5617
237 defines that a message with multiple authors has multiple signing
238 domain signing practices, but does not prescribe how these should
239 be combined. In presence of multiple signing practices, more than
240 one of the DKIM_ADSP_* rules may fire.
241 As a precaution against firing DKIM_ADSP_* rules when there is a
243 known local reason for a signature verification failure, the
244 domain's ADSP is considered 'unknown' when DNS lookups are disabled
245 or a DNS lookup encountered a temporary problem on fetching a
246 public key from the author's domain. Similarly, ADSP is considered
247 'unknown' when this plugin did its own signature verification
248 (signatures were not passed to SA by a caller) and a metarule
249 __TRUNCATED was triggered, indicating the caller intentionally
250 passed a truncated message to SpamAssassin, which was a likely
251 reason for a signature verification failure.
252 Example:
254 adsp_override *.mydomain.example.com discardable
256 adsp_override *.neversends.example.com discardable
257 adsp_override ebay.com
259 adsp_override *.ebay.com
260 adsp_override ebay.co.uk
261 adsp_override *.ebay.co.uk
262 adsp_override paypal.com
263 adsp_override *.paypal.com
264 adsp_override amazon.com
265 adsp_override ealerts.bankofamerica.com
266 adsp_override americangreetings.com
267 adsp_override egreetings.com
268 adsp_override bluemountain.com
269 adsp_override hallmark.com all
270 adsp_override *.hallmark.com all
271 adsp_override youtube.com custom_high
272 adsp_override google.com custom_low
273 adsp_override gmail.com custom_low
274 adsp_override googlemail.com custom_low
275 adsp_override yahoo.com custom_low
276 adsp_override yahoo.com.au custom_low
277 adsp_override yahoo.se custom_low
278 adsp_override junkmailerkbw0rr.com nxdomain
280 adsp_override junkmailerd2hlsg.com nxdomain
281 # effectively disables ADSP network DNS lookups for all other domains:
283 adsp_override * unknown
284 score DKIM_ADSP_ALL 2.5
286 score DKIM_ADSP_DISCARD 25
287 score DKIM_ADSP_NXDOMAIN 3
288 score DKIM_ADSP_CUSTOM_LOW 1
290 score DKIM_ADSP_CUSTOM_MED 3.5
291 score DKIM_ADSP_CUSTOM_HIGH 8
292
294 dkim_timeout n (default: 5)
295 How many seconds to wait for a DKIM query to complete, before
296 scanning continues without the DKIM result.
297perl v5.10.1 2010-03-16Mail::SpamAssassin::Plugin::DKIM(3)