1opendkim(8)                 System Manager's Manual                opendkim(8)
2
3
4

NAME

6       opendkim - DKIM signing and verifying filter for MTAs
7

SYNOPSIS

9       opendkim  [-A]  [-b modes] [-c canon] [-d domain[,...]]  [-D] [-e name]
10       [-f] [-F time] [-k keyfile] [-l] [-L min] [-n] [-o hdrlist] [-p socket‐
11       spec]  [-P pidfile] [-Q] [-r] [-s selector] [-S signalg] [-t testfiles]
12       [-T secs] [-u userid[:group]] [-v] [-V] [-W] [-x configfile] [-X]
13

DESCRIPTION

15       opendkim implements the DKIM standard for signing and verifying  e-mail
16       messages on a per-domain basis.
17
18       opendkim  uses  the milter interface, originally distributed as part of
19       version 8.11 of sendmail(8), to provide DKIM signing  and/or  verifying
20       service for mail transiting a milter-aware MTA.
21
22       Most,  if not all, of the command line options listed below can also be
23       set using a configuration file.  See the -x option for details.
24

DATA SETS

26       Many of the command line and configuration file parameters  will  refer
27       to  a  "dataset"  as their values.  This refers to a string that either
28       contains the list of desirable values, or to a file that contains them,
29       or (if enabled at compile time) a database containing the data.
30
31       Some data sets require that the value contain more than one entry.  How
32       this is done depends on which data set type is used.
33
34       Which type is used depends on the format of the  specification  string.
35       Note  that not all of these are necessarily supported for all installa‐
36       tions; most of them depend on the availability of a  particular  third-
37       party library at compile time.
38
39       In particular:
40
41       a)     If  the  string  begins  with "file:", then the remainder of the
42              string is presumed to refer to a flat file  that  contains  ele‐
43              ments  of the data set, one per line.  If a line contains white‐
44              space-separated values, then the line is presumed  to  define  a
45              key  and  its corresponding value.  Blank lines are ignored, and
46              the hash ("#") character denotes the start of a comment.   If  a
47              value contains multiple entries, the entries should be separated
48              by colons.
49
50       b)     If the string begins with "refile:", then the remainder  of  the
51              string is presumed to specify a file that contains a set of pat‐
52              terns, one per line, and their associated values.   The  pattern
53              is  taken  as the start of the line to the first whitespace, and
54              the portion after that whitespace is taken as the  value  to  be
55              used when that pattern is matched.  Patterns are simple wildcard
56              patterns, matching all text except that the asterisk ("*") char‐
57              acter  is  considered  a wildcard.  If a value contains multiple
58              entries, the entries should be separated by colons.
59
60       c)     If the string begins with "db:" and  the  program  was  compiled
61              with  Sleepycat  DB support, then the remainder of the string is
62              presumed to identify a Sleepycat database  containing  keys  and
63              corresponding  values.   These may be used only to test for mem‐
64              bership in the data set, or for storing keys  and  corresponding
65              values.   If  a  value  contains  multiple  entries, the entries
66              should be separated by colons.
67
68       d)     If the string begins with "dsn:" and the  OpenDKIM  library  was
69              compiled  to  support  that database type, then the remainder of
70              the string is a Data Store Name describing  the  type,  location
71              parameters  and  access credentials for an ODBC or SQL database.
72              The DSN is of the form:
73
74              backend://[user[:pwd]@][port+]host/dbase[/key=value[?...]]
75
76              where backend is the name of a supported backend database mecha‐
77              nism  (e.g.  "mysql"), user and password are optional login cre‐
78              dentials for the database, port and host describe  the  destina‐
79              tion  of  a TCP connection to connect to that database, dbase is
80              the name of the database to be accessed, and the key=value pairs
81              must  specify  at  least  "table", "keycol" and "datacol" values
82              specifying the name of the table, the name of the column to con‐
83              sider as the key, and the name(s) of the column(s) to be consid‐
84              ered as the values (separated by commas).  For example  (all  in
85              one line):
86
87              mysql:://dbuser:dbpass@3306+dbhost/odkim/table=macros
88                       ?keycol=host?datacol=v1,v2
89
90              defines  a  MySQL  database  listening  at  port  3306  on  host
91              "dbhost"; the userid "dbuser" and password  "dbpass"  should  be
92              used  to  access the database; the database name is "odkim", and
93              the data are in columns "host" (the keys) and "v1" and "v2" (the
94              values)  inside  table "macros".  This example would thus return
95              two values when a match is found.
96
97              The key may also include a "filter" value which will be included
98              in  all  generated  SQL  as an AND clause after the WHERE clause
99              that declares the search criteria.  For example, given the above
100              DSN  specification  with  an  additional "filter" value of "ID >
101              1000", the generated SQL for a query for "foo" would  look  like
102              so:
103
104              SELECT v1,v2 FROM macros WHERE host = 'foo' AND ID > 1000
105
106              No  value  within the DSN may contain any of the six punctuation
107              characters (":", "/", "@", "+", "?" and  "=")  used  to  delimit
108              portions of the DSN.  To include such characters within a value,
109              encode them in  quoted-printable  style  (e.g.,  "=20"  will  be
110              translated  into  a single space character).  Encoding of spaces
111              is also advised.
112
113       e)     If the string begins with "ldap:", "ldaps:" or "ldapi:",  it  is
114              presumed  to  be  a space-separated set of one or more LDAP URLs
115              that identify a set of servers to be  queried.   The  first  one
116              should  be a full RFC4516 LDAP URL indicating a base DN template
117              and optional  scope,  filter  and  attribute  names  to  use  in
118              queries.  When constructing a DN template or filter, the special
119              tokens "$d" and "$D" are replaced with the key being queried and
120              the  key  broken  into  components, separated at "." characters,
121              each component preceded by "dc=" and followed by "," (so  "exam‐
122              ple.com"  would  become  "dc=example,dc=com").   If  a  data set
123              requires  multiple  values  to  be  returned,  the   appropriate
124              attribute  names should be given in the correct order to satisfy
125              such requests.
126
127       f)     If the string begins with "lua:", it is presumed to refer  to  a
128              file  that contains a Lua script to be executed whenever a query
129              is performed.  The key for the query is placed in a global vari‐
130              able  called  "query",  which the called script can then access.
131              The script may return any number of values as required  for  the
132              type of query being performed.
133
134       g)     If  the  string begins with "memcache:", it is presumed to refer
135              to a memory cache database provided by memcached.  The remainder
136              of  the string is a comma-separated list of hosts to which query
137              attempts should be made, each optionally followed by ":"  and  a
138              port number; that list must be followed by a slash ("/") charac‐
139              ter and a string that will be used to prefix queries send to the
140              cache.  For example:
141
142              memcache:localhost,otherhost/keyname
143
144              This  would  use  either  "localhost"  or "otherhost" to conduct
145              queries, and all strings sent to the dataset  will  be  prefixed
146              with "keyname:".
147
148       h)     If  the  string  contains  none  of these prefixes but ends with
149              ".db", it is presumed to be a Sleepycat DB  as  described  above
150              (if support for same is compiled in).
151
152       i)     If  the string contains none of these prefixes but starts with a
153              slash ("/") character, it is presumed  to  be  a  flat  file  as
154              described above.
155
156       j)     If  the  string  begins  with "csl:", the string is treated as a
157              comma-separated list as described in m) below.
158
159       k)     If the string begins with "erlang:", it is presumed to refer  to
160              a function called to be made to the specified distributed Erlang
161              node(s). The specification is of the form
162
163              erlang:node@host[,...]:cookie:module:function
164
165              where node[,...]  is a list  of  comma-separated  erlang  nodes,
166              cookie  is  the  cookie  for  the known nodes of the distributed
167              Erlang setup, module is the name of the Erlang module where  the
168              function  to  be  called  resides,  function  is the name of the
169              Erlang function to be called. For example, (all in one line):
170
171              erlang:mynode@myhost,myothernode@myotherhost:
172                     chocolate:dkim:lookup
173
174              will join the distributed  Erlang  setup  connecting  to  either
175              "mynode@myhost"  or  "myothernode@myotherhost"  (connections  to
176              nodes are tried in order) using "chocolate" as the  cookie,  and
177              use the function "dkim:lookup/1" for lookups.
178
179       l)     If  the string begins with "mdb:", it refers to a directory that
180              contains a memory database, as provided by libmdb from OpenLDAP.
181
182       m)     In any other case, the string is presumed to  be  a  comma-sepa‐
183              rated  list.   Elements  in the list are either simple data ele‐
184              ments that are part of the set or, in the case of  an  entry  of
185              the  form  "x=y",  are  stored  as  key-value pairs as described
186              above.
187

