1opendkim.conf(5) File Formats Manual opendkim.conf(5)
2
6 opendkim.conf - Configuration file for opendkim
7
10 /etc/opendkim.conf
11
14 opendkim(8) implements the DKIM specification for signing and verifying
15 e-mail messages on a per-domain basis. This file is its configuration
16 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 that 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 opendkim(8). However, new parameters are generally not
32 added as command line options so the complete set of options is avail‐
33 able here, and thus use of the configuration file is encouraged. In
34 some future release, the set of available command line options is
35 likely to get trimmed.
36 See the opendkim(8) man page for details about how and when the config‐
38 uration file contents are reloaded.
39 Some of these parameters are listed as having a type of "dataset". See
41 the opendkim(8) man page for a description of such parameters.
42
45 AddAllSignatureResults (Boolean)
46 If "true", results for all signatures will be reported by an
47 added Authentication-Results header field. Otherwise, only one
48 signature will be reported, and which one depends on the
49 TrustSignaturesFrom setting or, in its absence, which one(s)
50 passed first or, if none passed, which one was found first dur‐
51 ing message processing.
52 ADSPAction (string)
55 Selects the action to be taken when an ADSP check against a mes‐
56 sage with no valid author signature results in the message being
57 deemed suspicious and discardable. Possible values are "dis‐
58 card" (accept the mesasge but throw it away) and "reject"
59 (bounce the message). If not set, discardable messages will
60 still be delivered.
61 ADSPNoSuchDomain (Boolean)
64 If "true", requests rejection of messages that are determined to
65 be from nonexistent domains according to the author domain sign‐
66 ing practises (ADSP) test.
67 AllowSHA1Only (Boolean)
70 Permit verify mode when only SHA1 support is available. RFC4871
71 requires that verifiers implement both SHA1 and SHA256 support.
72 Setting this feature changes the absence of SHA256 support from
73 an error to a warning.
74 AlwaysAddARHeader (Boolean)
77 Add an "Authentication-Results:" header field even to unsigned
78 messages from domains with no "signs all" policy. The reported
79 DKIM result will be "none" in such cases. Normally unsigned
80 mail from non-strict domains does not cause the results header
81 field to be added.
82 AlwaysSignHeaders (dataset)
85 Specifies a set of header fields that should be included in all
86 signature header lists (the "h=" tag) even if they were not
87 present at the time the signature was generated. The set is
88 empty by default. The purpose of listing an absent header field
89 is to prevent its addition between the signer and the verifier,
90 since the verifier would include that header field if it were
91 added when performing verification, which would mean the signed
92 message and the verified message were different and the verifi‐
93 cation would fail.
94 AnonymousDomains (dataset)
97 When Statistics is enabled, this data set is checked against the
98 From: field of an arriving message to determine whether or not
99 its data should be anonymized as described in AnonymousStatis‐
100 tics below. When the domain is found, the domain is exempted
101 from that setting. That is, if AnonymousStatistics is enabled
102 and the domain is found in this data set, it will not be
103 anonymized; if that feature is not enabled and the domain is
104 found, it will be anonymized. (Note: Feature is experimental.)
105 AnonymousStatistics (Boolean)
108 When Statistics is enabled, setting this flag will pass the
109 From: domain, signature domain and the client IP address por‐
110 tions of the reported data through a one-way hash algorithm to
111 conceal those data while allowing some correlation to take
112 place. This is done for all messages. The default is "true".
113 (Note: Feature is experimental.)
114 AuthservID (string)
117 Sets the "authserv-id" to use when generating the Authentica‐
118 tion-Results: header field after verifying a message. The
119 default is to use the name of the MTA processing the message.
120 If the string "HOSTNAME" is provided, the name of the host run‐
121 ning the filter (as returned by the gethostname(3) function)
122 will be used.
123 AuthservIDWithJobID (Boolean)
126 If "true", requests that the authserv-id portion of the added
127 Authentication-Results: header fields contain the job ID of the
128 message being evaluated.
129 AutoRestart (Boolean)
132 Automatically re-start on failures. Use with caution; if the
133 filter fails instantly after it starts, this can cause a tight
134 fork(2) loop.
135 AutoRestartCount (integer)
138 Sets the maximum automatic restart count. After this number of
139 automatic restarts, the filter will give up and terminate. A
140 value of 0 implies no limit; this is the default.
141 AutoRestartRate (string)
144 Sets the maximum automatic restart rate. If the filter begins
145 restarting faster than the rate defined here, it will give up
146 and terminate. This is a string of the form n/t[u] where n is
147 an integer limiting the count of restarts in the given interval
148 and t[u] defines the time interval through which the rate is
149 calculated; t is an integer and u defines the units thus repre‐
150 sented ("s" or "S" for seconds, the default; "m" or "M" for min‐
151 utes; "h" or "H" for hours; "d" or "D" for days). For example,
152 a value of "10/1h" limits the restarts to 10 in one hour. There
153 is no default, meaning restart rate is not limited.
154 Background (Boolean)
157 Normally opendkim forks and exits immediately, leaving the ser‐
158 vice running in the background. This flag suppresses that be‐
159 haviour so that it runs in the foreground.
160 BaseDirectory (string)
163 If set, instructs the filter to change to the specified direc‐
164 tory using chdir(2) before doing anything else. This means any
165 files referenced elsewhere in the configuration file can be
166 specified relative to this directory. It's also useful for
167 arranging that any crash dumps will be saved to a specific loca‐
168 tion.
169 BodyLengthDB (dataset)
172 Requests that opendkim include a "l=" body length tag when the
173 set contains any of the envelope recipient addresses. The
174 addresses presented are tested against the database in various
175 forms as described under the SigningTable setting (below). This
176 feature of the protocol exists to improve the likelihood that a
177 signature will survive transit through a mailing list server, as
178 they commonly append footers to messages. Note, however, that
179 this creates a potential security issue since someone could add
180 arbitrary text to the signed message and the signature would
181 still validate. See the DKIM specification for details.
182 BogusKey (string)
185 Instructs the filter to treat a passing signature associated
186 with a bogus (forged) key in a special way. Possible values are
187 neutral (return a "neutral" result), none (take no special
188 action) and fail (return a "fail" result; this is the default).
189 (Not enabled for this installation.)
190 BogusPolicy (string)
193 Instructs the filter to treat an ADSP policy found in an bogus
194 (forged) DNS record in a special way. Possible values are apply
195 (apply the policy) and ignore (ignore the policy; this is the
196 default). (Not enabled for this installation.)
197 CaptureUnknownErrors (Boolean)
200 When set, and on systems where MTA quarantine is available, the
201 filter will request quarantine of a message that results in an
202 internal error or resource exhaustion.
203 Canonicalization (string)
206 Selects the canonicalization method(s) to be used when signing
207 messages. When verifying, the message's DKIM-Signature: header
208 field specifies the canonicalization method. The recognized
209 values are relaxed and simple as defined by the DKIM specifica‐
210 tion. The default is simple. The value may include two differ‐
211 ent canonicalizations separated by a slash ("/") character, in
212 which case the first will be applied to the header and the sec‐
213 ond to the body.
214 ClockDrift (integer)
217 Sets the tolerance in seconds to be applied when determining
218 whether a signature was either expired or generated in the
219 future. The default is 300.
220 Diagnostics (Boolean)
223 Requests the inclusion of "z=" tags in signatures, which encode
224 the original header field set for use by verifiers when diagnos‐
225 ing verification failures. Not recommended for normal opera‐
226 tion.
227 DiagnosticDirectory (string)
230 Directory into which to write diagnostic reports when message
231 verification fails on a message bearing a "z=" tag. If not set
232 (the default), these files are not generated.
233 DisableADSP (Boolean)
236 If set, suppresses Author Domain Signing Practices (ADSP)
237 checks, which require multiple additional DNS queries.
238 DNSConnect (Boolean)
241 Requests that the asynchronous resolver start using TCP immedi‐
242 ately rather than using UDP until TCP is actually needed. Does
243 not work with all resolvers.
244 DNSTimeout (integer)
247 Sets the DNS timeout in seconds. A value of 0 causes an infi‐
248 nite wait. The default is 5. Ignored if not using an asynchro‐
249 nous resolver package. See also the NOTES section below.
250 Domain (dataset)
253 A set of domains whose mail should be signed by this filter.
254 Mail from other domains will be verified rather than being
255 signed.
256 This parameter is not required if a SigningTable is in use; in
258 that case, the list of signed domains is implied by the lines in
259 that file.
260 This parameter is ignored if a KeyTable is defined.
262 DomainKeysCompat (boolean)
265 If set, backward compatibility with DomainKeys (RFC4870) key
266 records is enabled. When not set, such keys are considered to
267 be syntactically invalid. The default is "false".
268 DontSignMailTo (dataset)
271 A set of e-mail address, mail to which should never be signed by
272 the filter. Note that this is an "any" feature; if any one of
273 the recipients of the message matches a member of this list, the
274 message will not be signed.
275 EnableCoredumps (boolean)
278 On systems that have such support, make an explicit request to
279 the kernel to dump cores when the filter crashes for some rea‐
280 son. Some modern UNIX systems suppress core dumps during
281 crashes for security reasons if the user ID has changed during
282 the lifetime of the process. Currently only supported on Linux.
283 ExemptDomains (dataset)
286 Specifies a set of domains, mail from which should be ignored
287 entirely by the filter. This is similar to the PeerList setting
288 except that it bases its decision on the sender of the message
289 as identified from the header fields or other message data, not
290 the identity of the SMTP client sending the message.
291 ExternalIgnoreList (dataset)
294 Identifies a set of "external" hosts that may send mail through
295 the server as one of the signing domains without credentials as
296 such. Basically suppresses the "external host (hostname) tried
297 to send mail as (domain)" log messages. Entries in the data set
298 should be of the same form as those of the PeerList option
299 below. The set is empty by default.
300 FinalPolicyScript (string)
303 Gives the name of a Lua script that should be run after the
304 entire message has been received. This can be used to enact
305 local policy decisions such as message rejection, quarantine,
306 rerouting, etc. based on signatures found on the message, the
307 results of attempts to verify them, and other properties of the
308 message or signatures. See opendkim-lua(3) for details. (Not
309 enabled for this installation.)
310 FixCRLF (Boolean)
313 Requests that the DKIM library convert bare CRs and LFs to CRLFs
314 during body canonicalization, anticipating that an MTA somewhere
315 before delivery will do that conversion anyway. The default is
316 to leave them as-is.
317 IdentityHeader (string)
320 This specifies the header field where an identity is stored.
321 (Experimental feature not enabled for this installation.)
322 IdentityHeaderRemove (Boolean)
325 Remove the IdentityHeader after signing. (Experimental feature
326 not enabled for this installation.)
327 Include (string)
330 Names a file to be opened and read as an additional configura‐
331 tion file. Nesting is allowed to a maximum of five levels.
332 InsecureKey (string)
335 Instructs the filter to treat a passing signature associated
336 with a key found in an insecure (i.e. not protected by DNSSEC)
337 DNS record in a special way. Possible values are neutral
338 (return a "neutral" result), none (take no special action; this
339 is the default) and fail (return a "fail" result). (Not enabled
340 for this installation.)
341 InsecurePolicy (string)
344 Instructs the filter to treat an ADSP policy found in an inse‐
345 cure (i.e. not protected by DNSSEC) DNS record in a special
346 way. Possible values are apply (apply the policy; this is the
347 default) and ignore (ignore the policy). (Not enabled for this
348 installation.)
349 InternalHosts (dataset)
352 Identifies a set internal hosts whose mail should be signed
353 rather than verified. Entries in this data set follow the same
354 form as those of the PeerList option below. If not specified,
355 the default of "127.0.0.1" is applied. Naturally, providing a
356 value here overrides the default, so if mail from 127.0.0.1
357 should be signed, the list provided here should include that
358 address explicitly.
359 KeepAuthResults (boolean)
362 Suppresses removal of Authentication-Results header fields con‐
363 taining DKIM results apparently added by this filter (usually
364 the result of a misconfiguration or a forgery).
365 KeepTemporaryFiles (boolean)
368 Instructs the filter to create temporary files containing the
369 header and body canonicalizations of messages that are signed or
370 verified. The location of these files can be set using the Tem‐
371 poraryDirectory parameter. Intended only for debugging verifi‐
372 cation problems.
373 KeyFile (string)
376 Gives the location of a PEM-formatted private key to be used for
377 signing all messages. Ignored if a KeyTable is defined.
378 KeyTable (dataset)
381 Gives the location of a file mapping key names to signing keys.
382 If present, overrides any KeyFile setting in the configuration
383 file. The data set named here maps each key name to three val‐
384 ues: (a) the name of the domain to use in the signature's "d="
385 value; (b) the name of the selector to use in the signature's
386 "s=" value; and (c) either a private key or a path to a file
387 containing a private key. If the first value consists solely of
388 a percent sign ("%") character, it will be replaced by the
389 apparent domain of the sender when generating a signature. If
390 the third value starts with a slash ("/") character, or "./" or
391 "../", then it is presumed to refer to a file from which the
392 private key should be read, otherwise it is itself a PEM-encoded
393 private key or a base64-encoded DER private key; a "%" in the
394 third value in this case will be replaced by the apparent domain
395 name of the sender. The SigningTable (see below) is used to
396 select records from this table to be used to add signatures
397 based on the message sender.
398 LDAPAuthMechanism (string)
401 Names the authentication mechanism to use when connecting to an
402 LDAP server. The default is the empty string, meaning "simple"
403 authentication should be done.
404 LDAPAuthName (string)
407 Specifies the authenticating name to use when using SASL to
408 authenticate to an LDAP server. Requires SASL support be
409 installed on the local system. There is no default.
410 LDAPAuthRealm (string)
413 Specifies the authentication realm to use when using SASL to
414 authenticate to an LDAP server. Requires SASL support be
415 installed on the local system. There is no default.
416 LDAPAuthUser (string)
419 Specifies the authenticating user to use when using SASL to
420 authenticate to an LDAP server. Requires SASL support be
421 installed on the local system. There is no default.
422 LDAPBindPassword (string)
425 Specifies the password to use when conducting an LDAP "bind"
426 operation. There is no default.
427 LDAPBindUser (string)
430 Specifies the user ID to use when conducting an LDAP "bind"
431 operation. There is no default.
432 LDAPUseTLS (Boolean)
435 Indicates whether or not a TLS connection should be established
436 when contacting an LDAP server. The default is "False".
437 LocalADSP (dataset)
440 Allows specification of local ADSP overrides for domains. This
441 is expected to be a data set with keys and matching values; the
442 keys are each either a fully-qualified domain name (e.g.
443 "foo.example.com") or a subdomain name preceded by a period
444 (e.g. ".example.com"), and the values are either unknown, all,
445 or discardable, as per the ADSP specification (RFC5617). This
446 allows local overrides of policies to enforce for domains that
447 either don't publish ADSP or publish weaker policies than the
448 verifier would like to enforce.
449 LogWhy (boolean)
452 If logging is enabled (see Syslog below), issues very detailed
453 logging about the logic behind the filter's decision to either
454 sign a message or verify it. The logic behind the decision is
455 non-trivial and can be confusing to administrators not familiar
456 with its operation. A description of how the decision is made
457 can be found in the OPERATIONS section of the opendkim(8) man
458 page. This causes a large increase in the amount of log data
459 generated for each message, so it should be limited to debugging
460 use and not enabled for general operation.
461 MacroList (dataset)
464 Defines a set of MTA-provided macros that should be checked to
465 see if the sender has been determined to be a local user and
466 therefore whether or not the message should be signed. If a
467 value is specified matching a macro name in the data set, the
468 value of the macro must match a value specified (matching is
469 case-sensitive), otherwise the macro must be defined but may
470 contain any value. The set is empty by default, meaning macros
471 are not considered when making the sign-verify decision. The
472 general format of the value is value1[|value2[|...]]; if one or
473 more value is defined then the macro must be set to one of the
474 listed values, otherwise the macro must be set but can contain
475 any value.
476 In order for the macro and its value to be available to the fil‐
478 ter for checking, the MTA must send it during the protocol
479 exchange. This is either accomplished via manual configuration
480 of the MTA to send the desired macros or, for MTA/filter combi‐
481 nations that support the feature, the filter can request those
482 macros that are of interest. The latter is a feature negotiated
483 at the time the filter receives a connection from the MTA and
484 its availability depends upon the version of milter used to com‐
485 pile the filter and the version of the MTA making the connec‐
486 tion.
487 This data set must be of type "file" or "csl".
489 MaximumHeaders (integer)
491 Defines the maximum number of bytes the header block of a mes‐
492 sage may consume before the filter will reject the message.
493 This mitigates a denial-of-service attack in which a client con‐
494 nects to the MTA and begins feeding an unbounded number of
495 header fields of arbitrary size; since the filter keeps a cache
496 of these, the attacker could cause the filter to allocate an
497 unspecified amount of memory. The default is 65536; a value of
498 0 removes the limit.
499 MaximumSignaturesToVerify (integer)
502 Defines the maximum number of signatures on a message for which
503 verification should be conducted. The default is three. Signa‐
504 tures are selected from the top of the message downward. If
505 TrustSignaturesFrom is set, signatures from domains in that data
506 set are always verified, which may consume part or all of, or
507 even exceed, this limit. Note that this could cause an author
508 domain signature to be ignored, causing the ADSP evaluation to
509 fail and, if SendADSPReports is enabled, a questionable report
510 could be generated.
511 MaximumSignedBytes (integer)
514 Specifies the maximum number of bytes of message body to be
515 signed. Messages shorter than this limit will be signed in
516 their entirety. Setting this value implies use of BodyLengthDB
517 for all addresses.
518 MilterDebug (integer)
521 Sets the debug level to be requested from the milter library.
522 The default is 0.
523 Minimum (string)
526 Instructs the verification code to fail messages for which a
527 partial signature was received. There are three possible for‐
528 mats: min indicating at least min bytes of the message must be
529 signed (or if the message is smaller than min then all of it
530 must be signed); min% requiring that at least min percent of the
531 received message must be signed; and min+ meaning there may be
532 no more than min bytes of unsigned data appended to the message
533 for it to be considered valid.
534 Mode (string)
537 Selects operating modes. The string is a concatenation of char‐
538 acters that indicate which mode(s) of operation are desired.
539 Valid modes are s (signer) and v (verifier). The default is sv
540 except in test mode (see the opendkim(8) man page) in which case
541 the default is v. When signing mode is enabled, one of the fol‐
542 lowing combinations must also be set: (a) Domain, KeyFile,
543 Selector, no KeyTable, no SigningTable; (b) KeyTable, Sign‐
544 ingTable, no Domain, no KeyFile, no Selector; (c) KeyTable,
545 SetupPolicyScript, no Domain, no KeyFile, no Selector.
546 MTA (dataset)
549 A set of MTA names (a la the sendmail(8) DaemonPortOptions Name
550 parameter) whose mail should be signed by this filter. There is
551 no default, meaning MTA name is not considered when making the
552 sign-verify decision.
553 MTACommand (string)
556 Specifies the path to an executable to be used for sending mail
557 such as that generated by SendADSPReports and SendReports. The
558 default is /usr/sbin/sendmail. The executable should accept
559 typical sendmail(8) command line options "-t" (take addresses
560 from message body) and "-f" (set envelope sender), accept the
561 new message on its standard input, and return a non-zero exit
562 status on any error.
563 MultipleSignatures (Boolean)
566 Allow addition of multiple signatures when a signing table is in
567 use. See SigningTable for more information.
568 MustBeSigned (dataset)
571 Specifies a set of header fields that, if present, must be cov‐
572 ered by the DKIM signature when verifying a message. If a
573 header field in this set is present in the message and is not
574 signed, the filter will treat even an otherwise valid signature
575 as invalid. The default is an empty list.
576 NoHeaderB (Boolean)
579 If set, this feature suppresses the use of "header.b" tags in
580 added Authentication-Results header fields. The default is
581 "false", which means those tags will be applied.
582 OmitHeaders (dataset)
585 Specifies a set of header fields that should be omitted when
586 generating signatures. If an entry in the list names any header
587 field that is mandated by the DKIM specification, the entry is
588 ignored. A set of header fields is listed in the DKIM specifi‐
589 cation (RFC4871, Section 5.5) as "SHOULD NOT" be signed; the
590 default list for this parameter contains those fields (Return-
591 Path, Received, Comments, Keywords, Bcc, Resent-Bcc and DKIM-
592 Signature). To omit no headers, simply use the string "." (or
593 any string that will match no header field names). Specifying a
594 list with this parameter replaces the default entirely, unless
595 one entry is "*" in which case the list is interpreted as a
596 delta to the default; for example, "*,+foobar" will use the
597 entire default list plus the name "foobar", while "*,-Bcc" would
598 use the entire default list except for the "Bcc" entry.
599 On-BadSignature (string)
602 Selects the action to be taken when a signature fails to vali‐
603 date. Possible values (with abbreviated forms in parentheses):
604 accept (a) accept the message; discard (d) discard the message;
605 quarantine (q) quarantine the message; reject (r) reject the
606 message; tempfail (t) temp-fail the message. The default is
607 accept.
608 On-Default (string)
611 Selects the action to be taken when any verification or internal
612 error of any kind is encountered. This is processed before the
613 other "On-" values so it can be used as a blanket setting fol‐
614 lowed by specific overrides.
615 On-DNSError (string)
618 Selects the action to be taken when a transient DNS error is
619 encountered. Possible values are the same as those for On-
620 BadSignature. The default is tempfail.
621 On-InternalError (string)
624 Selects the action to be taken when an internal error of some
625 kind is encountered. Possible values are the same as those for
626 On-BadSignature. The default is tempfail.
627 On-KeyNotFound (string)
630 Selects the action to be taken when the key referenced by a sig‐
631 nature is not present in the DNS. Possible values are the same
632 as those for On-BadSignature. The default is accept.
633 On-NoSignature (string)
636 Selects the action to be taken when a message arrives unsigned.
637 Possible values are the same as those for On-BadSignature. The
638 default is accept.
639 On-PolicyError (string)
642 Selects the action to be taken when a an attempt to retrieve and
643 evaluate the author domain's signing policy (ADSP) is unsuccess‐
644 ful. Possible values are the same as those for On-BadSignature.
645 The default is accept.
646 On-Security (string)
649 Selects the action to be taken when a message arrives containing
650 properties that may be a security concern. Possible values are
651 the same as those for On-BadSignature. The default is tempfail.
652 OversignHeaders (dataset)
655 Specifies a set of header fields that should be included in all
656 signature header lists (the "h=" tag) even if they were present
657 at the time the signature was generated. The set is empty by
658 default. The purpose of listing an absent header field is to
659 prevent its addition between the signer and the verifier, since
660 the verifier would include that header field if it were added
661 when performing verification, which would mean the signed mes‐
662 sage and the verified message were different and the verifica‐
663 tion would fail. Unlike AlwaysSignHeaders, the names in this
664 data set are always added to signatures even if they did appear
665 in the original header field set. Note that the fields in this
666 list must also be present in the SignHeaders list, or any signa‐
667 ture produced will be impossible to validate. (Experimental
668 feature not enabled for this installation.)
669 PeerList (dataset)
672 Identifies a set of "peers" that identifies clients whose con‐
673 nections should be accepted without processing by this filter.
674 The set should contain on each line a hostname, domain name
675 (e.g. ".example.com"), IP address, an IPv6 address (including an
676 IPv4 mapped address), or a CIDR-style IP specification (e.g.
677 "192.168.1.0/24"). An entry beginning with a bang ("!") charac‐
678 ter means "not", allowing exclusions of specific hosts that are
679 otherwise members of larger sets. Host and domain names are
680 matched first, then the IP or IPv6 address depending on the con‐
681 nection type. More precise entries are preferred over less pre‐
682 cise ones, i.e. "192.168.1.1" will match before
683 "!192.168.1.0/24". The text form of IPv6 addresses will be
684 forced to lowercase when queried (RFC5952), so the contents of
685 this data set should also use lowercase.
686 PidFile (string)
689 Specifies the path to a file that should be created at process
690 start containing the process ID.
691 POPDBFile (dataset)
694 Requests that the filter consult a set for IP addresses that
695 should be allowed for signing. This feature was designed for
696 POP-before-SMTP datastores. (Not enabled for this installa‐
697 tion.)
698 Quarantine (Boolean)
701 Requests that messages which fail verification be quarantined by
702 the MTA. (Requires a sufficiently recent version of the milter
703 library.)
704 QueryCache (Boolean)
707 Instructs the DKIM library to maintain its own local cache of
708 keys and policies retrieved from DNS, rather than relying on the
709 nameserver for caching service. Useful if the nameserver being
710 used by the filter is not local. (Not enabled for this instal‐
711 lation.)
712 RemoveARAll (Boolean)
715 Removes all Authentication-Results: header fields that also sat‐
716 isfy the requirements of RemoveARFrom below. By default, only
717 those containing a DKIM result are removed.
718 RemoveARFrom (dataset)
721 Defines a set of hostnames whose Authentication-Results: header
722 fields should be removed before the message is passed for deliv‐
723 ery. By default only those header fields matching the local
724 host's canonical name will be removed. Matching is only done on
725 full hostnames (e.g. "host.example.com") or on domain names
726 (e.g. ".example.com").
727 RemoveOldSignatures (Boolean)
730 Removes all existing signatures when operating in signing mode.
731 ReplaceHeaders (data set)
734 Defines a set of header fields that should be affected by the
735 text replacement rules defined by the ReplaceRules setting. By
736 default, all header fields are included. (Experimental feature
737 not enabled for this installation.)
738 ReplaceRules (string)
741 Specifies a file containing a list of text replacement rules
742 that are applied to the message header fields to replace certain
743 content expected to be changed as the message passes through
744 local MTAs. This can be used to accomodate expected changes
745 such as are made to From: fields by MTA "masquerade" features.
746 Each entry in the file consists of a POSIX regular expression,
747 followed by a tab (ASCII 9), followed by the text that should be
748 used to replace the text matching the expression. The '#' char‐
749 acter denotes the beginning of a comment and text from that
750 point on in a single line is ignored. Blank lines are also
751 skipped. (Experimental feature not enabled for this installa‐
752 tion.)
753 ReportAddress (string)
756 Specifies the string to use in the From: header field for outgo‐
757 ing reports (see SendReports and SendADSPReports below). If not
758 specified, the executing user and local hostname will be used to
759 construct the address.
760 ReportBccAddress (string)
763 Specifies address(es) to include in a Bcc: header field on out‐
764 going reports (see SendReports and SendADSPReports below). If
765 multiple addresses are required, they should be comma separated.
766 ReportIntervalDB (dataset)
769 Specifies a set of domains that correspond to how often, in sec‐
770 onds, to report DKIM signature failues. See SendReports for more
771 details. (Experimental feature not enabled for this installa‐
772 tion.)
773 ReputationFail (integer)
776 If the reputation returned by the DNS reputation service exceeds
777 this value then the result "x-dkim-rep" is set to "fail".
778 Defaults to 0. (Experimental feature not enabled for this
779 installation.)
780 ReputationPass (integer)
783 If the reputation returned by the DNS reputation service is less
784 than this value then the result "x-dkim-rep" is set to "pass".
785 Defaults to 0. Values in between ReputationFail and Reputation‐
786 Pass result in "x-dkim-rep" being set to "neutral". (Experimen‐
787 tal feature not enabled for this installation.)
788 ReputationReject (integer)
791 If the reputation returned by the DNS reputation service exceeds
792 this value then the message is rejected. The default value here
793 is 1001, a deliberately impossible value so that rejections are
794 not enabled by default. (Experimental feature not enabled for
795 this installation.)
796 ReputationRoot (string)
799 This is the root directory of the DNS reputation service. Its
800 interface is defined at http://www.dkim-reputation.org. The
801 default value here is "al.dkim-reputation.org". A value of
802 "none" disables the check. (Experimental feature not enabled
803 for this installation.)
804 RequiredHeaders (boolean)
807 Checks all messages for compliance with RFC5322 header field
808 count requirements. Non-compliant messages are rejected.
809 RequireSafeKeys (boolean)
812 When reading a key file, a message will be logged if the key
813 file has the read or write bit set other than for the owner or
814 for a group that the executing process is in. With this feature
815 set to "true", the filter will further consider this an error
816 and refuse to make use of the file's contents. The default is
817 "true".
818 ResignAll (boolean)
821 Where ResignMailTo triggers a re-signing action, this flag indi‐
822 cates whether or not all mail should be signed (if set) versus
823 only verified mail being signed (if not set). The default is
824 "false". (Experimental feature not enabled for this installa‐
825 tion.)
826 ResignMailTo (dataset)
829 Checks each message recipient against the specified dataset for
830 a matching record. The full address is checked in each case,
831 then the hostname, then each domain preceded by ".". If there
832 is a match, the value returned is presumed to be the name of a
833 key in the KeyTable (if defined) to be used to re-sign the mes‐
834 sage in addition to verifying it. If there is a match without a
835 KeyTable, the default key is applied. (Experimental feature not
836 enabled for this installation.)
837 ResolverTracing (Boolean)
840 Requests resolver tracing features be enabled, if available.
841 The effect of this depends on how debugging features of the
842 resolver might be implemented. Currently only effective with
843 the OpenDKIM asynchronous resolver library.
844 ScreenPolicyScript (string)
847 Gives the name of a Lua script that should be run after all of
848 the header fields have been processed for a message; in particu‐
849 lar, this is useful after all DKIM signatures have been detected
850 and initial evaluation has been done. The script has access to
851 all of the header fields and connection information and can that
852 certain signatures be ignored based on that information. See
853 opendkim-lua(3) for details. (Not enabled for this installa‐
854 tion.)
855 Selector (string)
858 Defines the name of the selector to be used when signing mes‐
859 sages. See the DKIM specification for details. Used only when
860 signing with a single key; see the SigningTable parameter below
861 for more information.
862 This parameter is ignored if a KeyTable is defined.
864 SelectorHeader (string)
867 Names a header field whose contents name the key to use when
868 signing. The referenced key must appear in the KeyTable.
869 (Experimental feature not enabled for this installation.)
870 SelectorHeaderRemove (Boolean)
873 Remove the SelectorHeader before signing. (Experimental feature
874 not enabled for this installation.)
875 SendADSPReports (Boolean)
878 If true, when a policy evaluation fails and the signing site
879 advertises a reporting address (i.e. r=user in its policy
880 record) and a request for reports of such failures, the filter
881 will send a structured report to that address containing details
882 of the incident.
883 SenderHeaders (dataset)
886 Specifies an ordered list of header fields that should be
887 searched to determine the sender of a message. This is mainly
888 used when verifying a message to determine the origin domain,
889 particularly for making signing decisions. By default, the DKIM
890 library's internal list is used, which consists solely of the
891 "From" header field. See the OmitHeaders setting for a descrip‐
892 tion of possible values.
893 SenderMacro (string)
896 Use the milter macro string to determine the sender of the mes‐
897 sage. (Experimental feature not enabled for this installation.)
898 SendReports (Boolean)
901 If true, when a signature verification fails and the signing
902 site advertises a reporting address (i.e. r=user in its policy
903 record) and a request for reports of such failures, the filter
904 will send a structured report to that address containing details
905 needed to reproduce the problem.
906 SetupPolicyScript (string)
909 Gives the name of a Lua script that should be run once all
910 header fields for a message have arrived. The script has access
911 to all of the header fields and connection information and can
912 request DKIM verification or signing based on that information.
913 See opendkim-lua(3) for details. (Not enabled for this installa‐
914 tion.)
915 SignatureAlgorithm (string)
918 Selects the signing algorithm to use when generating signatures.
919 Use 'dkim-filter -V' to see the list of supported algorithms.
920 The default is rsa-sha256 if it is available, otherwise it will
921 be rsa-sha1.
922 SignatureTTL (integer)
925 Sets the time-to-live, in seconds, of signatures generated by
926 the filter. If not set, no expiration time is added to signa‐
927 tures.
928 SignHeaders (dataset)
931 Specifies the set of header fields that should be included when
932 generating signatures. If the list omits any header field that
933 is mandated by the DKIM specification, those fields are implic‐
934 itly added. By default, those fields listed in the DKIM speci‐
935 fication as "SHOULD" be signed (RFC4871, Section 5.5) will be
936 signed by the filter. See the OmitHeaders configuration option
937 for more information about the format and interpretation of this
938 field.
939 SigningTable (dataset)
942 Defines a table used to select one or more signatures to apply
943 to a message based on the address found in the From: header
944 field. Keys in this table vary depending on the type of table
945 used; values in this data set should include one field that con‐
946 tains a name found in the KeyTable (see above) that identifies
947 which key should be used in generating the signature, and an
948 optional second field naming the signer of the message that will
949 be included in the "i=" tag in the generated signature.
950 If the first field contains only a "%" character, it will be
952 replaced by the domain found in the From: header field. Simi‐
953 larly, within the optional second field, any "%" character will
954 be replaced by the domain found in the From: header field.
955 If this table specifies a regular expression file ("refile"),
957 then the keys are wildcard patterns that are matched against the
958 address found in the From: header field. Entries are checked in
959 the order in which they appear in the file.
960 For all other database types, the full user@host is checked
962 first, then simply host, then user@.domain (with all superdo‐
963 mains checked in sequence, so "foo.example.com" would first
964 check "user@foo.example.com", then "user@.example.com", then
965 "user@.com"), then .domain, then user@*, and finally *.
966 In any case, only the first match is applied, unless MultipleS‐
968 ignatures is enabled in which case all matches are applied.
969 SingleAuthResult (Boolean)
972 If set, this feature ensures only a single Authentication-
973 Results header field will be added to a message. In this case,
974 the result of DKIM validation will be the only one present,
975 unless it failed and DomainKeys succeeded, in which case only
976 the DomainKeys result will be applied. The default is to show
977 both results in different header fields. (Not enabled for this
978 installation.)
979 Socket (string)
982 Specifies the socket that should be established by the filter to
983 receive connections from sendmail(8) in order to provide ser‐
984 vice. socketspec is in one of two forms: local:path, which cre‐
985 ates a UNIX domain socket at the specified path, or
986 inet:port[@host], which creates a TCP socket on the specified
987 port. If the host is not given as either a hostname or an IP
988 address, the socket will be listening on all interfaces. This
989 option is mandatory either in the configuration file or on the
990 command line.
991 Statistics (filename)
994 This specifies a file in which to store DKIM transaction statis‐
995 tics. See opendkim-stats(8) for a mechanism to parse the file's
996 contents, and opendkim-importstats() for a mechanism to trans‐
997 late the file's contents into SQL database insertions. (Note:
998 Feature is experimental.)
999 StatisticsName (string)
1002 Defines the name to be used as the reporting host in statistics
1003 logs. By default, the local host's name returned by gethost‐
1004 name(3) is used. (Note: Feature is experimental.)
1005 StatisticsPrefix (string)
1008 When AnonymousStatistics is enabled, this string may be speci‐
1009 fied and will be prepended to all data before hashing for more
1010 complete anonymization. This means two records from different
1011 sources referencing the same source will still produce different
1012 hashes, meaning such correlation is now only possible within the
1013 data from a single repoter.
1014 StrictHeaders (Boolean)
1017 If set, instructs the DKIM library to refuse processing of a
1018 message if the header field count does not conform to RFC5322
1019 Section 3.6.
1020 StrictTestMode (Boolean)
1023 Selects strict CRLF mode during testing (see the -t command line
1024 flag in the opendkim(8) man page); messages for which all header
1025 fields and body lines are not CRLF-terminated are considered
1026 malformed and will produce an error.
1027 SubDomains (Boolean)
1030 Sign subdomains of those listed by the Domain parameter as well
1031 as the actual domains.
1032 Syslog (Boolean)
1035 Log via calls to syslog(3) any interesting activity.
1036 SyslogFacility (string)
1039 Log via calls to syslog(3) using the named facility. The facil‐
1040 ity names are the same as the ones allowed in syslog.conf(5).
1041 The default is "mail".
1042 SyslogSuccess (Boolean)
1045 Log via calls to syslog(3) additional entries indicating suc‐
1046 cessful signing or verification of messages.
1047 TemporaryDirectory (string)
1050 Specifies the directory in which temporary canonicalization
1051 files should be written. The default is to use the libdkim
1052 default location, currently /var/tmp.
1053 TestPublicKeys (string)
1056 Names a file from which public keys should be read. Intended
1057 for use only during automated testing.
1058 TrustAnchorFile (string)
1061 Specifies a file from which trust anchor data should be read
1062 when doing DNS queries and applying the DNSSEC protocol. See
1063 the Unbound documentation at http://unbound.net for the expected
1064 format of this file. (Not enabled for this installation.)
1065 TrustSignaturesFrom (dataset)
1068 This value consists of a set of domains that are considered
1069 trustworthy in terms of third-party signatures. That is, if a
1070 message arrives with a signature from a domain that doesn't
1071 match the domain in the From: header, this setting determines
1072 whether or not that signature will be trusted. If this value is
1073 undefined, all signatures are trusted.
1074 UMask (integer)
1077 Requests a specific permissions mask to be used for file cre‐
1078 ation. This only really applies to creation of the socket when
1079 Socket specifies a UNIX domain socket, and to the PidFile (if
1080 any); temporary files are created by the mkstemp(3) function
1081 that enforces a specific file mode on creation regardless of the
1082 process umask. See umask(2) for more information.
1083 UnboundConfigFile (string)
1086 Specifies a configuration file to be passed to the Unbound
1087 library that performs DNS queries applying the DNSSEC protocol.
1088 See the Unbound documentation at http://unbound.net for the
1089 expected content of this file. The results of using this and
1090 the TrustAnchorFile setting at the same time are undefined.
1091 (Not enabled for this installation.)
1092 UserID (string)
1095 Attempts to become the specified userid before starting opera‐
1096 tions. The value is of the form userid[:group]. The process
1097 will be assigned all of the groups and primary group ID of the
1098 named userid unless an alternate group is specified.
1099 VBR-Certifiers (string)
1102 The default certifiers if not specified in X-VBR-Certifiers
1103 header field. (Experimental feature not enabled for this
1104 installation.)
1105 VBR-PurgeFields (string)
1108 If set, arranges to remove X-VBR-Certifiers and X-VBR-Type
1109 fields on messages prior to sending them. (Experimental feature
1110 not enabled for this installation.)
1111 VBR-TrustedCertifiers (string)
1114 A colon or comma sparated list of trusted certifiers to accept
1115 when verifying VBR-Info header field. (Experimental feature not
1116 enabled for this installation.)
1117 VBR-TrustedCertifiersOnly (Boolean)
1120 By default, the certifiers that are in both the trusted certi‐
1121 fiers list (above) and those in the message's VBR-Info header
1122 field will be checked for vouching. With this option set, the
1123 trusted certifiers will be checked and the ones claimed by the
1124 message will be ignored. (Experimental feature not enabled for
1125 this installation.)
1126 VBR-Type (string)
1129 This default VBR type if not specified in the X-VBR-Type header
1130 field. (Experimental feature not enabled for this installa‐
1131 tion.)
1132 X-Header (Boolean)
1135 Causes opendkim to add an "X-DKIM" header field indicating the
1136 presence of this filter in the path of the message from injec‐
1137 tion to delivery. The product's name, version, and the job ID
1138 are included in the header field's contents. Note that the
1139 header field is not added if the Mode setting causes the message
1140 to be ignored (e.g., if only signing mode is enabled and the
1141 configuration causes the message not to be signed, or only ver‐
1142 ify mode is enabled and configuration would otherwise have
1143 caused the message to be signed, then it will not have this
1144 header field added).
1145
1148 When using DNS timeouts (see the DNSTimeout option above), be sure not
1149 to use a timeout that is larger than the timeout being used for inter‐
1150 action between sendmail and the filter. Otherwise, the MTA could abort
1151 a message while waiting for a reply from the filter, which in turn is
1152 still waiting for a DNS reply.
1153 Features that involve specification of IPv4 addresses or CIDR blocks
1155 will use the inet_addr(3) function to parse that information. Users
1156 should be familiar with the way that function handles the non-trivial
1157 cases (for example, "192.0.2/24" and "192.0.2.0/24" are not the same
1158 thing).
1159
1161 /etc/opendkim.conf
1162 Default location of this file.
1163
1165 This man page covers version 2.4.2 of opendkim.
1166
1169 Copyright (c) 2007, 2008, Sendmail, Inc. and its suppliers. All rights
1170 reserved.
1171 Copyright (c) 2009-2011, The OpenDKIM Project. All rights reserved.
1173
1175 opendkim(8), opendkim-lua(3), sendmail(8)
1176 RFC4871 - DomainKeys Identified Mail
1178 RFC5451 - Message Header Field for Indicating Message Authentication
1180 Status
1181 RFC5617 - DKIM Author Domain Signing Practises
1183 RFC5965 - An Extensible Format for Email Feedback Reports
1185 RFC6008 - Authentication-Results Registration for Differentiating among
1187 Cryptographic Results
1188 The OpenDKIM Project opendkim.conf(5)