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

FreeBSD Manual Pages

  
 
  

home | help
opendkim.conf(5)	      File Formats Manual	      opendkim.conf(5)

NAME
       opendkim.conf - Configuration file for opendkim

LOCATION
       /usr/local/etc/opendkim.conf

DESCRIPTION
       opendkim(8) implements the DKIM specification for signing and verifying
       e-mail messages on a per-domain basis.  This file is its	 configuration
       file.

       Blank  lines  are ignored.  Lines containing a hash ("#") character are
       truncated at the	hash character to allow	for comments in	the file.

       Other content should be the name	of  a  parameter,  followed  by	 white
       space,  followed	 by  the  value	 of that parameter, each on a separate
       line.

       For parameters that are Boolean in nature, only the first byte  of  the
       value  is  processed.  For positive values, the following are accepted:
       "T", "t", "Y", "y", "1".	 For negative values, the  following  are  ac-
       cepted: "F", "f", "N", "n", "0".

       Many,  but  not	all, of	these parameters are also available as command
       line options to opendkim(8).  However, new parameters are generally not
       added  as command line options so the complete set of options is	avail-
       able here, and thus use of the configuration file  is  encouraged.   In
       some  future  release,  the  set	 of  available command line options is
       likely to get trimmed.

       See the opendkim(8) man page for	details	about how and when the config-
       uration file contents are reloaded.

       Some of these parameters	are listed as having a type of "dataset".  See
       the opendkim(8) man page	for a description of such parameters.

       Unless otherwise	stated,	Boolean	values	default	 to  "false",  integer
       values default to 0, and	string and dataset values default to being un-
       defined.