OPTIONS

189       -A     Automatically re-start on failures.  Use with  caution;  if  the
190              filter  fails  instantly after it starts, this can cause a tight
191              fork(2) loop.  This can be mitigated using some  values  in  the
192              configuration file to limit restarting.  See opendkim.conf(5).
193
194       -b modes
195              Selects operating modes.  modes is a concatenation of characters
196              that indicate which mode(s) of  operation  are  desired.   Valid
197              modes are s (signer) and v (verifier).  The default is sv except
198              in test mode (see -t below) in which case the default is v.
199
200       -c canon
201              Selects the canonicalization method(s) to be used  when  signing
202              messages.   When verifying, the message's DKIM-Signature: header
203              specifies the canonicalization method.   The  recognized  values
204              are  relaxed  and  simple  as defined by the DKIM specification.
205              The default is simple.  The  value  may  include  two  different
206              canonicalizations separated by a slash ("/") character, in which
207              case the first will be applied to the headers and the second  to
208              the body.
209
210       -d dataset
211              A  set  of  domains  whose mail should be signed by this filter.
212              Mail from other domains  will  be  verified  rather  than  being
213              signed.
214
215       -D     Sign  subdomains of those listed by the -d option as well as the
216              actual domains.
217
218       -e name
219              Extracts the value of name from the configuration file (if any).
220
221       -f     Normally opendkim forks and exits immediately, leaving the  ser‐
222              vice  running  in the background.  This flag suppresses that be‐
223              haviour so that it runs in the foreground.
224
225       -F time
226              Specifies a  fixed  time  to  use  when  generating  signatures.
227              Ignored  unless  also  used  in conjunction with -t (see below).
228              The time must be expressed in the  usual  UNIX  time_t  (seconds
229              since epoch) format.
230
231       -k keyfile
232              Gives the location of a PEM-formatted private key to be used for
233              signing all messages.  Ignored if a configuration file is refer‐
234              enced that defines a KeyTable.
235
236       -l     Log via calls to syslog(3) any interesting activity.
237
238       -L min[%+]
239              Instructs  the  verification  code  to fail messages for which a
240              partial signature was received.  There are three  possible  for‐
241              mats:  min  indicating at least min bytes of the message must be
242              signed (or if the message is smaller than min  then  all  of  it
243              must be signed); min% requiring that at least min percent of the
244              received message must be signed; and min+ meaning there  may  be
245              no  more than min bytes of unsigned data appended to the message
246              for it to be considered valid.
247
248       -n     Parse the configuration file and command line arguments, report‐
249              ing  any  errors found, and then exit.  The exit value will be 0
250              if the filter would start up without complaint, or non-zero oth‐
251              erwise.
252
253       -o dataset
254              Specifies a list of headers that should be omitted when generat‐
255              ing signatures.  If an entry in the list names any header  which
256              is  mandated by the DKIM specification, the entry is ignored.  A
257              set of headers is listed in the DKIM  specification  as  "SHOULD
258              NOT"  be  signed;  the  default list for this parameter contains
259              those headers (Return-Path, Received, Comments,  Keywords,  Bcc,
260              Resent-Bcc  and DKIM-Signature).  To omit no headers, simply use
261              the string "-" (or any string that will match no headers).
262
263       -p socketspec
264              Specifies the socket that should be established by the filter to
265              receive  connections  from  sendmail(8) in order to provide ser‐
266              vice.  socketspec is in one of two forms: local:path which  cre‐
267              ates   a   UNIX   domain   socket  at  the  specified  path,  or
268              inet:port[@host] or inet6:port[@host] which creates a TCP socket
269              on  the  specified port using the requested protocol family.  If
270              the host is not given as either a hostname or an IP address, the
271              socket  will  be  listening  on  all  interfaces.   A literal IP
272              address must be enclosed in square brackets.  If neither  socket
273              type  is  specified,  local is assumed, meaning the parameter is
274              interpreted as a path at which the  socket  should  be  created.
275              This  parameter is mandatory either here or in the configuration
276              file.
277
278       -P pidfile
279              Specifies a file into which the filter should write its  process
280              ID at startup.
281
282       -Q     Query  test  mode.  The filter will read two lines from standard
283              input, one containing a database description to  be  opened  and
284              one containing a string of the form "q/n" where "q" is the query
285              to be performed and "n" is the number of fields to be retrieved.
286
287       -r     Checks all messages for compliance  with  RFC5322  header  count
288              requirements.  Non-compliant messages are rejected.
289
290       -s selector
291              Defines  the  name  of the selector to be used when signing mes‐
292              sages.  See the DKIM specification for details.
293
294       -S signalg
295              Selects the signing algorithm to use when generating signatures.
296              Use  'opendkim -V' to see the list of supported algorithms.  The
297              default is rsa-sha256 if it is available, otherwise it  will  be
298              rsa-sha1.
299
300
301       -t testfiles
302              Evaluates (verifies) one or more RFC5322-formatted message found
303              in testfiles and exits.  The value  of  testfiles  should  be  a
304              comma-separated  list of one or more filenames, one of which may
305              be "-" if the message should be read from standard input.
306
307       -T secs
308              Sets the DNS timeout in seconds.  A value of 0 causes  an  infi‐
309              nite wait.  The default is 5.  Ignored if not using an asynchro‐
310              nous resolver package.  See also the NOTES section below.
311
312       -u userid[:group]
313              Attempts to be come the specified userid before starting  opera‐
314              tions.   The process will be assigned all of the groups and pri‐
315              mary group ID of the named userid unless an alternate  group  is
316              specified.   See  the FILE PERMISSIONS section for more informa‐
317              tion.
318
319       -v     Increase verbose output during test mode (see -t above).  May be
320              specified  more  than once to request increasing amounts of out‐
321              put.
322
323       -V     Print the version number and supported canonicalization and sig‐
324              nature algorithms, and then exit without doing anything else.
325
326       -W     If  logging is enabled (see -l above), issues very detailed log‐
327              ging about the logic behind the filter's decision to either sign
328              a  message  or verify it.  The "W" stands for "Why?!"  since the
329              logic behind the decision is non-trivial and can be confusing to
330              administrators  not  familiar with its operation.  A description
331              of how the decision is made can be found in the  OPERATION  sec‐
332              tion  of  this  document.   This  causes a large increase in the
333              amount of log data generated for each message, so it  should  be
334              limited to debugging use and not enabled for general operation.
335
336       -x configfile
337              Read the named configuration file.  See the opendkim.conf(5) man
338              page for details.  Values in the configuration file are overrid‐
339              den  when  their  equivalents  are  provided on the command line
340              until a configuration  reload  occurs.   The  OPERATION  section
341              describes  how  reloads are triggered.  The default is to read a
342              configuration file from /etc/opendkim.conf  if  one  exists,  or
343              otherwise to apply defaults to all values.
344
345       -X     Tolerates  configuration  file  items  that have been internally
346              marked as "deprecated".  Normally when a configuration file item
347              is  removed  from  the package, it is flagged in this way for at
348              least one full release cycle.  The presence of a deprecated con‐
349              figuration  file  item  typically causes the filter to return an
350              error and refuse to start.  Setting this  flag  will  allow  the
351              filter to start and a warning is logged.  In some future release
352              when the item is removed completely, a different error  results,
353              and  it  will  not be possible to start the filter.  Use of this
354              flag is NOT RECOMMENDED; it could effectively hide a major  con‐
355              figuration change with serious security implications.
356

