1Mail::SpamAssassin::PluUgsienr::CDoKnItMr(i3b)uted PerlMDaoiclu:m:eSnptaamtAisosnassin::Plugin::DKIM(3)
2
3
4

NAME

6       Mail::SpamAssassin::Plugin::DKIM - perform DKIM verification tests
7

SYNOPSIS

9        loadplugin Mail::SpamAssassin::Plugin::DKIM [/path/to/DKIM.pm]
10
11       Taking into account signatures from any signing domains:
12
13        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        full   DKIM_VALID_EF         eval:check_dkim_valid_envelopefrom()
17
18       Taking into account ARC signatures (Authenticated Received Chain, RFC
19       8617) from any signing domains:
20
21        full   ARC_SIGNED            eval:check_arc_signed()
22        full   ARC_VALID             eval:check_arc_valid()
23
24       Taking into account signatures from specified signing domains only:
25       (quotes may be omitted on domain names consisting only of letters,
26       digits, dots, and minus characters)
27
28        full   DKIM_SIGNED_MY1       eval:check_dkim_signed('dom1','dom2',...)
29        full   DKIM_VALID_MY1        eval:check_dkim_valid('dom1','dom2',...)
30        full   DKIM_VALID_AU_MY1     eval:check_dkim_valid_author_sig('d1','d2',...)
31
32        full   __DKIM_DEPENDABLE     eval:check_dkim_dependable()
33
34       Author Domain Signing Practices (ADSP) from any author domains:
35
36        header DKIM_ADSP_NXDOMAIN    eval:check_dkim_adsp('N')
37        header DKIM_ADSP_ALL         eval:check_dkim_adsp('A')
38        header DKIM_ADSP_DISCARD     eval:check_dkim_adsp('D')
39        header DKIM_ADSP_CUSTOM_LOW  eval:check_dkim_adsp('1')
40        header DKIM_ADSP_CUSTOM_MED  eval:check_dkim_adsp('2')
41        header DKIM_ADSP_CUSTOM_HIGH eval:check_dkim_adsp('3')
42
43       Author Domain Signing Practices (ADSP) from specified author domains
44       only:
45
46        header DKIM_ADSP_MY1         eval:check_dkim_adsp('*','dom1','dom2',...)
47
48        describe DKIM_SIGNED   Message has a DKIM or DK signature, not necessarily valid
49        describe DKIM_VALID    Message has at least one valid DKIM or DK signature
50        describe DKIM_VALID_AU Message has a valid DKIM or DK signature from author's domain
51        describe DKIM_VALID_EF Message has a valid DKIM or DK signature from envelope-from domain
52        describe __DKIM_DEPENDABLE     A validation failure not attributable to truncation
53
54        describe DKIM_ADSP_NXDOMAIN    Domain not in DNS and no valid author domain signature
55        describe DKIM_ADSP_ALL         Domain signs all mail, no valid author domain signature
56        describe DKIM_ADSP_DISCARD     Domain signs all mail and suggests discarding mail with no valid author domain signature, no valid author domain signature
57        describe DKIM_ADSP_CUSTOM_LOW  adsp_override is CUSTOM_LOW, no valid author domain signature
58        describe DKIM_ADSP_CUSTOM_MED  adsp_override is CUSTOM_MED, no valid author domain signature
59        describe DKIM_ADSP_CUSTOM_HIGH adsp_override is CUSTOM_HIGH, no valid author domain signature
60
61       For compatibility with pre-3.3.0 versions, the following are synonyms:
62
63        OLD: eval:check_dkim_verified = NEW: eval:check_dkim_valid
64        OLD: eval:check_dkim_signall  = NEW: eval:check_dkim_adsp('A')
65        OLD: eval:check_dkim_signsome = NEW: redundant, semantically always true
66
67       The __DKIM_DEPENDABLE eval rule deserves an explanation. The rule
68       yields true when signatures are supplied by a caller, OR ELSE when
69       signatures are obtained by this plugin AND either there are no
70       signatures OR a rule __TRUNCATED was false. In other words:
71       __DKIM_DEPENDABLE is true when failed signatures can not be attributed
72       to message truncation when feeding a message to SpamAssassin.  It can
73       be consulted to prevent false positives on large but truncated messages
74       with poor man's implementation of ADSP by hand-crafted rules.
75

