1dkim-filter.conf(5) File Formats Manual dkim-filter.conf(5)
2
6 dkim-filter.conf - Configuration file for dkim-filter
7
10 /etc/mail/dkim-filter.conf
11
14 dkim-filter(8) implements the DKIM specification for signing and veri‐
15 fying e-mail messages on a per-domain basis. This file is its configu‐
16 ration file.
17 Blank lines are ignored. Lines containing a hash ("#") character are
19 truncated at the hash character to allow for comments in the file.
20 Other content should be the name of a parameter, followed by white
22 space, followed by the value of that parameter, each on a separate
23 line.
24 For parameters which are Boolean in nature, only the first byte of the
26 value is processed. For positive values, the following are accepted:
27 "T", "t", "Y", "y", "1". For negative values, the following are
28 accepted: "F", "f", "N", "n", "0".
29 Many, but not all, of these parameters are also available as command
31 line options to dkim-filter(8). However, new parameters are generally
32 not added as command line options so the complete set of options is
33 available here, and thus use of the configuration file is encouraged.
34 In some future release, the set of available command line options is
35 likely to get trimmed.
36 See the dkim-filter(8) man page for details about how and when the con‐
38 figuration file contents are reloaded.
39
42 ADSPDiscard (Boolean)
43 If "true", requests rejection of messages which are determined
44 to be suspicious according to the author domain's published
45 signing practises (ADSP) record if that record also recommends
46 discard of such messages.
47 ADSPNoSuchDomain (Boolean)
50 If "true", requests rejection of messages which are determined
51 to be from nonexistent domains according to the author domain
52 signing practises (ADSP) test.
53 AllowSHA1Only (Boolean)
56 Permit verify mode when only SHA1 support is available. RFC4871
57 requires that verifiers implement both SHA1 and SHA256 support.
58 Setting this feature changes the absence of SHA256 support from
59 an error to a warning.
60 AlwaysAddARHeader (Boolean)
63 Add an "Authentication-Results:" header even to unsigned mes‐
64 sages from domains with no "signs all" policy. The reported
65 DKIM result will be "none" in such cases. Normally unsigned
66 mail from non-strict domains does not cause the results header
67 to be added.
68 AlwaysSignHeaders (string)
71 Specifies a list of headers which should be included in all sig‐
72 nature header lists (the "h=" tag) even if they were not present
73 at the time the signature was generated. The string should be a
74 comma-separated list of header names. The list is empty by
75 default. The purpose of listing an absent header is to prevent
76 its addition between the signer and the verifier, since the ver‐
77 ifier would include that header if it were added when performing
78 verification, which would mean the signed message and the veri‐
79 fied message were different and the verification would fail.
80 AuthservID (string)
83 Sets the "authserv-id" to use when generating the Authentica‐
84 tion-Results: header after verifying a message. The default is
85 to use the local machine's hostname.
86 AuthservIDWithJobID (Boolean)
89 If "true", requests that the authserv-id portion of the added
90 Authentication-Results: headers contain the job ID of the mes‐
91 sage being evaluated.
92 AutoRestart (Boolean)
95 Automatically re-start on failures. Use with caution; if the
96 filter fails instantly after it starts, this can cause a tight
97 fork(2) loop.
98 AutoRestartCount (integer)
101 Sets the maximum automatic restart count. After this number of
102 automatic restarts, the filter will give up and terminate. A
103 value of 0 implies no limit; this is the default.
104 AutoRestartRate (string)
107 Sets the maximum automatic restart rate. If the filter begins
108 restarting faster than the rate defined here, it will give up
109 and terminate. This is a string of the form n/t[u] where n is
110 an integer limiting the count of restarts in the given interval
111 and t[u] defines the time interval through which the rate is
112 calculated; t is an integer and u defines the units thus repre‐
113 sented ("s" or "S" for seconds, the default; "m" or "M" for min‐
114 utes; "h" or "H" for hours; "d" or "D" for days). For example,
115 a value of "10/1h" limits the restarts to 10 in one hour. There
116 is no default, meaning restart rate is not limited.
117 Background (Boolean)
120 Normally dkim-filter forks and exits immediately, leaving the
121 service running in the background. This flag suppresses that
122 behaviour so that it runs in the foreground.
123 BaseDirectory (string)
126 If set, instructs the filter to change to the specified direc‐
127 tory using chdir(2) before doing anything else. This means any
128 files referenced elsewhere in the configuration file can be
129 specified relative to this directory. It's also useful for
130 arranging that any crash dumps will be saved to a specific loca‐
131 tion.
132 BodyLengths (Boolean)
135 Requests that dkim-filter include the "l=" body length tag when
136 generating signatures. This indicates to the verifier that only
137 a certain amount of the original message was signed, allowing
138 tolerance of things like mailing list managers which append
139 list-specific text to the end of mailings it processes. How‐
140 ever, this also enables an abuse attack. See the DKIM specifi‐
141 cation for more information.
142 BogusKey (string)
145 (Only available if the filter was compiled with libunbound to
146 enable DNSSEC support.) Instructs the filter to treat a passing
147 signature associated with a bogus (forged) key in a special way.
148 Possible values are neutral (return a "neutral" result), none
149 (take no special action) and fail (return a "fail" result; this
150 is the default).
151 BogusPolicy (string)
154 (Only available if the filter was compiled with libunbound to
155 enable DNSSEC support.) Instructs the filter to treat an ADSP
156 policy found in an bogus (forged) DNS record in a special way.
157 Possible values are apply (apply the policy) and ignore (ignore
158 the policy; this is the default).
159 Canonicalization (string)
162 Selects the canonicalization method(s) to be used when signing
163 messages. When verifying, the message's DKIM-Signature: header
164 specifies the canonicalization method. The recognized values
165 are relaxed and simple as defined by the DKIM specification.
166 The default is simple. The value may include two different
167 canonicalizations separated by a slash ("/") character, in which
168 case the first will be applied to the headers and the second to
169 the body.
170 ClockDrift (integer)
173 Sets the tolerance in seconds to be applied when determining
174 whether a signature was either expired or generated in the
175 future. The default is 300.
176 Diagnostics (Boolean)
179 Requests the inclusion of "z=" tags in signatures, which encode
180 the original header set for use by verifiers when diagnosing
181 verification failures. Not recommended for normal operation.
182 DNSTimeout (integer)
185 Sets the DNS timeout in seconds. A value of 0 causes an infi‐
186 nite wait. The default is 5. Ignored if not using the asyn‐
187 chronous resolver package. See also the NOTES section below.
188 Domain (string)
191 A comma-separated list of domains whose mail should be signed by
192 this filter. Mail from other domains will be verified rather
193 than being signed.
194 The value of this parameter may also be a filename from which
196 domain names will be read. The "#" character in such a file is
197 assumed to indicate a comment. An absolute path must be used
198 (i.e. the first character must be a "/").
199 In either case, the domain name(s) may contain the special char‐
201 acter "*" which is treated as a wildcard character matching zero
202 or more characters in a domain name.
203 This parameter is not required if a KeyList is in use; in that
205 case, the list of signed domains is implied by the lines in that
206 file.
207 DontSignMailTo (string)
210 A comma-separated list of e-mail addresses (with "*" allowed as
211 a wildcard character), mail to which should never be signed by
212 the filter. Note that this is an "any" feature; if any one of
213 the recipients of the message matches a member of this list, the
214 message will not be signed.
215 EnableCoredumps (boolean)
218 On systems which have such support, make an explicit request to
219 the kernel to dump cores when the filter crashes for some rea‐
220 son. Some modern UNIX systems suppress core dumps during
221 crashes for security reasons if the user ID has changed during
222 the lifetime of the process. Currently only supported on Linux.
223 ExternalIgnoreList (string)
226 Identifies a file of "external" hosts which may send mail
227 through the server as one of the signing domains without creden‐
228 tials as such. Basically suppresses the "external host (host‐
229 name) tried to send mail as (domain)" log messages. Entries in
230 the file should be of the same form as those of the PeerList
231 option below. The list is empty by default.
232 FixCRLF (Boolean)
235 Requests that the DKIM library convert bare CRs and LFs to CRLFs
236 during body canonicalization, anticipating that an MTA somewhere
237 before delivery will do that conversion anyway. The default is
238 to leave them as-is.
239 Include (string)
242 Names a file to be opened and read as an additional configura‐
243 tion file. Nesting is allowed to a maximum of five levels.
244 InsecureKey (string)
247 (Only available if the filter was compiled with libunbound to
248 enable DNSSEC support.) Instructs the filter to treat a passing
249 signature associated with an insecure key in a special way.
250 Possible values are neutral (return a "neutral" result), none
251 (take no special action; this is the default) and fail (return a
252 "fail" result).
253 InsecurePolicy (string)
256 (Only available if the filter was compiled with libunbound to
257 enable DNSSEC support.) Instructs the filter to treat an ADSP
258 policy found in an insecure DNS record in a special way. Possi‐
259 ble values are apply (apply the policy; this is the default) and
260 ignore (ignore the policy).
261 InternalHosts (string)
264 Identifies a file of internal hosts whose mail should be signed
265 rather than verified. Entries in this file follow the same form
266 as those of the PeerList option below. If not specified, the
267 default of "127.0.0.1" is applied. Naturally, providing a value
268 here overrides the default, so if mail from 127.0.0.1 should be
269 signed, the list provided here should include that address
270 explicitly.
271 KeepTemporaryFiles (boolean)
274 Instructs the filter to create temporary files containing the
275 header and body canonicalizations of messages which are signed
276 or verified. The location of these files can be set using the
277 TemporaryDirectory parameter. Intended only for debugging veri‐
278 fication problems.
279 KeyFile (string)
282 Gives the location of a PEM-formatted private key to be used for
283 signing all messages. Ignored if KeyList is defined.
284 KeyList (string)
287 Gives the location of a file listing rules for signing with mul‐
288 tiple keys. If present, overrides any KeyFile setting in the
289 conifguration file. The file named here should contain a set of
290 lines of the form sender-pattern:signing-domain:keypath where
291 sender-pattern is a pattern to match against message senders
292 (with the special character "*" interpreted as "zero or more
293 characters"), signing-domain is the domain to announce as the
294 signing domain when generating signatures, and keypath is the
295 path to the PEM-formatted private key to be used for signing
296 messages which match the sender-pattern. The selector used in
297 the signature will be the filename portion of keypath. If the
298 file referenced by keypath cannot be opened, the filter will try
299 again by appending ".pem" and then ".private" before giving up.
300 LocalADSP (string)
303 Allows specification of local ADSP overrides for domains. This
304 is expected to be a file containing entries, one per line, with
305 comments and blank lines allowed. An entry is of the form
306 domain:policy where domain is either a fully-qualified domain
307 name (e.g. "foo.example.com") or a subdomain name preceded by a
308 period (e.g. ".example.com"), and policy is either unknown, all,
309 or discardable, as per the current ADSP draft specification.
310 This allows local overrides of policies to enforce for domains
311 which either don't publish ADSP or publish weaker policies than
312 the verifier would like to enforce.
313 LogWhy (boolean)
316 If logging is enabled (see Syslog below), issues very detailed
317 logging about the logic behind the filter's decision to either
318 sign a message or verify it. The logic behind the decision is
319 non-trivial and can be confusing to administrators not familiar
320 with its operation. A description of how the decision is made
321 can be found in the OPERATIONS section of the dkim-filter(8) man
322 page. This causes a large increase in the amount of log data
323 generated for each message, so it should be limited to debugging
324 use and not enabled for general operation.
325 MacroList (string)
328 Defines a set of MTA-provided macros which should be checked to
329 see if the sender has been determined to be a local user and
330 therefore whether or not the message should be signed. If a
331 value is specified, the value of the macro must match a value
332 specified (matching is case-sensitive), otherwise the macro must
333 be defined but may contain any value. The set is empty by
334 default, meaning macros are not considered when making the sign-
335 verify decision. The general format of the string is
336 test1[,test2[,...]] where a "test" is of the form
337 macro[=value1[|value2[|...]]]; if one or more value is defined
338 then the macro must be set to one of the listed values, other‐
339 wise the macro must be set but can contain any value.
340 MaximumHeaders (integer)
343 Defines the maximum number of bytes the header block of a mes‐
344 sage may consume before the filter will reject the message.
345 This mitigates a denial-of-service attack in which a client con‐
346 nects to the MTA and begins feeding an unbounded number of
347 header fields of arbitrary size; since the filter keeps a cache
348 of these, the attacker could cause the filter to allocate an
349 unspecified amount of memory. The default is 65536; a value of
350 0 removes the limit.
351 MaximumSignedBytes (integer)
354 Specifies the maximum number of bytes of message body to be
355 signed. Messages shorter than this limit will be signed in
356 their entirety. Setting this value forces BodyLengths to be
357 "True".
358 MilterDebug (integer)
361 Sets the debug level to be requested from the milter library.
362 The default is 0.
363 Minimum (string)
366 Instructs the verification code to fail messages for which a
367 partial signature was received. There are three possible for‐
368 mats: min indicating at least min bytes of the message must be
369 signed (or if the message is smaller than min then all of it
370 must be signed); min% requiring that at least min percent of the
371 received message must be signed; and min+ meaning there may be
372 no more than min bytes of unsigned data appended to the message
373 for it to be considered valid.
374 Mode (string)
377 Selects operating modes. The string is a concatenation of char‐
378 acters which indicate which mode(s) of operation are desired.
379 Valid modes are s (signer) and v (verifier). The default is sv
380 except in test mode (see the dkim-filter(8) man page) in which
381 case the default is v.
382 MTA (string)
385 A comma-separated list of MTA names (a la the sendmail(8) Dae‐
386 monPortOptions Name parameter) whose mail should be signed by
387 this filter. There is no default, meaning MTA name is not con‐
388 sidered when making the sign-verify decision.
389 MustBeSigned (string)
392 Specifies a list of headers which, if present, must be covered
393 by the DKIM signature when verifying a message. The string
394 should be a comma-separated list of header names. If a header
395 in this list is present in the message and is not signed, the
396 filter will treat even an otherwise valid signature as invalid.
397 The default is an empty list.
398 OmitHeaders (string)
401 Specifies a list of headers which should be omitted when gener‐
402 ating signatures. The string should be a comma-separated list
403 of header names. If an entry in the list names any header which
404 is mandated by the DKIM specification, the entry is ignored. A
405 set of headers is listed in the DKIM specification as "SHOULD
406 NOT" be signed; the default list for this parameter contains
407 those headers (Return-Path, Received, Comments, Keywords, Bcc,
408 Resent-Bcc and DKIM-Signature). To omit no headers, simply use
409 the string "-" (or any string which will match no headers).
410 Note that specifying a list with this parameter replaces the
411 default entirely.
412 On-BadSignature (string)
415 Selects the action to be taken when a signature fails to vali‐
416 date. Possible values (with abbreviated forms in parentheses):
417 accept (a) accept the message; discard (d) discard the message;
418 tempfail (t) temp-fail the message; reject (r) reject the mes‐
419 sage. The default is accept.
420 On-Default (string)
423 Selects the action to be taken when any verification or internal
424 error of any kind is encountered. This is processed before the
425 other "On-" values so it can be used as a blanket setting fol‐
426 lowed by specific overrides.
427 On-DNSError (string)
430 Selects the action to be taken when a transient DNS error is
431 encountered. Possible values are the same as those for On-
432 BadSignature. The default is tempfail.
433 On-InternalError (string)
436 Selects the action to be taken when an internal error of some
437 kind is encountered. Possible values are the same as those for
438 On-BadSignature. The default is tempfail.
439 On-NoSignature (string)
442 Selects the action to be taken when a message arrives unsigned.
443 Possible values are the same as those for On-BadSignature. The
444 default is accept.
445 On-Security (string)
448 Selects the action to be taken when a message arrives containing
449 properties that may be a security concern. Possible values are
450 the same as those for On-BadSignature. The default is tempfail.
451 PeerList (string)
454 Identifies a file of "peers" which identifies clients whose con‐
455 nections should be accepted without processing by this filter.
456 The file should contain on each line a hostname, domain name
457 (e.g. ".example.com"), IP address, an IPv6 address (including an
458 IPv4 mapped address), or a CIDR-style IP specification (e.g.
459 "192.168.1.0/24"). An entry beginning with a bang ("!") charac‐
460 ter means "not", allowing exclusions of specific hosts that are
461 otherwise members of larger sets. The order of entries in this
462 file is therefore significant.
463 PidFile (string)
466 Specifies the path to a file which should be created at process
467 start containing the process ID.
468 POPDBFile (string)
471 Requests that the filter consult a POP authentication database
472 named in the string for IP addresses that should be allowed for
473 signing. The filter must be compiled with the POPAUTH flag to
474 enable this feature, since it adds a library dependency.
475 Quarantine (Boolean)
478 Requests that messages which fail verification be quarantined by
479 the MTA. (Requires a sufficiently recent version of the milter
480 library.)
481 QueryCache (Boolean)
484 Instructs the DKIM library to maintain its own local cache of
485 keys and policies retrieved from DNS, rather than relying on the
486 nameserver for caching service. Useful if the nameserver being
487 used by the filter is not local. The filter must be compiled
488 with the QUERY_CACHE flag to enable this feature, since it adds
489 a library dependency.
490 RemoveARAll (Boolean)
493 Removes all Authentication-Results: header fields which also
494 satisfy the requirements of RemoveARFrom below. By default,
495 only those containing a DKIM result are removed.
496 RemoveARFrom (string)
499 Lists patterns of hostnames whose Authentication-Results: header
500 fields should be removed before the message is passed for deliv‐
501 ery. By default only those headers matching the local host's
502 canonical name will be removed. If more than one pattern is
503 desired, the list should be comma-separated. Matching is only
504 done on full hostnames (e.g. "host.example.com") or on domain
505 names (e.g. ".example.com").
506 RemoveOldSignatures (Boolean)
509 Removes all existing signatures when operating in signing mode.
510 ReportAddress (string)
513 Specifies the string to use in the From: header field for outgo‐
514 ing reports (see SendReports and SendADSPReports below). If not
515 specified, the executing user and local hostname will be used to
516 construct the address.
517 RequiredHeaders (boolean)
520 Checks all messages for compliance with RFC2822 header count
521 requirements. Non-compliant messages are rejected.
522 Selector (string)
525 Defines the name of the selector to be used when signing mes‐
526 sages. See the DKIM specification for details. Used only when
527 signing with a single key; see the KeyList parameter above for
528 more information.
529 SendADSPReports (Boolean)
532 If true, when a policy evaluation fails and the signing site
533 advertises a reporting address (i.e. r=user in its policy
534 record) and a request for reports of such failures, the filter
535 will send a structured report to that address containing details
536 of the incident.
537 SendReports (Boolean)
540 If true, when a signature verification fails and the signing
541 site advertises a reporting address (i.e. r=user in its policy
542 record) and a request for reports of such failures, the filter
543 will send a structured report to that address containing details
544 needed to reproduce the problem.
545 SignatureAlgorithm (string)
548 Selects the signing algorithm to use when generating signatures.
549 If the filter was compiled against version 0.9.8 or later of
550 OpenSSL then both rsa-sha1 and rsa-sha256 are available and the
551 latter is the default. Otherwise, only the former is available
552 and it is (obviously) the default.
553 SignatureTTL (integer)
556 Sets the time-to-live, in seconds, of signatures generated by
557 the filter. If not set, no expiration time is added to signa‐
558 tures.
559 SignHeaders (string)
562 Specifies the list of headers which should be included when gen‐
563 erating signatures. The string should be a comma-separated list
564 of header names. If the list omits any header which is mandated
565 by the DKIM specification, those headers are implicitly added.
566 By default, those headers listed in the DKIM specification as
567 "SHOULD" be signed will be signed by the filter. Specifying a
568 list here replaces that list entirely. See the OmitHeaders con‐
569 figuration option for more information.
570 Socket (string)
573 Specifies the socket that should be established by the filter to
574 receive connections from sendmail(8) in order to provide ser‐
575 vice. socketspec is in one of two forms: local:path which cre‐
576 ates a UNIX domain socket at the specified path, or
577 inet:port[@host] which creates a TCP socket on the specified
578 port. If the host is not given as either a hostname or an IP
579 address, the socket will be listening on all interfaces. This
580 option is mandatory either in the configuration file or on the
581 command line.
582 StrictTestMode (Boolean)
585 Selects strict CRLF mode during testing (see the -t command line
586 flag in the dkim-filter(8) man page); messages for which all
587 header fields and body lines are not CRLF-terminated are consid‐
588 ered malformed and will produce an error.
589 SubDomains (Boolean)
592 Sign subdomains of those listed by the Domain parameter as well
593 as the actual domains.
594 Syslog (Boolean)
597 Log via calls to syslog(3) any interesting activity.
598 SyslogFacility (string)
601 Log via calls to syslog(3) using the named facility. The facil‐
602 ity names are the same as the ones allowed in syslog.conf(5).
603 The default is mail .
604 SyslogSuccess (Boolean)
607 Log via calls to syslog(3) additional entries indicating suc‐
608 cessful signing or verification of messages.
609 TemporaryDirectory (string)
612 Specifies the directory in which temporary canonicalization
613 files should be written. The default is to use the libdkim
614 default location, currently /var/tmp.
615 TestPublicKeys (string)
618 Names a file from which public keys should be read. Intended
619 for use only during automated testing.
620 TrustAnchorFile (string)
623 Specifies a file from which trust anchor data should be read
624 when doing DNS queries and applying the DNSSEC protocol.
625 Requires that the filter be compiled with USE_UNBOUND set. See
626 the Unbound documentation at http://unbound.net for the expected
627 format of this file.
628 TrustSignaturesFrom (string)
631 Like Domain, this value consists of either a comma-separated
632 list of domain names or a file containing a list of domains. In
633 either case, the list of domains is used to decide which domains
634 are considered trustworthy in terms of third-party signatures.
635 That is, if a message arrives with a signature from a domain
636 that doesn't match the domain in the From: header, this setting
637 determines whether or not that signature will be trusted. If
638 this value is undefined, all signatures are trusted.
639 UMask (integer)
642 Requests a specific permissions mask to be used for file cre‐
643 ation. This only really applies to creation of the socket when
644 Socket specifies a UNIX domain socket, and to the PidFile (if
645 any); temporary files are created by the mkstemp(3) function
646 which enforces a specific file mode on creation regardless of
647 the process umask. See umask(2) for more information.
648 UserID (string)
651 Attempts to become the specified userid before starting opera‐
652 tions. The value is of the form userid[:group]. The process
653 will be assigned all of the groups and primary group ID of the
654 named userid unless an alternate group is specified.
655 X-Header (Boolean)
658 Causes dkim-filter to add a header indicating the presence of
659 this filter in the path of the message from injection to deliv‐
660 ery. The product's name, version, and the job ID are included
661 in the header's contents.
662
665 When using DNS timeouts (see the DNSTimeout option above), be sure not
666 to use a timeout that is larger than the timeout being used for inter‐
667 action between sendmail and the filter. Otherwise, the MTA could abort
668 a message while waiting for a reply from the filter, which in turn is
669 still waiting for a DNS reply.
670 Features that involve specification of IPv4 addresses or CIDR blocks
672 will use the inet_addr(3) function to parse that information. Users
673 should be familiar with the way that function handles the non-trivial
674 cases (for example, "1.2.3/24" and "1.2.3.0/24" are not the same
675 thing).
676
678 This man page covers version 2.8.0 of dkim-filter.
679
682 Copyright (c) 2007, 2008, Sendmail, Inc. and its suppliers. All rights
683 reserved.
684
687 dkim-filter(8), sendmail(8)
688 RFC4871 - DomainKeys Identified Mail
690 RFC5451 - Message Header Field for Indicating Message Authentication
692 Status
693 Author Domain Signing Practises draft (draft-ietf-dkim-ssp-09)
695 Sendmail, Inc. dkim-filter.conf(5)