OPERATION

358       A  message will be verified unless it conforms to the signing criteria,
359       which are: (1) the domain on the From: address  (if  present)  must  be
360       listed  by  the -d command line switch or the Domain configuration file
361       setting, and (2) (a) the client connecting to the MTA must have authen‐
362       ticated,  or (b) the client connecting to the MTA must be listed in the
363       file referenced by the InternalHosts configuration file setting (or  be
364       in  the  default  list for that option), or (c) the client must be con‐
365       nected to a daemon port named by the MTAs configuration  file  setting,
366       or  (d)  the MTA must have set one or more macros matching the criteria
367       set by the MacroList configuration file setting.
368
369       For (a) above, the test is whether or not the MTA  macro  "{auth_type}"
370       is  set and contains any non-empty value.  This means the MTA must pass
371       the value of that macro to the filter  before  or  during  the  end-of-
372       header  (EOH)  phase  in  order for its value to be tested.  Check your
373       MTA's configuration documentation for details.
374
375       For (1) above, other header fields may be selected  using  the  Sender‐
376       Headers  configuration  file  setting.   See  opendkim.conf(5) for more
377       information.
378
379       When signing a message, a DKIM-Signature: header will be  prepended  to
380       the message.  The signature is computed using the private key provided.
381       You must be running a version of sendmail(8) recent enough to  be  able
382       to do header prepend operations (8.13.0 or later).
383
384       When  verifying  a  message,  an Authentication-Results: header will be
385       prepended to indicate the presence of a signature and whether or not it
386       could be validated against the body of the message using the public key
387       advertised by the sender's nameserver.  The value of this header can be
388       used  by  mail  user  agents  to sort or discard messages that were not
389       signed or could not be verified.
390
391       Upon receiving SIGUSR1, if the filter was started with a  configuration
392       file,  it  will be re-read and the new values used.  Note that any com‐
393       mand line overrides provided at startup time will be lost when this  is
394       done.   Also, the following configuration file values (and their corre‐
395       sponding command line items, if any)  are  not  reloaded  through  this
396       process:  AutoRestart  (-A),  AutoRestartCount,  AutoRestartRate, Back‐
397       ground,  MilterDebug,  PidFile  (-P),   POPDBFile,   Quarantine   (-q),
398       QueryCache,  Socket (-p), StrictTestMode, TestPublicKeys, UMask, UserID
399       (-u).  The filter does not automatically check the  configuration  file
400       for changes and reload.
401

