1opendkim.conf(5)              File Formats Manual             opendkim.conf(5)
2
3
4

NAME

6       opendkim.conf - Configuration file for opendkim
7
8

LOCATION

10       /etc/opendkim.conf
11
12

DESCRIPTION

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
18       Blank  lines  are ignored.  Lines containing a hash ("#") character are
19       truncated at the hash character to allow for comments in the file.
20
21       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
25       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
30       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
37       See the opendkim(8) man page for details about how and when the config‐
38       uration file contents are reloaded.
39
40       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
43       Unless otherwise stated, Boolean values  default  to  "false",  integer
44       values  default  to  0,  and string and dataset values default to being
45       undefined.
46
47

PARAMETERS

49       AllowSHA1Only (Boolean)
50              Permit verify mode when only SHA1 support is available.  RFC6376
51              requires  that verifiers implement both SHA1 and SHA256 support.
52              Setting this feature changes the absence of SHA256 support  from
53              an error to a warning.
54
55
56       AlwaysAddARHeader (Boolean)
57              Add  an  "Authentication-Results:" header field even to unsigned
58              messages from domains with no "signs all" policy.  The  reported
59              DKIM  result  will  be  "none" in such cases.  Normally unsigned
60              mail from non-strict domains does not cause the  results  header
61              field to be added.
62
63
64       AuthservID (string)
65              Sets  the  "authserv-id"  to use when generating the Authentica‐
66              tion-Results: header  field  after  verifying  a  message.   The
67              default  is  to  use the name of the MTA processing the message.
68              If the string "HOSTNAME" is provided, the name of the host  run‐
69              ning  the  filter  (as  returned by the gethostname(3) function)
70              will be used.
71
72
73       AuthservIDWithJobID (Boolean)
74              If "true", requests that the authserv-id portion  of  the  added
75              Authentication-Results:  header fields contain the job ID of the
76              message being evaluated.
77
78
79       AutoRestart (Boolean)
80              Automatically re-start on failures.  Use with  caution;  if  the
81              filter  fails  instantly after it starts, this can cause a tight
82              fork(2) loop.
83
84
85       AutoRestartCount (integer)
86              Sets the maximum automatic restart count.  After this number  of
87              automatic  restarts,  the  filter will give up and terminate.  A
88              value of 0 implies no limit; this is the default.
89
90
91       AutoRestartRate (string)
92              Sets the maximum automatic restart rate.  If the  filter  begins
93              restarting  faster  than  the rate defined here, it will give up
94              and terminate.  This is a string of the form n/t[u] where  n  is
95              an  integer limiting the count of restarts in the given interval
96              and t[u] defines the time interval through  which  the  rate  is
97              calculated;  t is an integer and u defines the units thus repre‐
98              sented ("s" or "S" for seconds, the default; "m" or "M" for min‐
99              utes;  "h" or "H" for hours; "d" or "D" for days).  For example,
100              a value of "10/1h" limits the restarts to 10 in one hour.  There
101              is no default, meaning restart rate is not limited.
102
103
104       Background (Boolean)
105              Causes  opendkim to fork and exits immediately, leaving the ser‐
106              vice running in the background.  The default is "true".
107
108
109       BaseDirectory (string)
110              If set, instructs the filter to change to the  specified  direc‐
111              tory  using chdir(2) before doing anything else.  This means any
112              files referenced elsewhere in  the  configuration  file  can  be
113              specified  relative  to  this  directory.   It's also useful for
114              arranging that any crash dumps will be saved to a specific loca‐
115              tion.
116
117
118       BodyLengthDB (dataset)
119              Requests  that  opendkim include a "l=" body length tag when the
120              set contains any  of  the  envelope  recipient  addresses.   The
121              addresses  presented  are tested against the database in various
122              forms as described under the SigningTable setting (below).  This
123              feature  of the protocol exists to improve the likelihood that a
124              signature will survive transit through a mailing list server, as
125              they  commonly  append footers to messages.  Note, however, that
126              this creates a potential security issue since someone could  add
127              arbitrary  text  to  the  signed message and the signature would
128              still validate.  See the DKIM specification for details.
129
130
131       BogusKey (string)
132              Instructs the filter to treat  a  passing  signature  associated
133              with a bogus (forged) key in a special way.  Possible values are
134              neutral (return a  "neutral"  result),  none  (take  no  special
135              action)  and fail (return a "fail" result; this is the default).
136              (Not enabled for this installation.)
137
138
139       CaptureUnknownErrors (Boolean)
140              When set, and on systems where MTA quarantine is available,  the
141              filter  will  request quarantine of a message that results in an
142              internal error or resource exhaustion.
143
144
145       Canonicalization (string)
146              Selects the canonicalization method(s) to be used  when  signing
147              messages.   When verifying, the message's DKIM-Signature: header
148              field specifies the  canonicalization  method.   The  recognized
149              values  are relaxed and simple as defined by the DKIM specifica‐
150              tion.  The default is simple.  The value may include two differ‐
151              ent  canonicalizations  separated by a slash ("/") character, in
152              which case the first will be applied to the header and the  sec‐
153              ond to the body.
154
155
156       ChangeRootDirectory (string)
157              Requests  that  the  operating  system change the effective root
158              directory of the process to the  one  specified  here  prior  to
159              beginning  execution.   chroot(2)  requires  superuser access. A
160              warning will be generated if UserID is not also set.
161
162
163       ClockDrift (integer)
164              Sets the tolerance in seconds to  be  applied  when  determining
165              whether  a  signature  was  either  expired  or generated in the
166              future.  The default is 300.
167
168
169       Diagnostics (Boolean)
170              Requests the inclusion of "z=" tags in signatures, which  encode
171              the original header field set for use by verifiers when diagnos‐
172              ing verification failures.  Not recommended  for  normal  opera‐
173              tion.
174
175
176       DiagnosticDirectory (string)
177              Directory  into  which  to write diagnostic reports when message
178              verification fails on a message bearing a "z=" tag.  If not  set
179              (the default), these files are not generated.
180
181
182       DisableCryptoInit (Boolean)
183              If  set,  skips initialization of the SSL library initialization
184              steps, which are normaly  required  in  multi-threaded  environ‐
185              ments.   This  assumes some other library opendkim is using will
186              do the required initialization and shutdown.
187
188
189       DNSConnect (Boolean)
190              Requests that the asynchronous resolver start using TCP  immedi‐
191              ately  rather than using UDP until TCP is actually needed.  Does
192              not work with all resolvers.
193
194
195       DNSTimeout (integer)
196              Sets the DNS timeout in seconds.  A value of 0 causes  an  infi‐
197              nite wait.  The default is 5.  Ignored if not using an asynchro‐
198              nous resolver package.  See also the NOTES section below.
199
200
201       Domain (dataset)
202              A set of domains whose mail should be  signed  by  this  filter.
203              Mail  from  other  domains  will  be  verified rather than being
204              signed.
205
206              This parameter is not required if a SigningTable is in  use;  in
207              that case, the list of signed domains is implied by the lines in
208              that file.
209
210              This parameter is ignored if a KeyTable is defined.
211
212
213       DomainKeysCompat (boolean)
214              If set, backward compatibility  with  DomainKeys  (RFC4870)  key
215              records  is  enabled.  When not set, such keys are considered to
216              be syntactically invalid.  The default is "false".
217
218
219       DontSignMailTo (dataset)
220              A set of e-mail address, mail to which should never be signed by
221              the  filter.   Note that this is an "any" feature; if any one of
222              the recipients of the message matches a member of this list, the
223              message will not be signed.
224
225
226       EnableCoredumps (boolean)
227              On  systems  that have such support, make an explicit request to
228              the kernel to dump cores when the filter crashes for  some  rea‐
229              son.   Some  modern  UNIX  systems  suppress  core  dumps during
230              crashes for security reasons if the user ID has  changed  during
231              the lifetime of the process.  Currently only supported on Linux.
232
233
234       ExemptDomains (dataset)
235              Specifies  a  set  of domains, mail from which should be ignored
236              entirely by the filter.  This is similar to the PeerList setting
237              except  that  it bases its decision on the sender of the message
238              as identified from the header fields or other message data,  not
239              the identity of the SMTP client sending the message.
240
241
242       ExternalIgnoreList (dataset)
243              Identifies  a set of "external" hosts that may send mail through
244              the server as one of the signing domains without credentials  as
245              such.   This  has  the  effect of suppressing the "external host
246              (hostname)  tried  to  send  mail  as  (domain)"  log  messages.
247              Entries  in  the data set should be of the same form as those of
248              the PeerList option below.  The set is empty by default.
249
250
251       FinalPolicyScript (string)
252              Gives the name of a Lua script that  should  be  run  after  the
253              entire  message  has  been  received.  This can be used to enact
254              local policy decisions such as  message  rejection,  quarantine,
255              rerouting,  etc.  based  on signatures found on the message, the
256              results of attempts to verify them, and other properties of  the
257              message  or  signatures.   See opendkim-lua(3) for details. (Not
258              enabled for this installation.)
259
260
261       FixCRLF (Boolean)
262              Requests that the DKIM library convert bare CRs and LFs to CRLFs
263              during body canonicalization, anticipating that an MTA somewhere
264              before delivery will do that conversion anyway.  The default  is
265              to leave them as-is.
266
267
268       IdentityHeader (string)
269              This  specifies  the  header  field where an identity is stored.
270              (Experimental feature not enabled for this installation.)
271
272
273       IdentityHeaderRemove (Boolean)
274              Remove the IdentityHeader after signing.  (Experimental  feature
275              not enabled for this installation.)
276
277
278       IgnoreMalformedMail (boolean)
279              Silently  passes  malformed  messages  without alteration.  This
280              includes  messages  that  fail  the  RequiredHeaders  check,  if
281              enabled.   The  default  is  to  pass  those messages but add an
282              Authentication-Results field  indicating  that  they  were  mal‐
283              formed.
284
285
286       Include (string)
287              Names  a  file to be opened and read as an additional configura‐
288              tion file.  Nesting is allowed to a maximum of five levels.
289
290
291       InternalHosts (dataset)
292              Identifies a set internal hosts  whose  mail  should  be  signed
293              rather  than verified.  Entries in this data set follow the same
294              form as those of the PeerList option below.  If  not  specified,
295              the  default  of "127.0.0.1" is applied.  Naturally, providing a
296              value here overrides the default,  so  if  mail  from  127.0.0.1
297              should  be  signed,  the  list provided here should include that
298              address explicitly.
299
300
301       KeepAuthResults (boolean)
302              Suppresses removal of Authentication-Results header fields  con‐
303              taining  DKIM  results  apparently added by this filter (usually
304              the result of a misconfiguration or a forgery).
305
306
307       KeepTemporaryFiles (boolean)
308              Instructs the filter to create temporary  files  containing  the
309              header and body canonicalizations of messages that are signed or
310              verified.  The location of these files can be set using the Tem‐
311              poraryDirectory  parameter.  Intended only for debugging verifi‐
312              cation problems.
313
314
315       KeyFile (string)
316              Gives the location of a PEM-formatted private key to be used for
317              signing all messages.  Ignored if a KeyTable is defined.
318
319
320       KeyTable (dataset)
321              Gives  the location of a file mapping key names to signing keys.
322              If present, overrides any KeyFile setting in  the  configuration
323              file.   The data set named here maps each key name to three val‐
324              ues: (a) the name of the domain to use in the  signature's  "d="
325              value;  (b)  the  name of the selector to use in the signature's
326              "s=" value; and (c) either a private key or a  path  to  a  file
327              containing a private key.  If the first value consists solely of
328              a percent sign ("%") character,  it  will  be  replaced  by  the
329              apparent  domain  of the sender when generating a signature.  If
330              the third value starts with a slash ("/") character, or "./"  or
331              "../",  then  it  is  presumed to refer to a file from which the
332              private key should be read, otherwise it is itself a PEM-encoded
333              private  key  or  a base64-encoded DER private key; a "%" in the
334              third value in this case will be replaced by the apparent domain
335              name  of  the  sender.   The SigningTable (see below) is used to
336              select records from this table to  be  used  to  add  signatures
337              based on the message sender.
338
339
340       LDAPAuthMechanism (string)
341              Names  the authentication mechanism to use when connecting to an
342              LDAP server.  The default is the empty string, meaning  "simple"
343              authentication should be done.
344
345
346       LDAPAuthName (string)
347              Specifies  the  authenticating  name  to  use when using SASL to
348              authenticate to  an  LDAP  server.   Requires  SASL  support  be
349              installed on the local system.  There is no default.
350
351
352       LDAPAuthRealm (string)
353              Specifies  the  authentication  realm  to use when using SASL to
354              authenticate to  an  LDAP  server.   Requires  SASL  support  be
355              installed on the local system.  There is no default.
356
357
358       LDAPAuthUser (string)
359              Specifies  the  authenticating  user  to  use when using SASL to
360              authenticate to  an  LDAP  server.   Requires  SASL  support  be
361              installed on the local system.  There is no default.
362
363
364       LDAPBindPassword (string)
365              Specifies  the  password  to  use when conducting an LDAP "bind"
366              operation.  There is no default.
367
368
369       LDAPBindUser (string)
370              Specifies the user ID to use  when  conducting  an  LDAP  "bind"
371              operation.  There is no default.
372
373
374       LDAPDisableCache (Boolean)
375              Suppresses creation of a local cache in front of LDAP queries.
376
377
378       LDAPKeepaliveIdle (integer)
379              Sets  the number of seconds a connection to an LDAP server needs
380              to remain idle before TCP starts sending keepalive  probes.   If
381              not specified, the LDAP library default is used.
382
383
384       LDAPKeepaliveInterval (integer)
385              Sets  the  interval in seconds between TCP keepalive probes.  If
386              not specified, the LDAP library default is used.
387
388
389       LDAPKeepaliveProbes (integer)
390              Sets the maximum number of  keepalive  probes  TCP  should  send
391              before  abandoning  the  connection.  If not specified, the LDAP
392              library default is used.
393
394
395       LDAPTimeout (integer)
396              Sets the time in seconds after which an LDAP operation should be
397              abandoned.  The default is 5.
398
399
400       LDAPUseTLS (Boolean)
401              Indicates  whether or not a TLS connection should be established
402              when contacting an LDAP server.  The default is "False".
403
404
405       LogResults (boolean)
406              If logging is enabled (see  Syslog  below),  requests  that  the
407              results  of  evaluation  of  all  signatures  that were at least
408              partly intact (i.e., the "d=", "s=",  and  "b="  tags  could  be
409              extracted).
410
411
412       LogWhy (boolean)
413              If  logging  is enabled (see Syslog below), issues very detailed
414              logging about the logic behind the filter's decision  to  either
415              sign  a  message or verify it.  The logic behind the decision is
416              non-trivial and can be confusing to administrators not  familiar
417              with  its  operation.  A description of how the decision is made
418              can be found in the OPERATIONS section of  the  opendkim(8)  man
419              page.   This  causes  a large increase in the amount of log data
420              generated for each message, so it should be limited to debugging
421              use and not enabled for general operation.
422
423
424       MacroList (dataset)
425              Defines  a  set of MTA-provided macros that should be checked to
426              see if the sender has been determined to be  a  local  user  and
427              therefore  whether  or  not  the message should be signed.  If a
428              value is specified matching a macro name in the  data  set,  the
429              value  of  the  macro  must match a value specified (matching is
430              case-sensitive), otherwise the macro must  be  defined  but  may
431              contain  any value.  The set is empty by default, meaning macros
432              are not considered when making the  sign-verify  decision.   The
433              general  format of the value is value1[|value2[|...]]; if one or
434              more value is defined then the macro must be set to one  of  the
435              listed  values,  otherwise the macro must be set but can contain
436              any value.
437
438              In order for the macro and its value to be available to the fil‐
439              ter  for  checking,  the  MTA  must  send it during the protocol
440              exchange.  This is either accomplished via manual  configuration
441              of  the MTA to send the desired macros or, for MTA/filter combi‐
442              nations that support the feature, the filter can  request  those
443              macros that are of interest.  The latter is a feature negotiated
444              at the time the filter receives a connection from  the  MTA  and
445              its availability depends upon the version of milter used to com‐
446              pile the filter and the version of the MTA  making  the  connec‐
447              tion.
448
449              This data set must be of type "file" or "csl".
450
451       MaximumHeaders (integer)
452              Defines  the  maximum number of bytes the header block of a mes‐
453              sage may consume before the  filter  will  reject  the  message.
454              This mitigates a denial-of-service attack in which a client con‐
455              nects to the MTA and  begins  feeding  an  unbounded  number  of
456              header  fields of arbitrary size; since the filter keeps a cache
457              of these, the attacker could cause the  filter  to  allocate  an
458              unspecified  amount of memory.  The default is 65536; a value of
459              0 removes the limit.
460
461
462       MaximumSignaturesToVerify (integer)
463              Defines the maximum number of signatures on a message for  which
464              verification should be conducted.  The default is three.  Signa‐
465              tures are selected from the top of  the  message  downward.   If
466              TrustSignaturesFrom is set, signatures from domains in that data
467              set are always verified, which may consume part or  all  of,  or
468              even exceed, this limit.
469
470
471       MaximumSignedBytes (integer)
472              Specifies  the  maximum  number  of  bytes of message body to be
473              signed.  Messages shorter than this  limit  will  be  signed  in
474              their  entirety.  Setting this value implies use of BodyLengthDB
475              for all addresses.
476
477
478       MilterDebug (integer)
479              Sets the debug level to be requested from  the  milter  library.
480              The default is 0.
481
482
483       Minimum (string)
484              Instructs  the  verification  code  to fail messages for which a
485              partial signature was received.  There are three  possible  for‐
486              mats:  min  indicating at least min bytes of the message must be
487              signed (or if the message is smaller than min  then  all  of  it
488              must be signed); min% requiring that at least min percent of the
489              received message must be signed; and min+ meaning there  may  be
490              no  more than min bytes of unsigned data appended to the message
491              for it to be considered valid.
492
493
494       MinimumKeyBits (integer)
495              Establishes a minimum key size for acceptable signatures.   Sig‐
496              natures with smaller key sizes, even if they otherwise pass DKIM
497              validation, will me marked as invalid.   The  default  is  1024,
498              which  accepts  all signatures.  A value of 0 causes the default
499              to be used.
500
501
502       Mode (string)
503              Selects operating modes.  The string is a concatenation of char‐
504              acters  that  indicate  which  mode(s) of operation are desired.
505              Valid modes are s (signer) and v (verifier).  The default is  sv
506              except in test mode (see the opendkim(8) man page) in which case
507              the default is v.  When signing mode is enabled, one of the fol‐
508              lowing  combinations  must  also  be  set:  (a) Domain, KeyFile,
509              Selector, no KeyTable,  no  SigningTable;  (b)  KeyTable,  Sign‐
510              ingTable,  no  Domain,  no  KeyFile,  no Selector; (c) KeyTable,
511              SetupPolicyScript, no Domain, no KeyFile, no Selector.
512
513
514       MTA (dataset)
515              A set of MTA names (a la the sendmail(8) DaemonPortOptions  Name
516              parameter) whose mail should be signed by this filter.  There is
517              no default, meaning MTA name is not considered when  making  the
518              sign-verify decision.
519
520
521       MTACommand (string)
522              Specifies  the path to an executable to be used for sending mail
523              such  as  that  generated  by  SendReports.   The   default   is
524              /usr/sbin/sendmail.   The executable should accept typical send‐
525              mail(8) command line options "-t" (take addresses  from  message
526              body)  and "-f" (set envelope sender), accept the new message on
527              its standard input, and return a non-zero  exit  status  on  any
528              error.
529
530
531       MultipleSignatures (Boolean)
532              Allow addition of multiple signatures when a signing table is in
533              use.  See SigningTable for more information.
534
535
536       MustBeSigned (dataset)
537              Specifies a set of header fields that, if present, must be  cov‐
538              ered  by  the  DKIM  signature  when  verifying a message.  If a
539              header field in this set is present in the message  and  is  not
540              signed,  the filter will treat even an otherwise valid signature
541              as invalid.  The default is an empty list.
542
543
544       Nameservers (string)
545              Provides a comma-separated list of IP addresses that are  to  be
546              used  when doing DNS queries to retrieve DKIM keys, VBR records,
547              etc.  These override any local defaults built in to the resolver
548              in  use,  which may be defined in /etc/resolv.conf or hard-coded
549              into the software.
550
551
552       NoHeaderB (Boolean)
553              If set, this feature suppresses the use of  "header.b"  tags  in
554              added  Authentication-Results  header  fields.   The  default is
555              "false", which means those tags will be applied.
556
557
558       OmitHeaders (dataset)
559              Specifies a set of header fields that  should  be  omitted  when
560              generating signatures.  If an entry in the list names any header
561              field that is mandated by the DKIM specification, the  entry  is
562              ignored.   A set of header fields is listed in the DKIM specifi‐
563              cation (RFC6376, Section 5.4) as "SHOULD  NOT"  be  signed;  the
564              default  list  for this parameter contains those fields (Return-
565              Path, Received, Comments, Keywords, Bcc,  Resent-Bcc  and  DKIM-
566              Signature).   To  omit no headers, simply use the string "." (or
567              any string that will match no header field names).  Specifying a
568              list  with  this parameter replaces the default entirely, unless
569              one entry is "*" in which case the  list  is  interpreted  as  a
570              delta  to  the  default;  for  example, "*,+foobar" will use the
571              entire default list plus the name "foobar", while "*,-Bcc" would
572              use the entire default list except for the "Bcc" entry.
573
574
575       On-BadSignature (string)
576              Selects  the  action to be taken when a signature fails to vali‐
577              date.  Possible values (with abbreviated forms in  parentheses):
578              accept  (a) accept the message; discard (d) discard the message;
579              quarantine (q) quarantine the message;  reject  (r)  reject  the
580              message;  tempfail  (t)  temp-fail  the message.  The default is
581              accept.  Note that the "t" (testing) flag in a DKIM key bypasses
582              this  behaviour;  a bad signature that references a testing flag
583              will still be delivered, though the added Authentication-Results
584              field  will indicate both the failed result and the test mode so
585              that consumers of the message can take appropriate action.
586
587
588       On-Default (string)
589              Selects the action to be taken when any verification or internal
590              error  of any kind is encountered.  This is processed before the
591              other "On-" values so it can be used as a blanket  setting  fol‐
592              lowed by specific overrides.
593
594
595       On-DNSError (string)
596              Selects  the  action  to  be taken when a transient DNS error is
597              encountered.  Possible values are the  same  as  those  for  On-
598              BadSignature.  The default is tempfail.
599
600
601       On-InternalError (string)
602              Selects  the  action  to be taken when an internal error of some
603              kind is encountered.  Possible values are the same as those  for
604              On-BadSignature.  The default is tempfail.
605
606
607       On-KeyNotFound (string)
608              Selects the action to be taken when the key referenced by a sig‐
609              nature is not present in the DNS.  Possible values are the  same
610              as those for On-BadSignature.  The default is accept.
611
612
613       On-NoSignature (string)
614              Selects  the action to be taken when a message arrives unsigned.
615              Possible values are the same as those for On-BadSignature.   The
616              default is accept.
617
618
619       On-Security (string)
620              Selects the action to be taken when a message arrives containing
621              properties that may be a security concern.  Possible values  are
622              the same as those for On-BadSignature.  The default is tempfail.
623
624
625       On-SignatureError (string)
626              Selects  the  action to be taken when a message cannot be signed
627              because of issues with the message or the key provided for sign‐
628              ing.  Possible values are the same as those for On-BadSignature.
629              The default is reject.
630
631
632       OversignHeaders (dataset)
633              Specifies a set of header fields that should be included in  all
634              signature  header lists (the "h=" tag) once more than the number
635              of times they were actually present in the signed message.   The
636              set is empty by default.  The purpose of this, and especially of
637              listing an absent header field, is to prevent  the  addition  of
638              important fields between the signer and the verifier.  Since the
639              verifier would include that header field when performing verifi‐
640              cation  if it had been added by an intermediary, the signed mes‐
641              sage and the verified message were different and  the  verifica‐
642              tion  would  fail.   Note that listing a field name here and not
643              listing it in the SignHeaders list is likely to generate invalid
644              signatures.
645
646
647       PeerList (dataset)
648              Identifies  a  set of "peers" that identifies clients whose con‐
649              nections should be accepted without processing by  this  filter.
650              The  set  should  contain  on  each line a hostname, domain name
651              (e.g. ".example.com"), IP address, an IPv6 address (including an
652              IPv4  mapped  address),  or  a CIDR-style IP specification (e.g.
653              "192.168.1.0/24").  An entry beginning with a bang ("!") charac‐
654              ter  means "not", allowing exclusions of specific hosts that are
655              otherwise members of larger sets.  Host  and  domain  names  are
656              matched first, then the IP or IPv6 address depending on the con‐
657              nection type.  More precise entries are preferred over less pre‐
658              cise    ones,    i.e.     "192.168.1.1"    will   match   before
659              "!192.168.1.0/24".  The text form  of  IPv6  addresses  will  be
660              forced  to  lowercase when queried (RFC5952), so the contents of
661              this data set should also use lowercase.  The IP address portion
662              of  an  entry may optionally contain square brackets; both forms
663              (with and without) will be checked.
664
665
666       PidFile (string)
667              Specifies the path to a file that should be created  at  process
668              start containing the process ID.
669
670
671       POPDBFile (dataset)
672              Requests  that  the  filter  consult a set for IP addresses that
673              should be allowed for signing. This  feature  was  designed  for
674              POP-before-SMTP  datastores.   (Not  enabled  for this installa‐
675              tion.)
676
677
678       Quarantine (Boolean)
679              Requests that messages which fail verification be quarantined by
680              the  MTA.  (Requires a sufficiently recent version of the milter
681              library.)
682
683
684       QueryCache (Boolean)
685              Instructs the DKIM library to maintain its own  local  cache  of
686              keys and policies retrieved from DNS, rather than relying on the
687              nameserver for caching service.  Useful if the nameserver  being
688              used by the filter is not local.
689
690
691
692       RedirectFailuresTo (address)
693              Messages bearing signatures that failed to verify are redirected
694              to the specified address.  The original envelope  recipient  set
695              is  recorded  in  the  header  before  redirection  occurs.   By
696              default, no redirection is done.
697
698
699       RemoveARAll (Boolean)
700              Removes all Authentication-Results: header fields that also sat‐
701              isfy  the  requirements of RemoveARFrom below.  By default, only
702              those containing a DKIM result are removed.
703
704
705       RemoveARFrom (dataset)
706              Defines a set of hostnames whose Authentication-Results:  header
707              fields should be removed before the message is passed for deliv‐
708              ery.  By default only those header  fields  matching  the  local
709              host's canonical name will be removed.  Matching is only done on
710              full hostnames (e.g.  "host.example.com")  or  on  domain  names
711              (e.g. ".example.com").
712
713
714       RemoveOldSignatures (Boolean)
715              Removes all existing signatures when operating in signing mode.
716
717
718       ReplaceHeaders (data set)
719              Defines  a  set  of header fields that should be affected by the
720              text replacement rules defined by the ReplaceRules setting.   By
721              default,  all header fields are included.  (Experimental feature
722              not enabled for this installation.)
723
724
725       ReplaceRules (string)
726              Specifies a file containing a list  of  text  replacement  rules
727              that are applied to the message header fields to replace certain
728              content expected to be changed as  the  message  passes  through
729              local  MTAs.   This  can be used to accommodate expected changes
730              such as are made to From: fields by MTA  "masquerade"  features.
731              Each  entry  in the file consists of a POSIX regular expression,
732              followed by a tab (ASCII 9), followed by the text that should be
733              used to replace the text matching the expression.  The '#' char‐
734              acter denotes the beginning of a  comment  and  text  from  that
735              point  on  in  a  single  line is ignored.  Blank lines are also
736              skipped.  (Experimental feature not enabled for  this  installa‐
737              tion.)
738
739
740       ReportAddress (string)
741              Specifies the string to use in the From: header field for outgo‐
742              ing reports (see SendReports below).  If not specified, the exe‐
743              cuting  user  and  local  hostname will be used to construct the
744              address.
745
746
747       ReportBccAddress (string)
748              Specifies address(es) to include in a Bcc: header field on  out‐
749              going reports (see SendReports below). If multiple addresses are
750              required, they should be comma separated.
751
752
753       RequestReports (boolean)
754              When signing, includes a request for signature evaluation  fail‐
755              ures in the signature.  (See RFC6651 for details.)
756
757
758       RequiredHeaders (boolean)
759              Checks  all  messages  for  compliance with RFC5322 header field
760              count requirements.  Non-compliant messages are rejected.
761
762
763       RequireSafeKeys (boolean)
764              When reading a key file, a message will be  logged  if  the  key
765              file  has  the read or write bit set other than for the owner or
766              for a group that the executing process is in.  With this feature
767              set  to  "true",  the filter will further consider this an error
768              and refuse to make use of the file's contents.  The  default  is
769              "true".
770
771
772       ResignAll (boolean)
773              Where ResignMailTo triggers a re-signing action, this flag indi‐
774              cates whether or not all mail should be signed (if  set)  versus
775              only  verified  mail  being signed (if not set).  The default is
776              "false".  (Experimental feature not enabled for  this  installa‐
777              tion.)
778
779
780       ResignMailTo (dataset)
781              Checks  each message recipient against the specified dataset for
782              a matching record.  The full address is checked  in  each  case,
783              then  the  hostname, then each domain preceded by ".".  If there
784              is a match, the value returned is presumed to be the name  of  a
785              key  in the KeyTable (if defined) to be used to re-sign the mes‐
786              sage in addition to verifying it.  If there is a match without a
787              KeyTable, the default key is applied.  (Experimental feature not
788              enabled for this installation.)
789
790
791       ResolverConfiguration (string)
792              Provides the given string as configuration  information  to  the
793              underlying  resolver.   For  the standard UNIX resolver, this is
794              unused; for Unbound, the string contains a filename that is con‐
795              sidered to be a configuration file.  There is no default.
796
797
798       ResolverTracing (Boolean)
799              Requests  resolver  tracing  features  be enabled, if available.
800              The effect of this depends on  how  debugging  features  of  the
801              resolver  might  be  implemented.  Currently only effective with
802              the OpenDKIM asynchronous resolver library.
803
804
805       ScreenPolicyScript (string)
806              Gives the name of a Lua script that should be run after  all  of
807              the header fields have been processed for a message; in particu‐
808              lar, this is useful after all DKIM signatures have been detected
809              and  initial evaluation has been done.  The script has access to
810              all of the header fields and connection information and can that
811              certain  signatures  be  ignored based on that information.  See
812              opendkim-lua(3) for details. (Not  enabled  for  this  installa‐
813              tion.)
814
815
816       SelectCanonicalizationHeader (string)
817              Defines  a  header  field  name which, if present, adjusts which
818              canonicalization will be used to generate an outgoing signature.
819              Overrides  the  Canonicalization  setting if the header field is
820              present.  The default is "X-Canonicalization".
821
822
823       Selector (string)
824              Defines the name of the selector to be used  when  signing  mes‐
825              sages.   See the DKIM specification for details.  Used only when
826              signing with a single key; see the SigningTable parameter  below
827              for more information.
828
829              This parameter is ignored if a KeyTable is defined.
830
831
832       SenderHeaders (dataset)
833              Specifies  an  ordered  list  of  header  fields  that should be
834              searched to determine the sender of a message.  The first header
835              field found is the one whose value is used.  This is mainly used
836              when signing for deciding which signing request(s) to make.   By
837              default,  the  "From" header field is the only one checked.  See
838              the OmitHeaders setting for a description of possible values.
839
840
841       SenderMacro (string)
842              Use the milter macro string to determine the sender of the  mes‐
843              sage.  (Experimental feature not enabled for this installation.)
844
845
846       SendReports (Boolean)
847              If  true,  when a signature verification fails and the signature
848              included a reporting request  ("r=y")  and  the  signing  domain
849              advertises  a  reporting  address (i.e.  ra=user) in a reporting
850              record in the DNS, the filter will send a structured  report  to
851              that address containing details needed to reproduce the problem.
852              See RFC6651 for a complete description of this mechanism.
853
854
855       SetupPolicyScript (string)
856              Gives the name of a Lua script  that  should  be  run  once  all
857              header fields for a message have arrived.  The script has access
858              to all of the header fields and connection information  and  can
859              request  DKIM verification or signing based on that information.
860              See opendkim-lua(3) for details. (Not enabled for this installa‐
861              tion.)
862
863
864       SignatureAlgorithm (string)
865              Selects the signing algorithm to use when generating signatures.
866              Use 'opendkim -V' to see the list of supported algorithms.   The
867              default  is  rsa-sha256 if it is available, otherwise it will be
868              rsa-sha1.
869
870
871       SignatureTTL (integer)
872              Sets the time-to-live, in seconds, of  signatures  generated  by
873              the  filter.   If not set, no expiration time is added to signa‐
874              tures.
875
876
877       SignHeaders (dataset)
878              Specifies the set of header fields that should be included  when
879              generating  signatures.  If the list omits any header field that
880              is mandated by the DKIM specification, those fields are  implic‐
881              itly  added.  By default, those fields listed in the DKIM speci‐
882              fication as "SHOULD" be signed (RFC6376, Section  5.4)  will  be
883              signed  by the filter.  See the OmitHeaders configuration option
884              for more information about the format and interpretation of this
885              field.
886
887
888       SigningTable (dataset)
889              Defines  a  table used to select one or more signatures to apply
890              to a message based on the address  found  in  the  From:  header
891              field.   Keys  in this table vary depending on the type of table
892              used; values in this data set should include one field that con‐
893              tains  a  name found in the KeyTable (see above) that identifies
894              which key should be used in generating  the  signature,  and  an
895              optional second field naming the signer of the message that will
896              be included in the "i=" tag in the  generated  signature.   Note
897              that  the "i=" value will not be included in the signature if it
898              conflicts with the signing domain (the "d=" value).
899
900              If the first field contains only a "%"  character,  it  will  be
901              replaced  by  the domain found in the From: header field.  Simi‐
902              larly, within the optional second field, any "%" character  will
903              be replaced by the domain found in the From: header field.
904
905              If  this  table  specifies a regular expression file ("refile"),
906              then the keys are wildcard patterns that are matched against the
907              address found in the From: header field.  Entries are checked in
908              the order in which they appear in the file.
909
910              For all other database types,  the  full  user@host  is  checked
911              first,  then  simply  host, then user@.domain (with all superdo‐
912              mains checked in  sequence,  so  "foo.example.com"  would  first
913              check  "user@foo.example.com",  then  "user@.example.com",  then
914              "user@.com"), then .domain, then user@*, and finally *.
915
916              In any case, only the first match is applied, unless  MultipleS‐
917              ignatures is enabled in which case all matches are applied.
918
919
920       SMTPURI (string)
921              Specifies  a URI (e.g., "smtp://localhost") to which mail should
922              be sent via SMTP when notifications are generated.  (Not enabled
923              for this installation.)
924
925
926       Socket (string)
927              Specifies the socket that should be established by the filter to
928              receive connections from sendmail(8) in order  to  provide  ser‐
929              vice.  socketspec is in one of two forms: local:path, which cre‐
930              ates  a  UNIX  domain  socket  at   the   specified   path,   or
931              inet:port[@host] or inet6:port[@host] which creates a TCP socket
932              on the specified port and in the specified protocol family.   If
933              the host is not given as either a hostname or an IP address, the
934              socket will be  listening  on  all  interfaces.   A  literal  IP
935              address  must  be  enclosed  in square brackets.  This option is
936              mandatory either in the configuration file  or  on  the  command
937              line.
938
939
940       SoftStart (Boolean)
941              If  set, the inability to connect and authenticate to an LDAP or
942              SQL server will not prevent the filter from starting, and recon‐
943              nections  will  be  attempted  for  each  query.  The default is
944              "False".
945
946
947       SoftwareHeader (Boolean)
948              Causes opendkim to add an "DKIM-Filter" header field  indicating
949              the  presence  of  this  filter  in the path of the message from
950              injection to delivery.  The product's name, version, and the job
951              ID  are  included in the header field's contents.  Note that the
952              header field is not added if the Mode setting causes the message
953              to  be  ignored  (e.g.,  if only signing mode is enabled and the
954              configuration causes the message not to be signed, or only  ver‐
955              ify  mode  is  enabled  and  configuration  would otherwise have
956              caused the message to be signed, then  it  will  not  have  this
957              header field added).
958
959
960       Statistics (filename)
961              This specifies a file in which to store DKIM transaction statis‐
962              tics.  See opendkim-stats(8) for a mechanism to parse the file's
963              contents,  and  opendkim-importstats() for a mechanism to trans‐
964              late the file's contents into SQL database insertions.  (Experi‐
965              mental feature not enabled for this installation.)
966
967
968       StatisticsName (string)
969              Defines  the name to be used as the reporting host in statistics
970              logs.  By default, the local host's name  returned  by  gethost‐
971              name(3)  is  used.   (Experimental  feature not enabled for this
972              installation.)
973
974
975       StatisticsPrefix (string)
976              When AnonymousStatistics is enabled, this string may  be  speci‐
977              fied  and  will be prepended to all data before hashing for more
978              complete anonymization.  This means two records  from  different
979              sources referencing the same source will still produce different
980              hashes, meaning such correlation is now only possible within the
981              data from a single repoter.
982
983
984       StrictHeaders (Boolean)
985              If  set,  instructs  the  DKIM library to refuse processing of a
986              message if the header field count does not  conform  to  RFC5322
987              Section 3.6.
988
989
990       StrictTestMode (Boolean)
991              Selects strict CRLF mode during testing (see the -t command line
992              flag in the opendkim(8) man page); messages for which all header
993              fields  and  body  lines  are not CRLF-terminated are considered
994              malformed and will produce an error.
995
996
997       SubDomains (Boolean)
998              Sign subdomains of those listed by the Domain parameter as  well
999              as the actual domains.
1000
1001
1002       Syslog (Boolean)
1003              Log via calls to syslog(3) any interesting activity.
1004
1005
1006       SyslogFacility (string)
1007              Log via calls to syslog(3) using the named facility.  The facil‐
1008              ity names are the same as the ones  allowed  in  syslog.conf(5).
1009              The default is "mail".
1010
1011
1012       SyslogSuccess (Boolean)
1013              Log  via  calls  to syslog(3) additional entries indicating suc‐
1014              cessful signing or verification of messages.
1015
1016
1017       TemporaryDirectory (string)
1018              Specifies the  directory  in  which  temporary  canonicalization
1019              files  should  be  written.   The  default is to use the libdkim
1020              default location, currently /tmp.
1021
1022
1023       TestDNSData (data set)
1024              Provides a data set whose keys will be  treated  as  DNS  record
1025              names  and values as TXT record contents.  Intended for use dur‐
1026              ing automated testing.
1027
1028
1029       TestPublicKeys (string)
1030              Names a file from which public keys should  be  read.   Intended
1031              for use only during automated testing.
1032
1033
1034       TrustAnchorFile (string)
1035              Specifies  a  file  from  which trust anchor data should be read
1036              when doing DNS queries and applying the DNSSEC  protocol.   This
1037              is  currently  ignored unless the underlying library is compiled
1038              to use Unbound; see the documentation at  at  http://unbound.net
1039              for the expected format of this file.
1040
1041
1042       TrustSignaturesFrom (dataset)
1043              This  value  consists  of  a  set of domains that are considered
1044              trustworthy in terms of third-party signatures.  That is,  if  a
1045              message  arrives  with  a  signature  from a domain that doesn't
1046              match the domain in the From: header,  this  setting  determines
1047              whether or not that signature will be trusted.  If this value is
1048              undefined, all signatures are trusted.
1049
1050
1051       UMask (integer)
1052              Requests a specific permissions mask to be used  for  file  cre‐
1053              ation.   This only really applies to creation of the socket when
1054              Socket specifies a UNIX domain socket, and to  the  PidFile  (if
1055              any);  temporary  files  are  created by the mkstemp(3) function
1056              that enforces a specific file mode on creation regardless of the
1057              process umask.  See umask(2) for more information.
1058
1059
1060       UnprotectedKey (string)
1061              Instructs  the  filter  to  treat a passing signature associated
1062              with a key found in an insecure (i.e. not protected  by  DNSSEC)
1063              DNS  record  in  a  special  way.   Possible  values are neutral
1064              (return a "neutral" result), none (take no special action;  this
1065              is the default) and fail (return a "fail" result).  (Not enabled
1066              for this installation.)
1067
1068
1069       UserID (string)
1070              Attempts to become the specified userid before  starting  opera‐
1071              tions.   The  value  is of the form userid[:group].  The process
1072              will be assigned all of the groups and primary group ID  of  the
1073              named userid unless an alternate group is specified.
1074
1075
1076       VBR-Certifiers (string)
1077              The  default  certifiers  if  not  specified in X-VBR-Certifiers
1078              header  field.   (Experimental  feature  not  enabled  for  this
1079              installation.)
1080
1081
1082       VBR-PurgeFields (string)
1083              If  set,  arranges  to  remove  X-VBR-Certifiers  and X-VBR-Type
1084              fields on messages prior to sending them.  (Experimental feature
1085              not enabled for this installation.)
1086
1087
1088       VBR-TrustedCertifiers (string)
1089              A  colon  or comma sparated list of trusted certifiers to accept
1090              when verifying VBR-Info header field.  (Experimental feature not
1091              enabled for this installation.)
1092
1093
1094       VBR-TrustedCertifiersOnly (Boolean)
1095              By  default,  the certifiers that are in both the trusted certi‐
1096              fiers list (above) and those in the  message's  VBR-Info  header
1097              field  will  be checked for vouching.  With this option set, the
1098              trusted certifiers will be checked and the ones claimed  by  the
1099              message  will be ignored.  (Experimental feature not enabled for
1100              this installation.)
1101
1102
1103       VBR-Type (string)
1104              This default VBR type if not specified in the X-VBR-Type  header
1105              field.   (Experimental  feature  not  enabled for this installa‐
1106              tion.)
1107
1108
1109       WeakSyntaxChecks (Boolean)
1110              Requests that the library continue processing messages  even  if
1111              syntax  errors  are  discovered early in message analysis.  This
1112              means, for example, that a signed message with a  mangled  From:
1113              field  will  still  proceed to verification even if the author's
1114              domain could not be determined.
1115
1116