DESCRIPTION

77       This SpamAssassin plugin implements DKIM lookups as described by the
78       RFC 4871, as well as historical DomainKeys lookups, as described by RFC
79       4870, thanks to the support for both types of signatures by newer
80       versions of module Mail::DKIM.
81
82       It requires the "Mail::DKIM" CPAN module to operate. Many thanks to
83       Jason Long for that module.
84

TAGS

86       The following tags are added to the set, available for use in reports,
87       header fields, other plugins, etc.:
88
89         _DKIMIDENTITY_
90           Agent or User Identifier (AUID) (the 'i' tag) from valid signatures;
91
92         _DKIMDOMAIN_
93           Signing Domain Identifier (SDID) (the 'd' tag) from valid signatures;
94
95         _DKIMSELECTOR_
96           DKIM selector (the 's' tag) from valid signatures;
97
98       Identities and domains from signatures which failed verification are
99       not included in these tags. Duplicates are eliminated (e.g. when there
100       are two or more valid signatures from the same signer, only one copy
101       makes it into a tag).  Note that there may be more than one signature
102       in a message - currently they are provided as a space-separated list,
103       although this behaviour may change.
104

SEE ALSO

106       "Mail::DKIM" Mail::SpamAssassin::Plugin(3)
107
108         http://dkimproxy.sourceforge.net/
109         https://tools.ietf.org/rfc/rfc4871.txt
110         https://tools.ietf.org/rfc/rfc4870.txt
111         https://tools.ietf.org/rfc/rfc5617.txt
112         https://datatracker.ietf.org/group/dkim/about/
113

USER SETTINGS