MTA MACROS

403       opendkim  makes  use of three MTA-provided macros, plus any demanded by
404       configuration.  The basic three are: "i" (the envelope ID,  also  known
405       as  the  job  ID  or  the  queue  ID), which is used for logging; "dae‐
406       mon_name" (the symbolic name given to the MTA  instance  that  accepted
407       the connection), which is used when performing tests against any "MTAs"
408       setting used; and "auth_type", which is used to  determine  whether  or
409       not the SMTP client authenticated to the MTA.  If the MTA does not pro‐
410       vide them to opendkim then it is not able to apply their  corresponding
411       tests  or  do useful logging.  Consult your MTA documentation to deter‐
412       mine how to adjust your its configuration if some or all of  these  are
413       not available.
414

FILE PERMISSIONS

416       When the filter is started as the superuser and the UserID (-u) setting
417       is used, the filter gives up its root privileges  by  changing  to  the
418       specified  user after the following steps are taken: (1) the configura‐
419       tion file (if any) is loaded; (2) if the KeyFile (-k) setting is  used,
420       that  key is loaded into memory; (3) all data sets in the configuration
421       file are opened, and those that are based on flat files are  also  read
422       into memory; and (4) if ChangeRootDirectory is set, the process root is
423       changed to that directory.  This means  on  configuration  reload,  the
424       filter  will  not be accessing these files or the configuration file as
425       the superuser (and possibly from a different root), and any  key  files
426       referenced by the KeyTable will also be accessed by the new user.
427
428       Thus,  keys  referenced  by  the KeyTable must always be accessible for
429       read by the unprivileged user.  Also, run-time reloads are not possible
430       if  any  of  the  other  files will not be readable by the unprivileged
431       user.
432