NOTES

1118       When using DNS timeouts (see the DNSTimeout option above), be sure  not
1119       to  use a timeout that is larger than the timeout being used for inter‐
1120       action between sendmail and the filter.  Otherwise, the MTA could abort
1121       a  message  while waiting for a reply from the filter, which in turn is
1122       still waiting for a DNS reply.
1123
1124       Features that involve specification of IPv4 addresses  or  CIDR  blocks
1125       will  use  the  inet_addr(3) function to parse that information.  Users
1126       should be familiar with the way that function handles  the  non-trivial
1127       cases  (for  example,  "192.0.2/24" and "192.0.2.0/24" are not the same
1128       thing).
1129

FILES

1131       /etc/opendkim.conf
1132              Default location of this file.
1133

VERSION

1135       This man page covers version 2.11.0 of opendkim.
1136
1137
1139       Copyright (c) 2007, 2008, Sendmail, Inc. and its suppliers.  All rights
1140       reserved.
1141
1142       Copyright  (c)  2009-2015,  The  Trusted  Domain  Project.   All rights
1143       reserved.
1144

SEE ALSO

1146       opendkim(8), opendkim-lua(3), sendmail(8)
1147
1148       RFC5451 - Message Header Field for  Indicating  Message  Authentication
1149       Status
1150
1151       RFC5617 - DKIM Author Domain Signing Practises
1152
1153       RFC5965 - An Extensible Format for Email Feedback Reports
1154
1155       RFC6008 - Authentication-Results Registration for Differentiating among
1156       Cryptographic Results
1157
1158       RFC6376 - DomainKeys Identified Mail
1159
1160       RFC6651 - Extensions to DomainKeys Identified Mail (DKIM)  for  Failure
1161       Reporting
1162
1163
1164
1165                          The Trusted Domain Project          opendkim.conf(5)
Impressum