PARAMETERS
       AllowSHA1Only (Boolean)
	      Permit verify mode when only SHA1	support	is available.  RFC6376
	      requires	that verifiers implement both SHA1 and SHA256 support.
	      Setting this feature changes the absence of SHA256 support  from
	      an error to a warning.

       AlwaysAddARHeader (Boolean)
	      Add  an  "Authentication-Results:" header	field even to unsigned
	      messages from domains with no "signs all"	policy.	 The  reported
	      DKIM  result  will  be  "none" in	such cases.  Normally unsigned
	      mail from	non-strict domains does	not cause the  results	header
	      field to be added.

       AuthservID (string)
	      Sets  the	 "authserv-id"	to use when generating the Authentica-
	      tion-Results: header field after verifying a message.   The  de-
	      fault  is	to use the name	of the MTA processing the message.  If
	      the string "HOSTNAME" is provided, the name of the host  running
	      the  filter (as returned by the gethostname(3) function) will be
	      used.

       AuthservIDWithJobID (Boolean)
	      If "true", requests that the authserv-id portion	of  the	 added
	      Authentication-Results:  header fields contain the job ID	of the
	      message being evaluated.

       AutoRestart (Boolean)
	      Automatically re-start on	failures.  Use with  caution;  if  the
	      filter  fails  instantly after it	starts,	this can cause a tight
	      fork(2) loop.

       AutoRestartCount	(integer)
	      Sets the maximum automatic restart count.	 After this number  of
	      automatic	 restarts,  the	 filter	will give up and terminate.  A
	      value of 0 implies no limit; this	is the default.

       AutoRestartRate (string)
	      Sets the maximum automatic restart rate.	If the	filter	begins
	      restarting  faster  than	the rate defined here, it will give up
	      and terminate.  This is a	string of the form n/t[u] where	 n  is
	      an  integer limiting the count of	restarts in the	given interval
	      and t[u] defines the time	interval through  which	 the  rate  is
	      calculated;  t is	an integer and u defines the units thus	repre-
	      sented ("s" or "S" for seconds, the default; "m" or "M" for min-
	      utes;  "h" or "H"	for hours; "d" or "D" for days).  For example,
	      a	value of "10/1h" limits	the restarts to	10 in one hour.	 There
	      is no default, meaning restart rate is not limited.

       Background (Boolean)
	      Causes  opendkim to fork and exits immediately, leaving the ser-
	      vice running in the background.  The default is "true".

       BaseDirectory (string)
	      If set, instructs	the filter to change to	the  specified	direc-
	      tory  using chdir(2) before doing	anything else.	This means any
	      files referenced elsewhere in  the  configuration	 file  can  be
	      specified	 relative to this directory.  It's also	useful for ar-
	      ranging that any crash dumps will	be saved to a  specific	 loca-
	      tion.

       BodyLengthDB (dataset)
	      Requests	that  opendkim include a "l=" body length tag when the
	      set contains any of the envelope recipient addresses.   The  ad-
	      dresses  presented  are  tested  against the database in various
	      forms as described under the SigningTable	setting	(below).  This
	      feature  of the protocol exists to improve the likelihood	that a
	      signature	will survive transit through a mailing list server, as
	      they  commonly  append footers to	messages.  Note, however, that
	      this creates a potential security	issue since someone could  add
	      arbitrary	 text  to  the	signed message and the signature would
	      still validate.  See the DKIM specification for details.

       BogusKey	(string)
	      Instructs	the filter to treat  a	passing	 signature  associated
	      with a bogus (forged) key	in a special way.  Possible values are
	      neutral (return a	"neutral" result), none	(take no  special  ac-
	      tion) and	fail (return a "fail" result; this is the default).

       CaptureUnknownErrors (Boolean)
	      When  set, and on	systems	where MTA quarantine is	available, the
	      filter will request quarantine of	a message that results	in  an
	      internal error or	resource exhaustion.

       Canonicalization	(string)
	      Selects  the  canonicalization method(s) to be used when signing
	      messages.	 When verifying, the message's DKIM-Signature:	header
	      field  specifies	the  canonicalization  method.	The recognized
	      values are relaxed and simple as defined by the DKIM  specifica-
	      tion.  The default is simple.  The value may include two differ-
	      ent canonicalizations separated by a slash ("/")	character,  in
	      which  case the first will be applied to the header and the sec-
	      ond to the body.

       ChangeRootDirectory (string)
	      Requests that the	operating system change	the effective root di-
	      rectory of the process to	the one	specified here prior to	begin-
	      ning execution.  chroot(2) requires superuser access. A  warning
	      will be generated	if UserID is not also set.

       ClockDrift (integer)
	      Sets  the	 tolerance  in	seconds	to be applied when determining
	      whether a	signature was either expired or	generated in  the  fu-
	      ture.  The default is 300.

       Diagnostics (Boolean)
	      Requests	the inclusion of "z=" tags in signatures, which	encode
	      the original header field	set for	use by verifiers when diagnos-
	      ing  verification	 failures.   Not recommended for normal	opera-
	      tion.

       DiagnosticDirectory (string)
	      Directory	into which to write diagnostic	reports	 when  message
	      verification  fails on a message bearing a "z=" tag.  If not set
	      (the default), these files are not generated.

       DisableCryptoInit (Boolean)
	      If set, skips initialization of the SSL  library	initialization
	      steps,  which  are  normaly  required in multi-threaded environ-
	      ments.  This assumes some	other library opendkim is  using  will
	      do the required initialization and shutdown.

       DNSConnect (Boolean)
	      Requests	that the asynchronous resolver start using TCP immedi-
	      ately rather than	using UDP until	TCP is actually	needed.	  Does
	      not work with all	resolvers.

       DNSTimeout (integer)
	      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.

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

	      This  parameter  is not required if a SigningTable is in use; in
	      that case, the list of signed domains is implied by the lines in
	      that file.

	      This parameter is	ignored	if a KeyTable is defined.

       DomainKeysCompat	(boolean)
	      If  set,	backward  compatibility	 with DomainKeys (RFC4870) key
	      records is enabled.  When	not set, such keys are	considered  to
	      be syntactically invalid.	 The default is	"false".

       DontSignMailTo (dataset)
	      A	set of e-mail address, mail to which should never be signed by
	      the filter.  Note	that this is an	"any" feature; if any  one  of
	      the recipients of	the message matches a member of	this list, the
	      message will not be signed.

       EnableCoredumps (boolean)
	      On systems that have such	support, make an explicit  request  to
	      the  kernel  to dump cores when the filter crashes for some rea-
	      son.  Some  modern  UNIX	systems	 suppress  core	 dumps	during
	      crashes  for  security reasons if	the user ID has	changed	during
	      the lifetime of the process.  Currently only supported on	Linux.

       ExemptDomains (dataset)
	      Specifies	a set of domains, mail from which  should  be  ignored
	      entirely by the filter.  This is similar to the PeerList setting
	      except that it bases its decision	on the sender of  the  message
	      as  identified from the header fields or other message data, not
	      the identity of the SMTP client sending the message.

       ExternalIgnoreList (dataset)
	      Identifies a set of "external" hosts that	may send mail  through
	      the  server as one of the	signing	domains	without	credentials as
	      such.  This has the effect of  suppressing  the  "external  host
	      (hostname)  tried	 to  send mail as (domain)" log	messages.  En-
	      tries in the data	set should be of the same form as those	of the
	      PeerList option below.  The set is empty by default.

       FinalPolicyScript (string)
	      Gives  the name of a Lua script that should be run after the en-
	      tire message has been received.  This can	be used	to enact local
	      policy  decisions	such as	message	rejection, quarantine, rerout-
	      ing, etc.	based on signatures found on the message, the  results
	      of  attempts to verify them, and other properties	of the message
	      or signatures.  See opendkim-lua(3) for details.

       FixCRLF (Boolean)
	      Requests that the	DKIM library convert bare CRs and LFs to CRLFs
	      during body canonicalization, anticipating that an MTA somewhere
	      before delivery will do that conversion anyway.  The default  is
	      to leave them as-is.

       IdentityHeader (string)
	      This  specifies  the  header  field where	an identity is stored.
	      (Experimental feature not	enabled	for this installation.)

       IdentityHeaderRemove (Boolean)
	      Remove the IdentityHeader	after signing.	(Experimental  feature
	      not enabled for this installation.)

       IgnoreMalformedMail (boolean)
	      Silently passes malformed	messages without alteration.  This in-
	      cludes messages that fail	the RequiredHeaders check, if enabled.
	      The default is to	pass those messages but	add an Authentication-
	      Results field indicating that they were malformed.

       Include (string)
	      Names a file to be opened	and read as an	additional  configura-
	      tion file.  Nesting is allowed to	a maximum of five levels.

       InternalHosts (dataset)
	      Identifies  a  set  internal  hosts  whose mail should be	signed
	      rather than verified.  Entries in	this data set follow the  same
	      form  as	those of the PeerList option below.  If	not specified,
	      the default of "127.0.0.1" is applied.  Naturally,  providing  a
	      value  here  overrides  the  default,  so	if mail	from 127.0.0.1
	      should be	signed,	the list provided here should include that ad-
	      dress explicitly.

       KeepAuthResults (boolean)
	      Suppresses  removal of Authentication-Results header fields con-
	      taining DKIM results apparently added by	this  filter  (usually
	      the result of a misconfiguration or a forgery).

       KeepTemporaryFiles (boolean)
	      Instructs	 the  filter  to create	temporary files	containing the
	      header and body canonicalizations	of messages that are signed or
	      verified.	 The location of these files can be set	using the Tem-
	      poraryDirectory parameter.  Intended only	for debugging  verifi-
	      cation problems.

       KeyFile (string)
	      Gives the	location of a PEM-formatted private key	to be used for
	      signing all messages.  Ignored if	a KeyTable is defined.

       KeyTable	(dataset)
	      Gives the	location of a file mapping key names to	signing	 keys.
	      If  present,  overrides any KeyFile setting in the configuration
	      file.  The data set named	here maps each key name	to three  val-
	      ues:  (a)	 the name of the domain	to use in the signature's "d="
	      value; (b) the name of the selector to use  in  the  signature's
	      "s="  value;  and	 (c)  either a private key or a	path to	a file
	      containing a private key.	 If the	first value consists solely of
	      a	 percent  sign ("%") character,	it will	be replaced by the ap-
	      parent domain of the sender when generating a signature.	If the
	      third  value  starts  with  a  slash ("/") character, or "./" or
	      "../", then it is	presumed to refer to a	file  from  which  the
	      private key should be read, otherwise it is itself a PEM-encoded
	      private key or a base64-encoded DER private key; a  "%"  in  the
	      third value in this case will be replaced	by the apparent	domain
	      name of the sender.  The SigningTable (see below)	is used	to se-
	      lect  records from this table to be used to add signatures based
	      on the message sender.

       LDAPAuthMechanism (string)
	      Names the	authentication mechanism to use	when connecting	to  an
	      LDAP  server.  The default is the	empty string, meaning "simple"
	      authentication should be done.

       LDAPAuthName (string)
	      Specifies	the authenticating name	to use when using SASL to  au-
	      thenticate  to  an  LDAP	server.	  Requires SASL	support	be in-
	      stalled on the local system.  There is no	default.

       LDAPAuthRealm (string)
	      Specifies	the authentication realm to use	when using SASL	to au-
	      thenticate  to  an  LDAP	server.	  Requires SASL	support	be in-
	      stalled on the local system.  There is no	default.

       LDAPAuthUser (string)
	      Specifies	the authenticating user	to use when using SASL to  au-
	      thenticate  to  an  LDAP	server.	  Requires SASL	support	be in-
	      stalled on the local system.  There is no	default.

       LDAPBindPassword	(string)
	      Specifies	the password to	use when conducting an LDAP "bind" op-
	      eration.	There is no default.

       LDAPBindUser (string)
	      Specifies	 the user ID to	use when conducting an LDAP "bind" op-
	      eration.	There is no default.

       LDAPDisableCache	(Boolean)
	      Suppresses creation of a local cache in front of LDAP queries.

       LDAPKeepaliveIdle (integer)
	      Sets the number of seconds a connection to an LDAP server	 needs
	      to  remain  idle before TCP starts sending keepalive probes.  If
	      not specified, the LDAP library default is used.

       LDAPKeepaliveInterval (integer)
	      Sets the interval	in seconds between TCP keepalive  probes.   If
	      not specified, the LDAP library default is used.

       LDAPKeepaliveProbes (integer)
	      Sets  the	maximum	number of keepalive probes TCP should send be-
	      fore abandoning the connection.  If not specified, the LDAP  li-
	      brary default is used.

       LDAPTimeout (integer)
	      Sets the time in seconds after which an LDAP operation should be
	      abandoned.  The default is 5.

       LDAPUseTLS (Boolean)
	      Indicates	whether	or not a TLS connection	should be  established
	      when contacting an LDAP server.  The default is "False".

       LogResults (boolean)
	      If  logging is enabled (see Syslog below), requests that the re-
	      sults of evaluation of all signatures that were at least	partly
	      intact (i.e., the	"d=", "s=", and	"b=" tags could	be extracted).

       LogWhy (boolean)
	      If  logging  is enabled (see Syslog below), issues very detailed
	      logging about the	logic behind the filter's decision  to	either
	      sign  a  message or verify it.  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 OPERATIONS section of	 the  opendkim(8)  man
	      page.   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.

       MacroList (dataset)
	      Defines  a  set of MTA-provided macros that should be checked to
	      see if the sender	has been determined to be  a  local  user  and
	      therefore	 whether  or  not  the message should be signed.  If a
	      value is specified matching a macro name in the  data  set,  the
	      value  of	 the  macro  must match	a value	specified (matching is
	      case-sensitive), otherwise the macro must	 be  defined  but  may
	      contain  any value.  The set is empty by default,	meaning	macros
	      are not considered when making the  sign-verify  decision.   The
	      general  format of the value is value1[|value2[|...]]; if	one or
	      more value is defined then the macro must	be set to one  of  the
	      listed  values,  otherwise the macro must	be set but can contain
	      any value.

	      In order for the macro and its value to be available to the fil-
	      ter  for	checking, the MTA must send it during the protocol ex-
	      change.  This is either accomplished via manual configuration of
	      the  MTA	to send	the desired macros or, for MTA/filter combina-
	      tions that support the feature, the  filter  can	request	 those
	      macros that are of interest.  The	latter is a feature negotiated
	      at the time the filter receives a	connection from	 the  MTA  and
	      its availability depends upon the	version	of milter used to com-
	      pile the filter and the version of the MTA  making  the  connec-
	      tion.

	      This data	set must be of type "file" or "csl".

       MaximumHeaders (integer)
	      Defines  the  maximum number of bytes the	header block of	a mes-
	      sage may consume before the  filter  will	 reject	 the  message.
	      This mitigates a denial-of-service attack	in which a client con-
	      nects to the MTA and  begins  feeding  an	 unbounded  number  of
	      header  fields of	arbitrary size;	since the filter keeps a cache
	      of these,	the attacker could cause the filter to allocate	an un-
	      specified	 amount	of memory.  The	default	is 65536; a value of 0
	      removes the limit.

       MaximumSignaturesToVerify (integer)
	      Defines the maximum number of signatures on a message for	 which
	      verification should be conducted.	 The default is	three.	Signa-
	      tures are	selected from the top of  the  message	downward.   If
	      TrustSignaturesFrom is set, signatures from domains in that data
	      set are always verified, which may consume part or  all  of,  or
	      even exceed, this	limit.

       MaximumSignedBytes (integer)
	      Specifies	 the  maximum  number  of  bytes of message body to be
	      signed.  Messages	shorter	than this  limit  will	be  signed  in
	      their  entirety.	Setting	this value implies use of BodyLengthDB
	      for all addresses.

       MilterDebug (integer)
	      Sets the debug level to be requested from	 the  milter  library.
	      The default is 0.

       Minimum (string)
	      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.

       MinimumKeyBits (integer)
	      Establishes a minimum key	size for acceptable signatures.	  Sig-
	      natures with smaller key sizes, even if they otherwise pass DKIM
	      validation, will me marked as invalid.   The  default  is	 1024,
	      which  accepts  all signatures.  A value of 0 causes the default
	      to be used.

       Mode (string)
	      Selects operating	modes.	The string is a	concatenation of char-
	      acters  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 the opendkim(8) man page) in which case
	      the default is v.	 When signing mode is enabled, one of the fol-
	      lowing  combinations  must also be set: (a) Domain, KeyFile, Se-
	      lector,  no  KeyTable,  no  SigningTable;	 (b)  KeyTable,	 Sign-
	      ingTable,	 no Domain, no KeyFile,	no Selector; (c) KeyTable, Se-
	      tupPolicyScript, no Domain, no KeyFile, no Selector.

       MTA (dataset)
	      A	set of MTA names (a la the sendmail(8) DaemonPortOptions  Name
	      parameter) whose mail should be signed by	this filter.  There is
	      no default, meaning MTA name is not considered when  making  the
	      sign-verify decision.

       MTACommand (string)
	      Specifies	 the path to an	executable to be used for sending mail
	      such  as	that  generated	 by  SendReports.   The	  default   is
	      /usr/sbin/sendmail.   The	executable should accept typical send-
	      mail(8) command line options "-t"	(take addresses	 from  message
	      body)  and "-f" (set envelope sender), accept the	new message on
	      its standard input, and return a non-zero	exit status on any er-
	      ror.

       MultipleSignatures (Boolean)
	      Allow addition of	multiple signatures when a signing table is in
	      use.  See	SigningTable for more information.

       MustBeSigned (dataset)
	      Specifies	a set of header	fields that, if	present, must be  cov-
	      ered  by	the  DKIM  signature  when  verifying a	message.  If a
	      header field in this set is present in the message  and  is  not
	      signed,  the filter will treat even an otherwise valid signature
	      as invalid.  The default is an empty list.

       Nameservers (string)
	      Provides a comma-separated list of IP addresses that are	to  be
	      used  when doing DNS queries to retrieve DKIM keys, VBR records,
	      etc.  These override any local defaults built in to the resolver
	      in  use,	which may be defined in	/etc/resolv.conf or hard-coded
	      into the software.

       NoHeaderB (Boolean)
	      If set, this feature suppresses the use of  "header.b"  tags  in
	      added  Authentication-Results  header  fields.   The  default is
	      "false", which means those tags will be applied.

       OmitHeaders (dataset)
	      Specifies	a set of header	fields that  should  be	 omitted  when
	      generating signatures.  If an entry in the list names any	header
	      field that is mandated by	the DKIM specification,	the  entry  is
	      ignored.	 A set of header fields	is listed in the DKIM specifi-
	      cation (RFC6376, Section 5.4) as "SHOULD NOT" be signed; the de-
	      fault  list  for	this  parameter	contains those fields (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 header field names).  Specifying a
	      list  with  this parameter replaces the default entirely,	unless
	      one entry	is "*" in which	case the  list	is  interpreted	 as  a
	      delta  to	the default; for example, "*,+foobar" will use the en-
	      tire default list	plus the name "foobar",	while  "*,-Bcc"	 would
	      use the entire default list except for the "Bcc" entry.

       On-BadSignature (string)
	      Selects  the  action to be taken when a signature	fails to vali-
	      date.  Possible values (with abbreviated forms in	 parentheses):
	      accept  (a) accept the message; discard (d) discard the message;
	      quarantine (q) quarantine	the message;  reject  (r)  reject  the
	      message; tempfail	(t) temp-fail the message.  The	default	is ac-
	      cept.  Note that the "t" (testing) flag in a DKIM	 key  bypasses
	      this  behaviour;	a bad signature	that references	a testing flag
	      will still be delivered, though the added	Authentication-Results
	      field  will indicate both	the failed result and the test mode so
	      that consumers of	the message can	take appropriate action.

       On-Default (string)
	      Selects the action to be taken when any verification or internal
	      error  of	any kind is encountered.  This is processed before the
	      other "On-" values so it can be used as a	blanket	 setting  fol-
	      lowed by specific	overrides.

       On-DNSError (string)
	      Selects the action to be taken when a transient DNS error	is en-
	      countered.  Possible values are the same as those	for On-BadSig-
	      nature.  The default is tempfail.

       On-InternalError	(string)
	      Selects  the  action  to be taken	when an	internal error of some
	      kind is encountered.  Possible values are	the same as those  for
	      On-BadSignature.	The default is tempfail.

       On-KeyNotFound (string)
	      Selects the action to be taken when the key referenced by	a sig-
	      nature is	not present in the DNS.	 Possible values are the  same
	      as those for On-BadSignature.  The default is accept.

       On-NoSignature (string)
	      Selects  the action to be	taken when a message arrives unsigned.
	      Possible values are the same as those for	On-BadSignature.   The
	      default is accept.

       On-Security (string)
	      Selects the action to be taken when a message arrives containing
	      properties that may be a security	concern.  Possible values  are
	      the same as those	for On-BadSignature.  The default is tempfail.

       On-SignatureError (string)
	      Selects  the  action to be taken when a message cannot be	signed
	      because of issues	with the message or the	key provided for sign-
	      ing.  Possible values are	the same as those for On-BadSignature.
	      The default is reject.

       OversignHeaders (dataset)
	      Specifies	a set of header	fields that should be included in  all
	      signature	 header	lists (the "h="	tag) once more than the	number
	      of times they were actually present in the signed	message.   The
	      set is empty by default.	The purpose of this, and especially of
	      listing an absent	header field, is to prevent  the  addition  of
	      important	fields between the signer and the verifier.  Since the
	      verifier would include that header field when performing verifi-
	      cation  if it had	been added by an intermediary, the signed mes-
	      sage and the verified message were different and	the  verifica-
	      tion  would  fail.   Note	that listing a field name here and not
	      listing it in the	SignHeaders list is likely to generate invalid
	      signatures.

       PeerList	(dataset)
	      Identifies  a  set of "peers" that identifies clients whose con-
	      nections should be accepted without processing by	 this  filter.
	      The  set	should	contain	 on  each line a hostname, domain name
	      (e.g. ".example.com"), IP	address, an IPv6 address (including an
	      IPv4  mapped  address),  or  a CIDR-style	IP specification (e.g.
	      "192.168.1.0/24").  An entry beginning with a bang ("!") charac-
	      ter  means "not",	allowing exclusions of specific	hosts that are
	      otherwise	members	of larger sets.	 Host  and  domain  names  are
	      matched first, then the IP or IPv6 address depending on the con-
	      nection type.  More precise entries are preferred	over less pre-
	      cise    ones,    i.e.	"192.168.1.1"	 will	match	before
	      "!192.168.1.0/24".  The text form	 of  IPv6  addresses  will  be
	      forced  to  lowercase when queried (RFC5952), so the contents of
	      this data	set should also	use lowercase.	The IP address portion
	      of  an  entry may	optionally contain square brackets; both forms
	      (with and	without) will be checked.

       PidFile (string)
	      Specifies	the path to a file that	should be created  at  process
	      start containing the process ID.

       POPDBFile (dataset)
	      Requests	that  the  filter  consult a set for IP	addresses that
	      should be	allowed	for signing. This  feature  was	 designed  for
	      POP-before-SMTP  datastores.   (Not  enabled  for	this installa-
	      tion.)

       Quarantine (Boolean)
	      Requests that messages which fail	verification be	quarantined by
	      the  MTA.	 (Requires a sufficiently recent version of the	milter
	      library.)

       QueryCache (Boolean)
	      Instructs	the DKIM library to maintain its own  local  cache  of
	      keys and policies	retrieved from DNS, rather than	relying	on the
	      nameserver for caching service.  Useful if the nameserver	 being
	      used  by the filter is not local.	 (Not enabled for this instal-
	      lation.)

       RedirectFailuresTo (address)
	      Messages bearing signatures that failed to verify	are redirected
	      to  the  specified address.  The original	envelope recipient set
	      is recorded in the header	before	redirection  occurs.   By  de-
	      fault, no	redirection is done.

       RemoveARAll (Boolean)
	      Removes all Authentication-Results: header fields	that also sat-
	      isfy the requirements of RemoveARFrom below.  By	default,  only
	      those containing a DKIM result are removed.

       RemoveARFrom (dataset)
	      Defines  a set of	hostnames whose	Authentication-Results:	header
	      fields should be removed before the message is passed for	deliv-
	      ery.   By	 default  only	those header fields matching the local
	      host's canonical name will be removed.  Matching is only done on
	      full  hostnames  (e.g.  "host.example.com")  or  on domain names
	      (e.g. ".example.com").

       RemoveOldSignatures (Boolean)
	      Removes all existing signatures when operating in	signing	mode.

       ReplaceHeaders (data set)
	      Defines a	set of header fields that should be  affected  by  the
	      text  replacement	rules defined by the ReplaceRules setting.  By
	      default, all header fields are included.	(Experimental  feature
	      not enabled for this installation.)

       ReplaceRules (string)
	      Specifies	 a  file  containing  a	list of	text replacement rules
	      that are applied to the message header fields to replace certain
	      content expected to be changed as	the message passes through lo-
	      cal MTAs.	 This can be used to accommodate expected changes such
	      as  are made to From: fields by MTA "masquerade" features.  Each
	      entry in the file	consists of a POSIX regular  expression,  fol-
	      lowed  by	 a  tab	(ASCII 9), followed by the text	that should be
	      used to replace the text matching	the expression.	 The '#' char-
	      acter  denotes  the  beginning  of  a comment and	text from that
	      point on in a single line	is  ignored.   Blank  lines  are  also
	      skipped.	 (Experimental	feature	not enabled for	this installa-
	      tion.)

       ReportAddress (string)
	      Specifies	the string to use in the From: header field for	outgo-
	      ing reports (see SendReports below).  If not specified, the exe-
	      cuting user and local hostname will be used to construct the ad-
	      dress.

       ReportBccAddress	(string)
	      Specifies	 address(es) to	include	in a Bcc: header field on out-
	      going reports (see SendReports below). If	multiple addresses are
	      required,	they should be comma separated.

       RequestReports (boolean)
	      When  signing, includes a	request	for signature evaluation fail-
	      ures in the signature.  (See RFC6651 for details.)

       RequiredHeaders (boolean)
	      Checks all messages for compliance  with	RFC5322	 header	 field
	      count requirements.  Non-compliant messages are rejected.

       RequireSafeKeys (boolean)
	      When  reading  a	key  file, a message will be logged if the key
	      file has the read	or write bit set other than for	the  owner  or
	      for a group that the executing process is	in.  With this feature
	      set to "true", the filter	will further consider  this  an	 error
	      and  refuse  to make use of the file's contents.	The default is
	      "true".

       ResignAll (boolean)
	      Where ResignMailTo triggers a re-signing action, this flag indi-
	      cates  whether  or not all mail should be	signed (if set)	versus
	      only verified mail being signed (if not set).   The  default  is
	      "false".	 (Experimental	feature	not enabled for	this installa-
	      tion.)

       ResignMailTo (dataset)
	      Checks each message recipient against the	specified dataset  for
	      a	 matching  record.   The full address is checked in each case,
	      then the hostname, then each domain preceded by ".".   If	 there
	      is  a  match, the	value returned is presumed to be the name of a
	      key in the KeyTable (if defined) to be used to re-sign the  mes-
	      sage in addition to verifying it.	 If there is a match without a
	      KeyTable,	the default key	is applied.  (Experimental feature not
	      enabled for this installation.)

       ResolverConfiguration (string)
	      Provides	the  given  string as configuration information	to the
	      underlying resolver.  For	the standard UNIX  resolver,  this  is
	      unused; for Unbound, the string contains a filename that is con-
	      sidered to be a configuration file.  There is no default.

       ResolverTracing (Boolean)
	      Requests resolver	tracing	features  be  enabled,	if  available.
	      The  effect of this depends on how debugging features of the re-
	      solver might be implemented.  Currently only effective with  the
	      OpenDKIM asynchronous resolver library.

       ScreenPolicyScript (string)
	      Gives  the  name of a Lua	script that should be run after	all of
	      the header fields	have been processed for	a message; in particu-
	      lar, this	is useful after	all DKIM signatures have been detected
	      and initial evaluation has been done.  The script	has access  to
	      all of the header	fields and connection information and can that
	      certain signatures be ignored based on  that  information.   See
	      opendkim-lua(3) for details.

       SelectCanonicalizationHeader (string)
	      Defines  a  header  field	 name which, if	present, adjusts which
	      canonicalization will be used to generate	an outgoing signature.
	      Overrides	 the  Canonicalization	setting	if the header field is
	      present.	The default is "X-Canonicalization".

       Selector	(string)
	      Defines the name of the selector to be used  when	 signing  mes-
	      sages.   See the DKIM specification for details.	Used only when
	      signing with a single key; see the SigningTable parameter	 below
	      for more information.

	      This parameter is	ignored	if a KeyTable is defined.

       SenderHeaders (dataset)
	      Specifies	 an  ordered  list  of	header	fields	that should be
	      searched to determine the	sender of a message.  The first	header
	      field found is the one whose value is used.  This	is mainly used
	      when signing for deciding	which signing request(s) to make.   By
	      default,	the  "From" header field is the	only one checked.  See
	      the OmitHeaders setting for a description	of possible values.

       SenderMacro (string)
	      Use the milter macro string to determine the sender of the  mes-
	      sage.  (Experimental feature not enabled for this	installation.)

       SendReports (Boolean)
	      If  true,	 when a	signature verification fails and the signature
	      included a reporting request ("r=y") and the signing domain  ad-
	      vertises	a  reporting  address  (i.e.   ra=user)	in a reporting
	      record in	the DNS, the filter will send a	structured  report  to
	      that address containing details needed to	reproduce the problem.
	      See RFC6651 for a	complete description of	this mechanism.

       SetupPolicyScript (string)
	      Gives the	name of	a Lua script  that  should  be	run  once  all
	      header fields for	a message have arrived.	 The script has	access
	      to all of	the header fields and connection information  and  can
	      request  DKIM verification or signing based on that information.
	      See opendkim-lua(3) for details.

       SignatureAlgorithm (string)
	      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
	      rsa-sha1.

       SignatureTTL (integer)
	      Sets  the	 time-to-live,	in seconds, of signatures generated by
	      the filter.  If not set, no expiration time is added  to	signa-
	      tures.

       SignHeaders (dataset)
	      Specifies	 the set of header fields that should be included when
	      generating signatures.  If the list omits	any header field  that
	      is  mandated by the DKIM specification, those fields are implic-
	      itly added.  By default, those fields listed in the DKIM	speci-
	      fication	as  "SHOULD"  be signed	(RFC6376, Section 5.4) will be
	      signed by	the filter.  See the OmitHeaders configuration	option
	      for more information about the format and	interpretation of this
	      field.

       SigningTable (dataset)
	      Defines a	table used to select one or more signatures  to	 apply
	      to  a  message  based  on	 the address found in the From:	header
	      field.  Keys in this table vary depending	on the type  of	 table
	      used; values in this data	set should include one field that con-
	      tains a name found in the	KeyTable (see above)  that  identifies
	      which key	should be used in generating the signature, and	an op-
	      tional second field naming the signer of the message  that  will
	      be  included  in	the "i=" tag in	the generated signature.  Note
	      that the "i=" value will not be included in the signature	if  it
	      conflicts	with the signing domain	(the "d=" value).

	      If the first field contains only a "%" character,	it will	be re-
	      placed by	the domain found in the	 From:	header	field.	 Simi-
	      larly,  within the optional second field,	any "%"	character will
	      be replaced by the domain	found in the From: header field.

	      If this table specifies a	regular	 expression  file  ("refile"),
	      then the keys are	wildcard patterns that are matched against the
	      address found in the From: header	field.	Entries	are checked in
	      the order	in which they appear in	the file.

	      For  all	other  database	 types,	 the full user@host is checked
	      first, then simply host, then user@.domain  (with	 all  superdo-
	      mains  checked  in  sequence,  so	 "foo.example.com" would first
	      check  "user@foo.example.com",  then  "user@.example.com",  then
	      "user@.com"), then .domain, then user@*, and finally *.

	      In  any case, only the first match is applied, unless MultipleS-
	      ignatures	is enabled in which case all matches are applied.

       SMTPURI (string)
	      Specifies	a URI (e.g., "smtp://localhost") to which mail	should
	      be sent via SMTP when notifications are generated.  (Not enabled
	      for this installation.)

       Socket (string)
	      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 and in the	specified 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.   This  option  is
	      mandatory	 either	 in  the  configuration	file or	on the command
	      line.

       SoftStart (Boolean)
	      If set, the inability to connect and authenticate	to an LDAP  or
	      SQL server will not prevent the filter from starting, and	recon-
	      nections will be attempted  for  each  query.   The  default  is
	      "False".

       SoftwareHeader (Boolean)
	      Causes  opendkim to add an "DKIM-Filter" header field indicating
	      the presence of this filter in the path of the message from  in-
	      jection  to  delivery.  The product's name, version, and the job
	      ID are included in the header field's contents.  Note  that  the
	      header field is not added	if the Mode setting causes the message
	      to be ignored (e.g., if only signing mode	 is  enabled  and  the
	      configuration  causes the	message	not to be signed, or only ver-
	      ify mode is  enabled  and	 configuration	would  otherwise  have
	      caused  the  message  to	be  signed, then it will not have this
	      header field added).

       Statistics (filename)
	      This specifies a file in which to	store DKIM transaction statis-
	      tics.  See opendkim-stats(8) for a mechanism to parse the	file's
	      contents,	and opendkim-importstats() for a mechanism  to	trans-
	      late the file's contents into SQL	database insertions.  (Experi-
	      mental feature not enabled for this installation.)

       StatisticsName (string)
	      Defines the name to be used as the reporting host	in  statistics
	      logs.   By  default,  the	local host's name returned by gethost-
	      name(3) is used.	(Experimental feature not enabled for this in-
	      stallation.)

       StatisticsPrefix	(string)
	      When  AnonymousStatistics	 is enabled, this string may be	speci-
	      fied and will be prepended to all	data before hashing  for  more
	      complete	anonymization.	 This means two	records	from different
	      sources referencing the same source will still produce different
	      hashes, meaning such correlation is now only possible within the
	      data from	a single repoter.

       StrictHeaders (Boolean)
	      If set, instructs	the DKIM library to  refuse  processing	 of  a
	      message  if  the	header field count does	not conform to RFC5322
	      Section 3.6.

       StrictTestMode (Boolean)
	      Selects strict CRLF mode during testing (see the -t command line
	      flag in the opendkim(8) man page); messages for which all	header
	      fields and body lines are	 not  CRLF-terminated  are  considered
	      malformed	and will produce an error.

       SubDomains (Boolean)
	      Sign  subdomains of those	listed by the Domain parameter as well
	      as the actual domains.

       Syslog (Boolean)
	      Log via calls to syslog(3) any interesting activity.

       SyslogFacility (string)
	      Log via calls to syslog(3) using the named facility.  The	facil-
	      ity  names  are  the same	as the ones allowed in syslog.conf(5).
	      The default is "mail".

       SyslogSuccess (Boolean)
	      Log via calls to syslog(3) additional  entries  indicating  suc-
	      cessful signing or verification of messages.

       TemporaryDirectory (string)
	      Specifies	 the  directory	 in  which  temporary canonicalization
	      files should be written.	The default is to use the libdkim  de-
	      fault location, currently	/tmp.

       TestDNSData (data set)
	      Provides	a  data	 set  whose keys will be treated as DNS	record
	      names and	values as TXT record contents.	Intended for use  dur-
	      ing automated testing.

       TestPublicKeys (string)
	      Names  a	file  from which public	keys should be read.  Intended
	      for use only during automated testing.

       TrustAnchorFile (string)
	      Specifies	a file from which trust	anchor	data  should  be  read
	      when  doing  DNS queries and applying the	DNSSEC protocol.  This
	      is currently ignored unless the underlying library  is  compiled
	      to  use  Unbound;	see the	documentation at at http://unbound.net
	      for the expected format of this file.

       TrustSignaturesFrom (dataset)
	      This value consists of a set  of	domains	 that  are  considered
	      trustworthy  in  terms of	third-party signatures.	 That is, if a
	      message arrives with a signature	from  a	 domain	 that  doesn't
	      match  the  domain  in the From: header, this setting determines
	      whether or not that signature will be trusted.  If this value is
	      undefined, all signatures	are trusted.

       UMask (integer)
	      Requests	a  specific  permissions mask to be used for file cre-
	      ation.  This only	really applies to creation of the socket  when
	      Socket  specifies	 a  UNIX domain	socket,	and to the PidFile (if
	      any); temporary files are	created	 by  the  mkstemp(3)  function
	      that enforces a specific file mode on creation regardless	of the
	      process umask.  See umask(2) for more information.

       UnprotectedKey (string)
	      Instructs	the filter to treat  a	passing	 signature  associated
	      with  a  key found in an insecure	(i.e. not protected by DNSSEC)
	      DNS record in a special way.  Possible values are	 neutral  (re-
	      turn  a "neutral"	result), none (take no special action; this is
	      the default) and fail (return a "fail" result).

       UserID (string)
	      Attempts to become the specified userid before  starting	opera-
	      tions.   The  value  is of the form userid[:group].  The process
	      will be assigned all of the groups and primary group ID  of  the
	      named userid unless an alternate group is	specified.

       VBR-Certifiers (string)
	      The  default  certifiers	if  not	 specified in X-VBR-Certifiers
	      header field.  (Experimental feature not enabled	for  this  in-
	      stallation.)

       VBR-PurgeFields (string)
	      If  set,	arranges  to  remove  X-VBR-Certifiers	and X-VBR-Type
	      fields on	messages prior to sending them.	 (Experimental feature
	      not enabled for this installation.)

       VBR-TrustedCertifiers (string)
	      A	 colon	or comma sparated list of trusted certifiers to	accept
	      when verifying VBR-Info header field.  (Experimental feature not
	      enabled for this installation.)

       VBR-TrustedCertifiersOnly (Boolean)
	      By  default,  the	certifiers that	are in both the	trusted	certi-
	      fiers list (above) and those in the  message's  VBR-Info	header
	      field  will  be checked for vouching.  With this option set, the
	      trusted certifiers will be checked and the ones claimed  by  the
	      message  will be ignored.	 (Experimental feature not enabled for
	      this installation.)

       VBR-Type	(string)
	      This default VBR type if not specified in	the X-VBR-Type	header
	      field.   (Experimental  feature  not  enabled for	this installa-
	      tion.)

       WeakSyntaxChecks	(Boolean)
	      Requests that the	library	continue processing messages  even  if
	      syntax  errors  are  discovered early in message analysis.  This
	      means, for example, that a signed	message	with a	mangled	 From:
	      field  will  still  proceed to verification even if the author's
	      domain could not be determined.

