1opendkim(8) System Manager's Manual opendkim(8)
2
6 opendkim - DKIM signing and verifying filter for MTAs
7
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
15 opendkim implements the DKIM standard for signing and verifying e-mail
16 messages on a per-domain basis.
17 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 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
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 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 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 In particular:
40 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 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 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 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 backend://[user[:pwd]@][port+]host/dbase[/key=value[?...]]
75 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 mysql:://dbuser:dbpass@3306+dbhost/odkim/table=macros
88 ?keycol=host?datacol=v1,v2
89 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 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 SELECT v1,v2 FROM macros WHERE host = 'foo' AND ID > 1000
105 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 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 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 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 memcache:localhost,otherhost/keyname
143 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 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 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 j) If the string begins with "csl:", the string is treated as a
157 comma-separated list as described in m) below.
158 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 erlang:node@host[,...]:cookie:module:function
164 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 erlang:mynode@myhost,myothernode@myotherhost:
172 chocolate:dkim:lookup
173 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 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 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
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 -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 -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 -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 -D Sign subdomains of those listed by the -d option as well as the
216 actual domains.
217 -e name
219 Extracts the value of name from the configuration file (if any).
220 -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 -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 -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 -l Log via calls to syslog(3) any interesting activity.
237 -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 -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 -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 -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 -P pidfile
279 Specifies a file into which the filter should write its process
280 ID at startup.
281 -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 -r Checks all messages for compliance with RFC5322 header count
288 requirements. Non-compliant messages are rejected.
289 -s selector
291 Defines the name of the selector to be used when signing mes‐
292 sages. See the DKIM specification for details.
293 -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 -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 -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 -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 -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 -V Print the version number and supported canonicalization and sig‐
324 nature algorithms, and then exit without doing anything else.
325 -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 -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 -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
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 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 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 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 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 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
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
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 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
434 The following environment variable(s) can be used to adjust the behav‐
435 iour of this filter:
436 DKIM_TMPDIR
438 The directory to use when creating temporary files. The default
439 is /tmp.
440
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 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 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
464 Filter exit status codes are selected according to sysexits(3).
465
467 DKIM is an amalgam of Yahoo!'s DomainKeys proposal, and Cisco's Inter‐
468 net Identified Mail (IIM) proposal.
469
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 Copyright (c) 2009-2013, 2015, The Trusted Domain Project. All rights
478 reserved.
479
481 opendkim.conf(5), sendmail(8)
482 Sendmail Operations Guide
484 RFC5321 - Simple Mail Transfer Protocol
486 RFC5322 - Internet Messages
488 RFC5451 - Message Header Field for Indicating Message Authentication
490 Status
491 RFC6008 - Authentication-Results Registration for Differentiating among
493 Cryptographic Results
494 RFC6376 - DomainKeys Identified Mail
496 The Trusted Domain Project opendkim(8)