1opendkim(8) System Manager's Manual opendkim(8)
2
6 opendkim - DKIM signing and verifying filter for MTAs
7
9 opendkim -p socketspec [-A] [-b modes] [-c canon] [-d domain[,...]]
10 [-D] [-e name] [-f] [-F time] [-k keyfile] [-l] [-L min] [-n] [-o
11 hdrlist] [-P pidfile] [-q] [-Q] [-r] [-s selector] [-S signalg] [-t
12 testfile] [-T secs] [-u userid[:group]] [-v] [-V] [-W] [-x configfile]
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 In particular:
36 a) If the string begins with "file:", then the remainder of the
38 string is presumed to refer to a flat file that contains ele‐
39 ments of the data set, one per line. If a line contains white‐
40 space-separated values, then the line is preusmed to define a
41 key and its corresponding value. Blank lines are ignored, and
42 the hash ("#") character denotes the start of a comment. If a
43 value contains multiple entries, the entries should be separated
44 by colons.
45 b) If the string begins with "refile:", then the remainder of the
47 string is presumed to specify a file that contains a set of pat‐
48 terns, one per line, and their associated values. The pattern
49 is taken as the start of the line to the first whitespace, and
50 the portion after that whitespace is taken as the value to be
51 used when that pattern is matched. Patterns are simple wildcard
52 patterns, matching all text except that the asterisk ("*") char‐
53 acter is considered a wildcard. If a value contains multiple
54 entries, the entries should be separated by colons.
55 c) If the string begins with "db:" and the program was compiled
57 with Sleepycat DB support, then the remainder of the string is
58 presumed to identify a Sleepycat database containing keys and
59 corresponding values. These may be used only to test for mem‐
60 bership in the data set, or for storing keys and corresponding
61 values. If a value contains multiple entries, the entries
62 should be separated by colons.
63 d) If the string begins with "dsn:" and the OpenDKIM library was
65 compiled to support that database type, then the remainder of
66 the string is a Data Store Name describing the type, location
67 parameters and access credentials for an ODBC or SQL database.
68 The DSN is of the form:
69 backend://[user[:pwd]@][port+]host/dbase[/key=value[?...]]
71 where backend is the name of a supported backend database mecha‐
73 nism (e.g. "mysql"), user and password are optional login cre‐
74 dentials for the database, port and host describe the destina‐
75 tion of a TCP connection to connect to that database, dbase is
76 the name of the database to be accessed, and the key=value pairs
77 must specify at least "table", "keycol" and "datacol" values
78 specifying the name of the table, the name of the column to con‐
79 sider as the key, and the name(s) of the column(s) to be consid‐
80 ered as the values (separated by commas). For example (all in
81 one line):
82 mysql:://dbuser:dbpass@3306+dbhost/odkim/table=macros
84 ?keycol=host?datacol=v1,v2
85 defines a MySQL database listening at port 3306 on host
87 "dbhost"; the userid "dbuser" and password "dbpass" should be
88 used to access the database; the database name is "odkim", and
89 the data are in columns "host" (the keys) and "v1" and "v2" (the
90 values) inside table "macros". This example would thus return
91 two values when a match is found.
92 No value within the DSN may contain any of the six punctuation
94 characters (":", "/", "@", "+", "?" and "=") used to separate
95 portions of the DSN from each other.
96 e) If the string begins with "ldap:", "ldaps:" or "ldapi:", it is
98 presumed to be a space-separated set of one or more LDAP URLs
99 that identify a set of servers to be queried. The first one
100 should be a full RFC4516 LDAP URL indicating a base DN template
101 and optional scope, filter and attribute names to use in
102 queries. When constructing a DN template or filter, the special
103 tokens "$d" and "$D" are replaced with the key being queried and
104 they key broken into components, separated at "." characters,
105 each component preceded by "dc=" and followed by "," (so "exam‐
106 ple.com" would become "dc=example,dc=com"). If a data set
107 requires multiple values to be returned, the appropriate
108 attribute names should be given in the correct order to satisfy
109 such requests.
110 f) If the string begins with "lua:", it is presumed to refer to a
112 file that contains a Lua script to be executed whenever a query
113 is performed. The key for the query is placed in a global vari‐
114 able called "query", which the called script can then access.
115 The script may return any number of values as required for the
116 type of query being performed.
117 g) If the string begins with "memcache:", it is presumed to refer
119 to a memory cache database provided by memcached. The remainder
120 of the string is a comma-separated list of hosts to which query
121 attempts should be made, each optionally followed by ":" and a
122 port number; that list must be followed by a slash ("/") charac‐
123 ter and a string that will be used to prefix queries send to the
124 cache. For example:
125 memcache:localhost,otherhost/keyname
127 This would use either "localhost" or "otherhost" to conduct
129 queries, and all strings sent to the dataset will be prefixed
130 with "keyname:".
131 h) If the string contains none of these prefixes but ends with
133 ".db", it is presumed to be a Sleepycat DB as described above
134 (if support for same is compiled in).
135 i) If the string contains none of these prefixes but starts with a
137 slash ("/") character, it is presumed to be a flat file as
138 described above.
139 j) If the string begins with "csl:", the string is treated as a
141 comma-separated list as described in k) below.
142 k) In any other case, the string is presumed to be a comma-sepa‐
144 rated list. Elements in the list are either simple data ele‐
145 ments that are part of the set or, in the case of an entry of
146 the form "x=y", are stored as key-value pairs as described
147 above.
148
150 -A Automatically re-start on failures. Use with caution; if the
151 filter fails instantly after it starts, this can cause a tight
152 fork(2) loop. This can be mitigated using some values in the
153 configuration file to limit restarting. See opendkim.conf(5).
154 -b modes
156 Selects operating modes. modes is a concatenation of characters
157 that indicate which mode(s) of operation are desired. Valid
158 modes are s (signer) and v (verifier). The default is sv except
159 in test mode (see -t below) in which case the default is v.
160 -c canon
162 Selects the canonicalization method(s) to be used when signing
163 messages. When verifying, the message's DKIM-Signature: header
164 specifies the canonicalization method. The recognized values
165 are relaxed and simple as defined by the DKIM specification.
166 The default is simple. The value may include two different
167 canonicalizations separated by a slash ("/") character, in which
168 case the first will be applied to the headers and the second to
169 the body.
170 -d dataset
172 A set of domains whose mail should be signed by this filter.
173 Mail from other domains will be verified rather than being
174 signed.
175 -D Sign subdomains of those listed by the -d option as well as the
177 actual domains.
178 -e name
180 Extracts the value of name from the configuration file (if any).
181 -f Normally opendkim forks and exits immediately, leaving the ser‐
183 vice running in the background. This flag suppresses that be‐
184 haviour so that it runs in the foreground.
185 -F time
187 Specifies a fixed time to use when generating signatures.
188 Ignored unless also used in conjunction with -t (see below).
189 The time must be expressed in the usual UNIX time_t (seconds
190 since epoch) format.
191 -k keyfile
193 Gives the location of a PEM-formatted private key to be used for
194 signing all messages. Ignored if a configuration file is refer‐
195 enced that defines a KeyTable.
196 -l Log via calls to syslog(3) any interesting activity.
198 -L min[%+]
200 Instructs the verification code to fail messages for which a
201 partial signature was received. There are three possible for‐
202 mats: min indicating at least min bytes of the message must be
203 signed (or if the message is smaller than min then all of it
204 must be signed); min% requiring that at least min percent of the
205 received message must be signed; and min+ meaning there may be
206 no more than min bytes of unsigned data appended to the message
207 for it to be considered valid.
208 -n Parse the configuration file and command line arguments, report‐
210 ing any errors found, and then exit. The exit value will be 0
211 if the filter would start up without complaint, or non-zero oth‐
212 erwise.
213 -o dataset
215 Specifies a list of headers that should be omitted when generat‐
216 ing signatures. If an entry in the list names any header which
217 is mandated by the DKIM specification, the entry is ignored. A
218 set of headers is listed in the DKIM specification as "SHOULD
219 NOT" be signed; the default list for this parameter contains
220 those headers (Return-Path, Received, Comments, Keywords, Bcc,
221 Resent-Bcc and DKIM-Signature). To omit no headers, simply use
222 the string "-" (or any string that will match no headers).
223 -p socketspec
225 Specifies the socket that should be established by the filter to
226 receive connections from sendmail(8) in order to provide ser‐
227 vice. socketspec is in one of two forms: local:path which cre‐
228 ates a UNIX domain socket at the specified path, or
229 inet:port[@host] which creates a TCP socket on the specified
230 port. If the host is not given as either a hostname or an IP
231 address, the socket will be listening on all interfaces. If
232 neither socket type is specified, local is assumed, meaning the
233 parameter is interpreted as a path at which the socket should be
234 created. This parameter is mandatory.
235 -P pidfile
237 Specifies a file into which the filter should write its process
238 ID at startup.
239 -q Requests that messages which fail verification be quarantined by
241 the MTA. (Requires a sufficiently recent version of the milter
242 library.)
243 -Q Query test mode. The filter will read two lines from standard
245 input, one containing a database description to be opened and
246 one containing a string of the form "q/n" where "q" is the query
247 to be performed and "n" is the number of fields to be retrieved.
248 -r Checks all messages for compliance with RFC5322 header count
250 requirements. Non-compliant messages are rejected.
251 -s selector
253 Defines the name of the selector to be used when signing mes‐
254 sages. See the DKIM specification for details.
255 -S signalg
257 Selects the signing algorithm to use when generating signatures.
258 Use 'dkim-filter -V' to see the list of supported algorithms.
259 The default is rsa-sha256 if it is available, otherwise it will
260 be rsa-sha1.
261 -t testfile
264 Evaluates (verifies) an RFC5322-formatted message found in test‐
265 file and exits. The value of testfile may be "-" if the message
266 should be read from standard input.
267 -T secs
269 Sets the DNS timeout in seconds. A value of 0 causes an infi‐
270 nite wait. The default is 5. Ignored if not using an asynchro‐
271 nous resolver package. See also the NOTES section below.
272 -u userid[:group]
274 Attempts to be come the specified userid before starting opera‐
275 tions. The process will be assigned all of the groups and pri‐
276 mary group ID of the named userid unless an alternate group is
277 specified.
278 -v Increase verbose output during test mode (see -t above). May be
280 specified more than once to request increasing amounts of out‐
281 put.
282 -V Print the version number and supported canonicalization and sig‐
284 nature algorithms, and then exit without doing anything else.
285 -W If logging is enabled (see -l above), issues very detailed log‐
287 ging about the logic behind the filter's decision to either sign
288 a message or verify it. The "W" stands for "Why?!" since the
289 logic behind the decision is non-trivial and can be confusing to
290 administrators not familiar with its operation. A description
291 of how the decision is made can be found in the OPERATION sec‐
292 tion of this document. This causes a large increase in the
293 amount of log data generated for each message, so it should be
294 limited to debugging use and not enabled for general operation.
295 -x configfile
297 Read the named configuration file. See the opendkim.conf(5) man
298 page for details. Values in the configuration file are overrid‐
299 den when their equivalents are provided on the command line
300 until a configuration reload occurs. The OPERATION section
301 describes how reloads are triggered. The default is to read a
302 configuration file from /etc/opendkim.conf if one exists, or
303 otherwise to apply defaults to all values.
304
306 A message will be verified unless it conforms to the signing criteria,
307 which are: (1) the domain on the From: address or Sender: address (if
308 present) must be listed by the -d command line switch or the Domain
309 configuration file setting, and (2) (a) the client connecting to the
310 MTA must have authenticated, or (b) the client connecting to the MTA
311 must be listed in the file referenced by the InternalHosts configura‐
312 tion file setting (or be in the default list for that option), or (c)
313 the client must be connected to a daemon port named by the MTAs config‐
314 uration file setting, or (d) the MTA must have set one or more macros
315 matching the criteria set by the MacroList configuration file setting.
316 For (a) above, the test is whether or not the MTA macro "{auth_type}"
318 is set and contains any non-empty value. This means the MTA must pass
319 the value of that macro to the filter in order for its value to be
320 tested. Check your MTA's configuration documentation for details.
321 When signing a message, a DKIM-Signature: header will be prepended to
323 the message. The signature is computed using the private key provided.
324 You must be running a version of sendmail(8) recent enough to be able
325 to do header prepend operations (8.13.0 or later).
326 When verifying a message, an Authentication-Results: header will be
328 prepended to indicate the presence of a signature and whether or not it
329 could be validated against the body of the message using the public key
330 advertised by the sender's nameserver. The value of this header can be
331 used by mail user agents to sort or discard messages that were not
332 signed or could not be verified.
333 Upon receiving SIGUSR1, if the filter was started with a configuration
335 file, it will be re-read and the new values used. Note that any com‐
336 mand line overrides provided at startup time will be lost when this is
337 done. Also, the following configuration file values (and their corre‐
338 sponding command line items, if any) are not reloaded through this
339 process: AutoRestart (-A), AutoRestartCount, AutoRestartRate, Back‐
340 ground, MilterDebug, PidFile (-P), POPDBFile, Quarantine (-q),
341 QueryCache, Socket (-p), StrictTestMode, TestPublicKeys, UMask, UserID
342 (-u). The filter does not automatically check the configuration file
343 for changes and reload.
344
346 The following environment variable(s) can be used to adjust the behav‐
347 iour of this filter:
348 DKIM_TMPDIR
350 The directory to use when creating temporary files. The default
351 is /var/tmp.
352
354 When using DNS timeouts (see the -T option above), be sure not to use a
355 timeout that is larger than the timeout being used for interaction
356 between sendmail and the filter. Otherwise, the MTA could abort a mes‐
357 sage while waiting for a reply from the filter, which in turn is still
358 waiting for a DNS reply.
359 The POP authentication database is expected to be a Sleepycat DB file
361 (formerly known as a Berkeley DB) in hash format with keys containing
362 the IP address in text form without a terminating NULL. The values of
363 these records are not checked; only the existence of such records is of
364 interest. The filter will attempt to establish a shared lock on the
365 database before reading from it, so any programs which write to the
366 database should keep their lock use to a minimum or else this filter
367 will appear to hang while waiting for the lock operation to complete.
368 Features that involve specification of IPv4 addresses or CIDR blocks
370 will use the inet_addr(3) function to parse that information. Users
371 should be familiar with the way that function handles the non-trivial
372 cases (for example, "192.0.2/24" and "192.0.2.0/24" are not the same
373 thing).
374
376 DKIM is an amalgam of Yahoo!'s DomainKeys proposal, and Cisco's Inter‐
377 net Identified Mail (IIM) proposal.
378
380 This man page covers version 2.4.2 of opendkim.
381
383 Copyright (c) 2005-2008, Sendmail, Inc. and its suppliers. All rights
384 reserved.
385 Copyright (c) 2009-2011, The OpenDKIM Project. All rights reserved.
387
389 opendkim.conf(5), sendmail(8)
390 Sendmail Operations Guide
392 RFC4871 - DomainKeys Identified Mail
394 RFC5321 - Simple Mail Transfer Protocol
396 RFC5322 - Internet Messages
398 RFC5451 - Message Header Field for Indicating Message Authentication
400 Status
401 RFC6008 - Authentication-Results Registration for Differentiating among
403 Cryptographic Results
404 The OpenDKIM Project opendkim(8)