NOTES
       When using DNS timeouts (see the	DNSTimeout option above), be sure  not
       to  use a timeout that is larger	than the timeout being used for	inter-
       action between sendmail and the filter.	Otherwise, the MTA could abort
       a  message  while waiting for a reply from the filter, which in turn is
       still waiting for a DNS reply.

       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 "192.0.2.0/24" are not the same
       thing).

FILES
       /usr/local/etc/opendkim.conf
	      Default location of this file.

VERSION
       This man	page covers version 2.10.3 of opendkim.

COPYRIGHT
       Copyright (c) 2007, 2008, Sendmail, Inc.	and its	suppliers.  All	rights
       reserved.

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

SEE ALSO
       opendkim(8), opendkim-lua(3), sendmail(8)

       RFC5451 - Message Header	Field for  Indicating  Message	Authentication
       Status

       RFC5617 - DKIM Author Domain Signing Practises

       RFC5965 - An Extensible Format for Email	Feedback Reports

       RFC6008 - Authentication-Results	Registration for Differentiating among
       Cryptographic Results

       RFC6376 - DomainKeys Identified Mail

       RFC6651 - Extensions to DomainKeys Identified Mail (DKIM)  for  Failure
       Reporting

			  The Trusted Domain Project	      opendkim.conf(5)

NAME | LOCATION | DESCRIPTION | PARAMETERS | NOTES | FILES | VERSION | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=opendkim.conf&sektion=5&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help