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 unwhitelist_from_dkim author@example.com [signing-domain]
148 Removes an email address with its corresponding signing-domain
149 field from def_whitelist_from_dkim and whitelist_from_dkim tables,
150 if it exists. Parameters to unwhitelist_from_dkim must exactly
151 match the parameters of a corresponding whitelist_from_dkim or
152 def_whitelist_from_dkim config option which created the entry, for
153 it to be removed (a domain name is matched case-insensitively);
154 i.e. if a signing-domain parameter was specified in a whitelisting
155 command, it must also be specified in the unwhitelisting command.
156 Useful for removing undesired default entries from a distributed
158 configuration by a local or site-specific configuration or by
159 "user_prefs".
160 adsp_override domain [signing-practices]
162 Currently few domains publish their signing practices (RFC 5617 -
163 ADSP), partly because the ADSP rfc is rather new, partly because
164 they think hardly any recipient bothers to check it, and partly for
165 fear that some recipients might lose mail due to problems in their
166 signature validation procedures or mail mangling by mailers beyond
167 their control.
168 Nevertheless, recipients could benefit by knowing signing practices
170 of a sending (author's) domain, for example to recognize forged
171 mail claiming to be from certain domains which are popular targets
172 for phishing, like financial institutions. Unfortunately, as
173 signing practices are seldom published or are weak, it is hardly
174 justifiable to look them up in DNS.
175 To overcome this chicken-or-the-egg problem, the "adsp_override"
177 mechanism allows recipients using SpamAssassin to override
178 published or defaulted ADSP for certain domains. This makes it
179 possible to manually specify a stronger (or weaker) signing
180 practices than a signing domain is willing to publish (explicitly
181 or by default), and also save on a DNS lookup.
182 Note that ADSP (published or overridden) is only consulted for
184 messages which do not contain a valid DKIM signature from the
185 author's domain.
186 According to RFC 5617, signing practices can be one of the
188 following: "unknown", "all" and "discardable".
189 "unknown": The domain might sign some or all email - messages from
191 the domain may or may not have an Author Domain Signature. This is
192 a default if a domain exists in DNS but no ADSP record is found.
193 "all": All mail from the domain is signed with an Author Domain
195 Signature.
196 "discardable": All mail from the domain is signed with an Author
198 Domain Signature. Furthermore, if a message arrives without a
199 valid Author Domain Signature, the domain encourages the
200 recipient(s) to discard it.
201 ADSP lookup can also determine that a domain is "out of scope",
203 i.e., the domain does not exist (NXDOMAIN) in the DNS.
204 To override domain's signing practices in a SpamAssassin
206 configuration file, specify an "adsp_override" directive for each
207 sending domain to be overridden.
208 Its first argument is a domain name. Author's domain is matched
210 against it, matching is case insensitive. This is not a regular
211 expression or a file-glob style wildcard, but limited wildcarding
212 is still available: if this argument starts by a "*." (or is a sole
213 "*"), author's domain matches if it is a subdomain (to one or more
214 levels) of the argument. Otherwise (with no leading asterisk) the
215 match must be exact (not a subdomain).
216 An optional second parameter is one of the following keywords
218 (case-insensitive): "nxdomain", "unknown", "all", "discardable",
219 "custom_low", "custom_med", "custom_high".
220 Absence of this second parameter implies "discardable". If a domain
222 is not listed by a "adsp_override" directive nor does it explicitly
223 publish any ADSP record, then "unknown" is implied for valid
224 domains, and "nxdomain" for domains not existing in DNS. (Note:
225 domain validity is only checked with versions of Mail::DKIM 0.37 or
226 later (actually since 0.36_5), the "nxdomain" would never turn up
227 with older versions).
228 The strong setting "discardable" is useful for domains which are
230 known to always sign their mail and to always send it directly to
231 recipients (not to mailing lists), and are frequent targets of
232 fishing attempts, such as financial institutions. The "discardable"
233 is also appropriate for domains which are known never to send any
234 mail.
235 When a message does not contain a valid signature by the author's
237 domain (the domain in a From header field), the signing practices
238 pertaining to author's domain determine which of the following
239 rules fire and contributes its score: DKIM_ADSP_NXDOMAIN,
240 DKIM_ADSP_ALL, DKIM_ADSP_DISCARD, DKIM_ADSP_CUSTOM_LOW,
241 DKIM_ADSP_CUSTOM_MED, DKIM_ADSP_CUSTOM_HIGH. Not more than one of
242 these rules can fire for messages that have one author (but see
243 below). The last three can only result from a 'signing-practices'
244 as given in a "adsp_override" directive (not from a DNS lookup),
245 and can serve as a convenient means of providing a different score
246 if scores assigned to DKIM_ADSP_ALL or DKIM_ADSP_DISCARD are not
247 considered suitable for some domains.
248 RFC 5322 permits a message to have more than one author - multiple
250 addresses may be listed in a single From header field. RFC 5617
251 defines that a message with multiple authors has multiple signing
252 domain signing practices, but does not prescribe how these should
253 be combined. In presence of multiple signing practices, more than
254 one of the DKIM_ADSP_* rules may fire.
255 As a precaution against firing DKIM_ADSP_* rules when there is a
257 known local reason for a signature verification failure, the
258 domain's ADSP is considered 'unknown' when DNS lookups are disabled
259 or a DNS lookup encountered a temporary problem on fetching a
260 public key from the author's domain. Similarly, ADSP is considered
261 'unknown' when this plugin did its own signature verification
262 (signatures were not passed to SA by a caller) and a metarule
263 __TRUNCATED was triggered, indicating the caller intentionally
264 passed a truncated message to SpamAssassin, which was a likely
265 reason for a signature verification failure.
266 Example:
268 adsp_override *.mydomain.example.com discardable
270 adsp_override *.neversends.example.com discardable
271 adsp_override ebay.com
273 adsp_override *.ebay.com
274 adsp_override ebay.co.uk
275 adsp_override *.ebay.co.uk
276 adsp_override paypal.com
277 adsp_override *.paypal.com
278 adsp_override amazon.com
279 adsp_override ealerts.bankofamerica.com
280 adsp_override americangreetings.com
281 adsp_override egreetings.com
282 adsp_override bluemountain.com
283 adsp_override hallmark.com all
284 adsp_override *.hallmark.com all
285 adsp_override youtube.com custom_high
286 adsp_override google.com custom_low
287 adsp_override gmail.com custom_low
288 adsp_override googlemail.com custom_low
289 adsp_override yahoo.com custom_low
290 adsp_override yahoo.com.au custom_low
291 adsp_override yahoo.se custom_low
292 adsp_override junkmailerkbw0rr.com nxdomain
294 adsp_override junkmailerd2hlsg.com nxdomain
295 # effectively disables ADSP network DNS lookups for all other domains:
297 adsp_override * unknown
298 score DKIM_ADSP_ALL 2.5
300 score DKIM_ADSP_DISCARD 25
301 score DKIM_ADSP_NXDOMAIN 3
302 score DKIM_ADSP_CUSTOM_LOW 1
304 score DKIM_ADSP_CUSTOM_MED 3.5
305 score DKIM_ADSP_CUSTOM_HIGH 8
306
308 dkim_timeout n (default: 5)
309 How many seconds to wait for a DKIM query to complete, before
310 scanning continues without the DKIM result. A numeric value is
311 optionally suffixed by a time unit (s, m, h, d, w, indicating
312 seconds (default), minutes, hours, days, weeks).
313perl v5.16.3 2014-02-07Mail::SpamAssassin::Plugin::DKIM(3)