Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
opendkim(8)		    System Manager's Manual		   opendkim(8)

       opendkim	- DKIM signing and verifying filter for	MTAs

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

       opendkim	implements the DKIM standard for signing and verifying	e-mail
       messages	on a per-domain	basis.

       opendkim	 uses  the milter interface, originally	distributed as part of
       version 8.11 of sendmail(8), to provide DKIM signing  and/or  verifying
       service for mail	transiting a milter-aware MTA.

       Most,  if not all, of the command line options listed below can also be
       set using a configuration file.	See the	-x option for details.

       Many of the command line	and configuration file parameters  will	 refer
       to  a  "dataset"	 as their values.  This	refers to a string that	either
       contains	the list of desirable values, or to a file that	contains them,
       or (if enabled at compile time) a database containing the data.

       Some data sets require that the value contain more than one entry.  How
       this is done depends on which data set type is used.

       Which type is used depends on the format	of the	specification  string.
       Note  that not all of these are necessarily supported for all installa-
       tions; most of them depend on the availability of a  particular	third-
       party library at	compile	time.

       In particular:

       a)     If  the  string  begins  with "file:", then the remainder	of the
	      string is	presumed to refer to a flat file  that	contains  ele-
	      ments  of	the data set, one per line.  If	a line contains	white-
	      space-separated values, then the line is presumed	 to  define  a
	      key  and	its corresponding value.  Blank	lines are ignored, and
	      the hash ("#") character denotes the start of a comment.	 If  a
	      value contains multiple entries, the entries should be separated
	      by colons.

       b)     If the string begins with	"refile:", then	the remainder  of  the
	      string is	presumed to specify a file that	contains a set of pat-
	      terns, one per line, and their associated	values.	  The  pattern
	      is  taken	 as the	start of the line to the first whitespace, and
	      the portion after	that whitespace	is taken as the	 value	to  be
	      used when	that pattern is	matched.  Patterns are simple wildcard
	      patterns,	matching all text except that the asterisk ("*") char-
	      acter  is	 considered  a wildcard.  If a value contains multiple
	      entries, the entries should be separated by colons.

       c)     If the string begins with	"db:" and  the	program	 was  compiled
	      with  Sleepycat  DB support, then	the remainder of the string is
	      presumed to identify a Sleepycat database	 containing  keys  and
	      corresponding  values.   These may be used only to test for mem-
	      bership in the data set, or for storing keys  and	 corresponding
	      values.	If  a  value  contains	multiple  entries, the entries
	      should be	separated by colons.

       d)     If the string begins with	"dsn:" and the	OpenDKIM  library  was
	      compiled	to  support  that database type, then the remainder of
	      the string is a Data Store Name describing  the  type,  location
	      parameters  and  access credentials for an ODBC or SQL database.
	      The DSN is of the	form:


	      where backend is the name	of a supported backend database	mecha-
	      nism  (e.g.  "mysql"), user and password are optional login cre-
	      dentials for the database, port and host describe	 the  destina-
	      tion  of	a TCP connection to connect to that database, dbase is
	      the name of the database to be accessed, and the key=value pairs
	      must  specify  at	 least	"table", "keycol" and "datacol"	values
	      specifying the name of the table,	the name of the	column to con-
	      sider as the key,	and the	name(s)	of the column(s) to be consid-
	      ered as the values (separated by commas).	 For example  (all  in
	      one line):


	      defines  a  MySQL	 database  listening at	port 3306 on host "db-
	      host"; the userid	"dbuser" and password "dbpass" should be  used
	      to  access  the  database; the database name is "odkim", and the
	      data are in columns "host" (the keys) and	 "v1"  and  "v2"  (the
	      values)  inside  table "macros".	This example would thus	return
	      two values when a	match is found.

	      No value within the DSN may contain any of the  six  punctuation
	      characters  (":",	 "/",  "@", "+", "?" and "=") used to separate
	      portions of the DSN from each other.

       e)     If the string begins with	"ldap:", "ldaps:" or "ldapi:",	it  is
	      presumed	to  be	a space-separated set of one or	more LDAP URLs
	      that identify a set of servers to	be  queried.   The  first  one
	      should  be a full	RFC4516	LDAP URL indicating a base DN template
	      and optional  scope,  filter  and	 attribute  names  to  use  in
	      queries.	When constructing a DN template	or filter, the special
	      tokens "$d" and "$D" are replaced	with the key being queried and
	      the  key	broken	into  components, separated at "." characters,
	      each component preceded by "dc=" and followed by "," (so	"exam-"	would  become "dc=example,dc=com").  If	a data set re-
	      quires multiple values to	be returned, the appropriate attribute
	      names  should  be	given in the correct order to satisfy such re-

       f)     If the string begins with	"lua:",	it is presumed to refer	 to  a
	      file  that contains a Lua	script to be executed whenever a query
	      is performed.  The key for the query is placed in	a global vari-
	      able  called  "query",  which the	called script can then access.
	      The script may return any	number of values as required  for  the
	      type of query being performed.

       g)     If  the  string begins with "memcache:", it is presumed to refer
	      to a memory cache	database provided by memcached.	 The remainder
	      of  the string is	a comma-separated list of hosts	to which query
	      attempts should be made, each optionally followed	by ":"	and  a
	      port number; that	list must be followed by a slash ("/") charac-
	      ter and a	string that will be used to prefix queries send	to the
	      cache.  For example:


	      This  would  use	either	"localhost"  or	"otherhost" to conduct
	      queries, and all strings sent to the dataset  will  be  prefixed
	      with "keyname:".

       h)     If  the  string  contains	 none  of these	prefixes but ends with
	      ".db", it	is presumed to be a Sleepycat DB  as  described	 above
	      (if support for same is compiled in).

       i)     If  the string contains none of these prefixes but starts	with a
	      slash ("/") character, it	is presumed to be a flat file  as  de-
	      scribed above.

       j)     If  the  string  begins  with "csl:", the	string is treated as a
	      comma-separated list as described	in m) below.

       k)     If the string begins with	"erlang:", it is presumed to refer  to
	      a	function called	to be made to the specified distributed	Erlang
	      node(s). The specification is of the form


	      where node[,...]	is a list  of  comma-separated	erlang	nodes,
	      cookie  is the cookie for	the known nodes	of the distributed Er-
	      lang setup, module is the	name of	the Erlang  module  where  the
	      function	to  be called resides, function	is the name of the Er-
	      lang function to be called. For example, (all in one line):


	      will join	the distributed	 Erlang	 setup	connecting  to	either
	      "mynode@myhost"  or  "myothernode@myotherhost"  (connections  to
	      nodes are	tried in order)	using "chocolate" as the  cookie,  and
	      use the function "dkim:lookup/1" for lookups.

       l)     If  the string begins with "mdb:", it refers to a	directory that
	      contains a memory	database, as provided by libmdb	from OpenLDAP.

       m)     In any other case, the string is presumed	to  be	a  comma-sepa-
	      rated  list.   Elements  in the list are either simple data ele-
	      ments that are part of the set or, in the	case of	 an  entry  of
	      the  form	 "x=y",	 are  stored  as  key-value pairs as described

       -A     Automatically re-start on	failures.  Use with  caution;  if  the
	      filter  fails  instantly after it	starts,	this can cause a tight
	      fork(2) loop.  This can be mitigated using some  values  in  the
	      configuration file to limit restarting.  See opendkim.conf(5).

       -b modes
	      Selects operating	modes.	modes is a concatenation of characters
	      that indicate which mode(s) of  operation	 are  desired.	 Valid
	      modes are	s (signer) and v (verifier).  The default is sv	except
	      in test mode (see	-t below) in which case	the default is v.

       -c canon
	      Selects the canonicalization method(s) to	be used	 when  signing
	      messages.	  When verifying, the message's	DKIM-Signature:	header
	      specifies	the canonicalization method.   The  recognized	values
	      are  relaxed  and	 simple	 as defined by the DKIM	specification.
	      The default is simple.  The  value  may  include	two  different
	      canonicalizations	separated by a slash ("/") character, in which
	      case the first will be applied to	the headers and	the second  to
	      the body.

       -d dataset
	      A	 set  of  domains  whose mail should be	signed by this filter.
	      Mail from	other domains  will  be	 verified  rather  than	 being

       -D     Sign  subdomains of those	listed by the -d option	as well	as the
	      actual domains.

       -e name
	      Extracts the value of name from the configuration	file (if any).

       -f     Normally opendkim	forks and exits	immediately, leaving the  ser-
	      vice  running  in	the background.	 This flag suppresses that be-
	      haviour so that it runs in the foreground.

       -F time
	      Specifies	a fixed	time to	use when generating  signatures.   Ig-
	      nored  unless also used in conjunction with -t (see below).  The
	      time must	be expressed in	the usual UNIX time_t  (seconds	 since
	      epoch) format.

       -k keyfile
	      Gives the	location of a PEM-formatted private key	to be used for
	      signing all messages.  Ignored if	a configuration	file is	refer-
	      enced that defines a KeyTable.

       -l     Log via calls to syslog(3) any interesting activity.

       -L min[%+]
	      Instructs	 the  verification  code  to fail messages for which a
	      partial signature	was received.  There are three	possible  for-
	      mats:  min  indicating at	least min bytes	of the message must be
	      signed (or if the	message	is smaller than	min  then  all	of  it
	      must be signed); min% requiring that at least min	percent	of the
	      received message must be signed; and min+	meaning	there  may  be
	      no  more than min	bytes of unsigned data appended	to the message
	      for it to	be considered valid.

       -n     Parse the	configuration file and command line arguments, report-
	      ing  any	errors found, and then exit.  The exit value will be 0
	      if the filter would start	up without complaint, or non-zero oth-

       -o dataset
	      Specifies	a list of headers that should be omitted when generat-
	      ing signatures.  If an entry in the list names any header	 which
	      is  mandated by the DKIM specification, the entry	is ignored.  A
	      set of headers is	listed in the DKIM  specification  as  "SHOULD
	      NOT"  be	signed;	 the  default list for this parameter contains
	      those headers (Return-Path, Received, Comments,  Keywords,  Bcc,
	      Resent-Bcc  and DKIM-Signature).	To omit	no headers, simply use
	      the string "-" (or any string that will match no headers).

       -p socketspec
	      Specifies	the socket that	should be established by the filter to
	      receive  connections  from  sendmail(8) in order to provide ser-
	      vice.  socketspec	is in one of two forms:	local:path which  cre-
	      ates   a	 UNIX	domain	 socket	 at  the  specified  path,  or
	      inet:port[@host] or inet6:port[@host] which creates a TCP	socket
	      on  the  specified port using the	requested protocol family.  If
	      the host is not given as either a	hostname or an IP address, the
	      socket  will  be	listening on all interfaces.  A	literal	IP ad-
	      dress must be enclosed in	square brackets.   If  neither	socket
	      type  is	specified,  local is assumed, meaning the parameter is
	      interpreted as a path at which the  socket  should  be  created.
	      This  parameter is mandatory either here or in the configuration

       -P pidfile
	      Specifies	a file into which the filter should write its  process
	      ID at startup.

       -Q     Query  test  mode.  The filter will read two lines from standard
	      input, one containing a database description to  be  opened  and
	      one containing a string of the form "q/n"	where "q" is the query
	      to be performed and "n" is the number of fields to be retrieved.

       -r     Checks all messages for compliance with RFC5322 header count re-
	      quirements.  Non-compliant messages are rejected.

       -s selector
	      Defines  the  name  of the selector to be	used when signing mes-
	      sages.  See the DKIM specification for details.

       -S signalg
	      Selects the signing algorithm to use when	generating signatures.
	      Use  'opendkim -V' to see	the list of supported algorithms.  The
	      default is rsa-sha256 if it is available,	otherwise it  will  be

       -t testfiles
	      Evaluates	(verifies) one or more RFC5322-formatted message found
	      in testfiles and exits.  The value  of  testfiles	 should	 be  a
	      comma-separated  list of one or more filenames, one of which may
	      be "-" if	the message should be read from	standard input.

       -T secs
	      Sets the DNS timeout in seconds.	A value	of 0 causes  an	 infi-
	      nite wait.  The default is 5.  Ignored if	not using an asynchro-
	      nous resolver package.  See also the NOTES section below.

       -u userid[:group]
	      Attempts to be come the specified	userid before starting	opera-
	      tions.   The process will	be assigned all	of the groups and pri-
	      mary group ID of the named userid	unless an alternate  group  is
	      specified.   See	the FILE PERMISSIONS section for more informa-

       -v     Increase verbose output during test mode (see -t above).	May be
	      specified	 more  than once to request increasing amounts of out-

       -V     Print the	version	number and supported canonicalization and sig-
	      nature algorithms, and then exit without doing anything else.

       -W     If  logging is enabled (see -l above), issues very detailed log-
	      ging about the logic behind the filter's decision	to either sign
	      a	 message  or verify it.	 The "W" stands	for "Why?!"  since the
	      logic behind the decision	is non-trivial and can be confusing to
	      administrators  not  familiar with its operation.	 A description
	      of how the decision is made can be found in the  OPERATION  sec-
	      tion  of	this  document.	  This	causes a large increase	in the
	      amount of	log data generated for each message, so	it  should  be
	      limited to debugging use and not enabled for general operation.

       -x configfile
	      Read the named configuration file.  See the opendkim.conf(5) man
	      page for details.	 Values	in the configuration file are overrid-
	      den  when	their equivalents are provided on the command line un-
	      til a configuration reload occurs.  The  OPERATION  section  de-
	      scribes  how  reloads  are  triggered.  The default is to	read a
	      configuration file from /usr/local/etc/opendkim.conf if one  ex-
	      ists, or otherwise to apply defaults to all values.

       -X     Tolerates	 configuration	file  items  that have been internally
	      marked as	"deprecated".  Normally	when a configuration file item
	      is  removed  from	 the package, it is flagged in this way	for at
	      least one	full release cycle.  The presence of a deprecated con-
	      figuration  file	item  typically	causes the filter to return an
	      error and	refuse to start.  Setting this	flag  will  allow  the
	      filter to	start and a warning is logged.	In some	future release
	      when the item is removed completely, a different error  results,
	      and  it  will  not be possible to	start the filter.  Use of this
	      flag is NOT RECOMMENDED; it could	effectively hide a major  con-
	      figuration change	with serious security implications.

       A  message will be verified unless it conforms to the signing criteria,
       which are: (1) the domain on the	From: address  (if  present)  must  be
       listed  by  the -d command line switch or the Domain configuration file
       setting,	and (2)	(a) the	client connecting to the MTA must have authen-
       ticated,	 or (b)	the client connecting to the MTA must be listed	in the
       file referenced by the InternalHosts configuration file setting (or  be
       in  the	default	 list for that option),	or (c) the client must be con-
       nected to a daemon port named by	the MTAs configuration	file  setting,
       or  (d)	the MTA	must have set one or more macros matching the criteria
       set by the MacroList configuration file setting.

       For (a) above, the test is whether or not the MTA  macro	 "{auth_type}"
       is  set and contains any	non-empty value.  This means the MTA must pass
       the value of that macro to the filter  before  or  during  the  end-of-
       header  (EOH)  phase  in	 order for its value to	be tested.  Check your
       MTA's configuration documentation for details.

       For (1) above, other header fields may be selected  using  the  Sender-
       Headers	configuration file setting.  See opendkim.conf(5) for more in-

       When signing a message, a DKIM-Signature: header	will be	 prepended  to
       the message.  The signature is computed using the private key provided.
       You must	be running a version of	sendmail(8) recent enough to  be  able
       to do header prepend operations (8.13.0 or later).

       When  verifying	a  message,  an	Authentication-Results:	header will be
       prepended to indicate the presence of a signature and whether or	not it
       could be	validated against the body of the message using	the public key
       advertised by the sender's nameserver.  The value of this header	can be
       used  by	 mail  user  agents  to	sort or	discard	messages that were not
       signed or could not be verified.

       Upon receiving SIGUSR1, if the filter was started with a	 configuration
       file,  it  will be re-read and the new values used.  Note that any com-
       mand line overrides provided at startup time will be lost when this  is
       done.   Also, the following configuration file values (and their	corre-
       sponding	command	line items, if any)  are  not  reloaded	 through  this
       process:	 AutoRestart  (-A),  AutoRestartCount,	AutoRestartRate, Back-
       ground,	MilterDebug,  PidFile  (-P),   POPDBFile,   Quarantine	 (-q),
       QueryCache,  Socket (-p), StrictTestMode, TestPublicKeys, UMask,	UserID
       (-u).  The filter does not automatically	check the  configuration  file
       for changes and reload.

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

       When the	filter is started as the superuser and the UserID (-u) setting
       is used,	the filter gives up its	root privileges	 by  changing  to  the
       specified  user after the following steps are taken: (1)	the configura-
       tion file (if any) is loaded; (2) if the	KeyFile	(-k) setting is	 used,
       that  key is loaded into	memory;	(3) all	data sets in the configuration
       file are	opened,	and those that are based on flat files are  also  read
       into memory; and	(4) if ChangeRootDirectory is set, the process root is
       changed to that directory.  This	means  on  configuration  reload,  the
       filter  will  not be accessing these files or the configuration file as
       the superuser (and possibly from	a different root), and any  key	 files
       referenced by the KeyTable will also be accessed	by the new user.

       Thus,  keys  referenced	by  the	KeyTable must always be	accessible for
       read by the unprivileged	user.  Also, run-time reloads are not possible
       if  any	of  the	 other	files will not be readable by the unprivileged

       The following environment variable(s) can be used to adjust the	behav-
       iour of this filter:

	      The directory to use when	creating temporary files.  The default
	      is /tmp.

       When using DNS timeouts (see the	-T option above), be sure not to use a
       timeout	that is	larger than the	timeout	being used for interaction be-
       tween sendmail and the filter.  Otherwise, the MTA could	abort  a  mes-
       sage  while waiting for a reply from the	filter,	which in turn is still
       waiting for a DNS reply.

       The POP authentication database is expected to be a Sleepycat  DB  file
       (formerly  known	 as a Berkeley DB) in hash format with keys containing
       the IP address in text form without a terminating NULL.	The values  of
       these records are not checked; only the existence of such records is of
       interest.  The filter will attempt to establish a shared	 lock  on  the
       database	 before	 reading  from	it, so any programs which write	to the
       database	should keep their lock use to a	minimum	or  else  this	filter
       will appear to hang while waiting for the lock operation	to complete.

       Features	 that  involve	specification of IPv4 addresses	or CIDR	blocks
       will use	the inet_addr(3) function to parse  that  information.	 Users
       should  be  familiar with the way that function handles the non-trivial
       cases (for example, "192.0.2/24"	and "" are	not  the  same

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

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

       This man	page covers version 2.10.3 of opendkim.

       Copyright (c) 2005-2008,	Sendmail, Inc. and its suppliers.  All	rights

       Copyright  (c) 2009-2013, 2015, The Trusted Domain Project.  All	rights

       opendkim.conf(5), sendmail(8)

       Sendmail	Operations Guide

       RFC5321 - Simple	Mail Transfer Protocol

       RFC5322 - Internet Messages

       RFC5451 - Message Header	Field for  Indicating  Message	Authentication

       RFC6008 - Authentication-Results	Registration for Differentiating among
       Cryptographic Results

       RFC6376 - DomainKeys Identified Mail

			  The Trusted Domain Project		   opendkim(8)


Want to link to this manual page? Use this URL:

home | help