ENVIRONMENT

434       The following environment variable(s) can be used to adjust the  behav‐
435       iour of this filter:
436
437       DKIM_TMPDIR
438              The directory to use when creating temporary files.  The default
439              is /tmp.
440

NOTES

442       When using DNS timeouts (see the -T option above), be sure not to use a
443       timeout  that  is  larger  than  the timeout being used for interaction
444       between sendmail and the filter.  Otherwise, the MTA could abort a mes‐
445       sage  while waiting for a reply from the filter, which in turn is still
446       waiting for a DNS reply.
447
448       The POP authentication database is expected to be a Sleepycat  DB  file
449       (formerly  known  as a Berkeley DB) in hash format with keys containing
450       the IP address in text form without a terminating NULL.  The values  of
451       these records are not checked; only the existence of such records is of
452       interest.  The filter will attempt to establish a shared  lock  on  the
453       database  before  reading  from  it, so any programs which write to the
454       database should keep their lock use to a minimum or  else  this  filter
455       will appear to hang while waiting for the lock operation to complete.
456
457       Features  that  involve  specification of IPv4 addresses or CIDR blocks
458       will use the inet_addr(3) function to parse  that  information.   Users
459       should  be  familiar with the way that function handles the non-trivial
460       cases (for example, "192.0.2/24" and "192.0.2.0/24" are  not  the  same
461       thing).
462

EXIT STATUS

464       Filter exit status codes are selected according to sysexits(3).
465

HISTORY

467       DKIM  is an amalgam of Yahoo!'s DomainKeys proposal, and Cisco's Inter‐
468       net Identified Mail (IIM) proposal.
469

VERSION

471       This man page covers version 2.11.0 of opendkim.
472
474       Copyright (c) 2005-2008, Sendmail, Inc. and its suppliers.  All  rights
475       reserved.
476
477       Copyright  (c) 2009-2013, 2015, The Trusted Domain Project.  All rights
478       reserved.
479

SEE ALSO

481       opendkim.conf(5), sendmail(8)
482
483       Sendmail Operations Guide
484
485       RFC5321 - Simple Mail Transfer Protocol
486
487       RFC5322 - Internet Messages
488
489       RFC5451 - Message Header Field for  Indicating  Message  Authentication
490       Status
491
492       RFC6008 - Authentication-Results Registration for Differentiating among
493       Cryptographic Results
494
495       RFC6376 - DomainKeys Identified Mail
496
497
498
499                          The Trusted Domain Project               opendkim(8)
Impressum