115       welcomelist_from_dkim author@example.com [signing-domain]
116           Previously whitelist_from_dkim which will work interchangeably
117           until 4.1.
118
119           Works similarly to welcomelist_from, except that in addition to
120           matching an author address (From) to the pattern in the first
121           parameter, the message must also carry a valid Domain Keys
122           Identified Mail (DKIM) signature made by a signing domain (SDID,
123           i.e. the d= tag) that is acceptable to us.
124
125           Only one welcomelist entry is allowed per line, as in
126           "welcomelist_from_rcvd".  Multiple "welcomelist_from_dkim" lines
127           are allowed. File-glob style characters are allowed for the From
128           address (the first parameter), just like with
129           "welcomelist_from_rcvd".
130
131           The second parameter (the signing-domain) does not accept full
132           file-glob style wildcards, although a simple '*.' (or just a '.')
133           prefix to a domain name is recognized and implies any subdomain of
134           the specified domain (but not the domain itself).
135
136           If no signing-domain parameter is specified, the only acceptable
137           signature will be an Author Domain Signature (sometimes called
138           first-party signature) which is a signature where the signing
139           domain (SDID) of a signature matches the domain of the author's
140           address (i.e. the address in a From header field).
141
142           Since this welcomelist requires a DKIM check to be made, network
143           tests must be enabled.
144
145           Examples of welcomelisting based on an author domain signature
146           (first-party):
147
148             welcomelist_from_dkim joe@example.com
149             welcomelist_from_dkim *@corp.example.com
150             welcomelist_from_dkim *@*.example.com
151
152           Examples of welcomelisting based on third-party signatures:
153
154             welcomelist_from_dkim jane@example.net      example.org
155             welcomelist_from_dkim rick@info.example.net example.net
156             welcomelist_from_dkim *@info.example.net    example.net
157             welcomelist_from_dkim *@*                   mail7.remailer.example.com
158             welcomelist_from_dkim *@*                   *.remailer.example.com
159
160       def_welcomelist_from_dkim author@example.com [signing-domain]
161           Previously def_whitelist_from_dkim which will work interchangeably
162           until 4.1.
163
164           Same as "welcomelist_from_dkim", but used for the default
165           welcomelist entries in the SpamAssassin distribution.  The
166           welcomelist score is lower, because these are often targets for
167           abuse of public mailers which sign their mail.
168
169       unwelcomelist_from_dkim author@example.com [signing-domain]
170           Previously unwhitelist_from_dkim which will work interchangeably
171           until 4.1.
172
173           Removes an email address with its corresponding signing-domain
174           field from def_welcomelist_from_dkim and welcomelist_from_dkim
175           tables, if it exists.  Parameters to unwelcomelist_from_dkim must
176           exactly match the parameters of a corresponding
177           welcomelist_from_dkim or def_welcomelist_from_dkim config option
178           which created the entry, for it to be removed (a domain name is
179           matched case-insensitively);  i.e. if a signing-domain parameter
180           was specified in a welcomelisting command, it must also be
181           specified in the unwelcomelisting command.
182
183           Useful for removing undesired default entries from a distributed
184           configuration by a local or site-specific configuration or by
185           "user_prefs".
186
187       adsp_override domain [signing-practices]
188           Currently few domains publish their signing practices (RFC 5617 -
189           ADSP), partly because the ADSP rfc is rather new, partly because
190           they think hardly any recipient bothers to check it, and partly for
191           fear that some recipients might lose mail due to problems in their
192           signature validation procedures or mail mangling by mailers beyond
193           their control.
194
195           Nevertheless, recipients could benefit by knowing signing practices
196           of a sending (author's) domain, for example to recognize forged
197           mail claiming to be from certain domains which are popular targets
198           for phishing, like financial institutions. Unfortunately, as
199           signing practices are seldom published or are weak, it is hardly
200           justifiable to look them up in DNS.
201
202           To overcome this chicken-or-the-egg problem, the "adsp_override"
203           mechanism allows recipients using SpamAssassin to override
204           published or defaulted ADSP for certain domains. This makes it
205           possible to manually specify a stronger (or weaker) signing
206           practices than a signing domain is willing to publish (explicitly
207           or by default), and also save on a DNS lookup.
208
209           Note that ADSP (published or overridden) is only consulted for
210           messages which do not contain a valid DKIM signature from the
211           author's domain.
212
213           According to RFC 5617, signing practices can be one of the
214           following: "unknown", "all" and "discardable".
215
216           "unknown": The domain might sign some or all email - messages from
217           the domain may or may not have an Author Domain Signature. This is
218           a default if a domain exists in DNS but no ADSP record is found.
219
220           "all": All mail from the domain is signed with an Author Domain
221           Signature.
222
223           "discardable": All mail from the domain is signed with an Author
224           Domain Signature.  Furthermore, if a message arrives without a
225           valid Author Domain Signature, the domain encourages the
226           recipient(s) to discard it.
227
228           ADSP lookup can also determine that a domain is "out of scope",
229           i.e., the domain does not exist (NXDOMAIN) in the DNS.
230
231           To override domain's signing practices in a SpamAssassin
232           configuration file, specify an "adsp_override" directive for each
233           sending domain to be overridden.
234
235           Its first argument is a domain name. Author's domain is matched
236           against it, matching is case insensitive. This is not a regular
237           expression or a file-glob style wildcard, but limited wildcarding
238           is still available: if this argument starts by a "*." (or is a sole
239           "*"), author's domain matches if it is a subdomain (to one or more
240           levels) of the argument. Otherwise (with no leading asterisk) the
241           match must be exact (not a subdomain).
242
243           An optional second parameter is one of the following keywords
244           (case-insensitive): "nxdomain", "unknown", "all", "discardable",
245           "custom_low", "custom_med", "custom_high".
246
247           Absence of this second parameter implies "discardable". If a domain
248           is not listed by a "adsp_override" directive nor does it explicitly
249           publish any ADSP record, then "unknown" is implied for valid
250           domains, and "nxdomain" for domains not existing in DNS. (Note:
251           domain validity is only checked with versions of Mail::DKIM 0.37 or
252           later (actually since 0.36_5), the "nxdomain" would never turn up
253           with older versions).
254
255           The strong setting "discardable" is useful for domains which are
256           known to always sign their mail and to always send it directly to
257           recipients (not to mailing lists), and are frequent targets of
258           fishing attempts, such as financial institutions. The "discardable"
259           is also appropriate for domains which are known never to send any
260           mail.
261
262           When a message does not contain a valid signature by the author's
263           domain (the domain in a From header field), the signing practices
264           pertaining to author's domain determine which of the following
265           rules fire and contributes its score: DKIM_ADSP_NXDOMAIN,
266           DKIM_ADSP_ALL, DKIM_ADSP_DISCARD, DKIM_ADSP_CUSTOM_LOW,
267           DKIM_ADSP_CUSTOM_MED, DKIM_ADSP_CUSTOM_HIGH. Not more than one of
268           these rules can fire for messages that have one author (but see
269           below). The last three can only result from a 'signing-practices'
270           as given in a "adsp_override" directive (not from a DNS lookup),
271           and can serve as a convenient means of providing a different score
272           if scores assigned to DKIM_ADSP_ALL or DKIM_ADSP_DISCARD are not
273           considered suitable for some domains.
274
275           RFC 5322 permits a message to have more than one author - multiple
276           addresses may be listed in a single From header field.  RFC 5617
277           defines that a message with multiple authors has multiple signing
278           domain signing practices, but does not prescribe how these should
279           be combined. In presence of multiple signing practices, more than
280           one of the DKIM_ADSP_* rules may fire.
281
282           As a precaution against firing DKIM_ADSP_* rules when there is a
283           known local reason for a signature verification failure, the
284           domain's ADSP is considered 'unknown' when DNS lookups are disabled
285           or a DNS lookup encountered a temporary problem on fetching a
286           public key from the author's domain. Similarly, ADSP is considered
287           'unknown' when this plugin did its own signature verification
288           (signatures were not passed to SA by a caller) and a metarule
289           __TRUNCATED was triggered, indicating the caller intentionally
290           passed a truncated message to SpamAssassin, which was a likely
291           reason for a signature verification failure.
292
293           Example:
294
295             adsp_override *.mydomain.example.com   discardable
296             adsp_override *.neversends.example.com discardable
297
298             adsp_override ebay.com
299             adsp_override *.ebay.com
300             adsp_override ebay.co.uk
301             adsp_override *.ebay.co.uk
302             adsp_override paypal.com
303             adsp_override *.paypal.com
304             adsp_override amazon.com
305             adsp_override ealerts.bankofamerica.com
306             adsp_override americangreetings.com
307             adsp_override egreetings.com
308             adsp_override bluemountain.com
309             adsp_override hallmark.com   all
310             adsp_override *.hallmark.com all
311             adsp_override youtube.com    custom_high
312             adsp_override google.com     custom_low
313             adsp_override gmail.com      custom_low
314             adsp_override googlemail.com custom_low
315             adsp_override yahoo.com      custom_low
316             adsp_override yahoo.com.au   custom_low
317             adsp_override yahoo.se       custom_low
318
319             adsp_override junkmailerkbw0rr.com nxdomain
320             adsp_override junkmailerd2hlsg.com nxdomain
321
322             # effectively disables ADSP network DNS lookups for all other domains:
323             adsp_override *              unknown
324
325             score DKIM_ADSP_ALL          2.5
326             score DKIM_ADSP_DISCARD     25
327             score DKIM_ADSP_NXDOMAIN     3
328
329             score DKIM_ADSP_CUSTOM_LOW   1
330             score DKIM_ADSP_CUSTOM_MED   3.5
331             score DKIM_ADSP_CUSTOM_HIGH  8
332
333       dkim_minimum_key_bits n             (default: 1024)
334           The smallest size of a signing key (in bits) for a valid signature
335           to be considered for welcomelisting. Additionally, the eval
336           function check_dkim_valid() will return false on short keys when
337           called with explicitly listed domains, and the eval function
338           check_dkim_valid_author_sig() will return false on short keys
339           (regardless of its arguments). Setting the option to 0 disables a
340           key size check.
341
342           Note that the option has no effect when the eval function
343           check_dkim_valid() is called with no arguments (like in a rule
344           DKIM_VALID). A mere presence of some valid signature on a message
345           has no reputational value (without being associated with a
346           particular domain), regardless of its key size - anyone can prepend
347           its own signature on a copy of some third party mail and re-send
348           it, which makes it no more trustworthy than without such signature.
349           This is also a reason for a rule DKIM_VALID to have a near-zero
350           score, i.e. a rule hit is only informational.  This option is
351           evaluated on ARC signatures checks as well.
352

ADMINISTRATOR SETTINGS

354       dkim_timeout n             (default: 5)
355           How many seconds to wait for a DKIM query to complete, before
356           scanning continues without the DKIM result. A numeric value is
357           optionally suffixed by a time unit (s, m, h, d, w, indicating
358           seconds (default), minutes, hours, days, weeks).
359
360
361
362perl v5.36.0                      2023-01-21Mail::SpamAssassin::Plugin::DKIM(3)
Impressum