Provided by: dkim-filter_2.6.0.dfsg-1ubuntu2_i386 bug

NAME

       dkim-filter.conf - Configuration file for dkim-filter

LOCATION

       /etc/mail/dkim-filter.conf

DESCRIPTION

       dkim-filter(8)  implements  the  DKIM  specification  for  signing  and
       verifying e-mail messages on a per-domain  basis.   This  file  is  its
       configuration file, read on startup only.

       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 which 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
       accepted: "F", "f", "N", "n", "0".

       Many,  but  not  all, of these parameters are also available as command
       line options to dkim-filter(8).  However, new parameters are  generally
       not  added  as  command  line options so the complete set of options is
       available 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 dkim-filter(8) man page for details  about  how  and  when  the
       configuration file contents are reloaded.

PARAMETERS

       AllowSHA1Only (Boolean)
              Permit verify mode when only SHA1 support is available.  RFC4871
              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  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
              to be added.

       AlwaysSignHeaders (string)
              Specifies a list of headers which  should  be  included  in  all
              signature  header  lists  (the  "h="  tag) even if they were not
              present at the time the signature  was  generated.   The  string
              should  be  a comma-separated list of header names.  The list is
              empty by default.  The purpose of listing an absent header is to
              prevent  its addition between the signer and the verifier, since
              the verifier would include that header if  it  were  added  when
              performing verification, which would mean the signed message and
              the verified message were different and the  verification  would
              fail.

       ASPDiscard (Boolean)
              If  "true",  requests rejection of messages which are determined
              to be suspicious according  to  the  author  domain’s  published
              signing  practises  (ASP)  record if that record also recommends
              discard of such messages.

       ASPNoSuchDomain (Boolean)
              If "true", requests rejection of messages which  are  determined
              to  be  from  nonexistent domains according to the author domain
              signing practises (ASP) test.

       AuthservIDWithJobID (Boolean)
              If "true", requests that the authserv-id portion  of  the  added
              Authentication-Results:  headers  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
              represented ("s" or "S" for seconds, the default; "m" or "M" for
              minutes;  "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)
              Normally dkim-filter forks and exits  immediately,  leaving  the
              service  running  in  the background.  This flag suppresses that
              behaviour so that it runs in the foreground.

       BodyLengths (Boolean)
              Requests that dkim-filter include the "l=" body length tag  when
              generating signatures.  This indicates to the verifier that only
              a certain amount of the original message  was  signed,  allowing
              tolerance  of  things  like  mailing  list managers which append
              list-specific  text  to  the  end  of  mailings  it   processes.
              However,  this  also  enables  an  abuse  attack.   See the DKIM
              specification for more information.

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

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

       Diagnostics (Boolean)
              Requests  the inclusion of "z=" tags in signatures, which encode
              the original header set for use  by  verifiers  when  diagnosing
              verification failures.  Not recommended for normal operation.

       DNSTimeout (integer)
              Sets  the  DNS  timeout  in  seconds.   A  value  of 0 causes an
              infinite wait.  The default is 5.   Ignored  if  not  using  the
              asynchronous  resolver  package.   See  also  the  NOTES section
              below.

       DontSignMailTo (string)
              A comma-separated list of e-mail addresses (with "*" allowed  as
              a  wildcard  character), 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.

       Domain (string)
              A comma-separated list of domains whose mail should be signed by
              this  filter.   Mail  from other domains will be verified rather
              than being signed.

              The value of this parameter may also be a  filename  from  which
              domain  names will be read.  The "#" character in such a file is
              assumed to indicate a comment.  An absolute path  must  be  used
              (i.e. the first character must be a "/").

              In  either  case,  the  domain  name(s)  may contain the special
              character "*" which is treated as a wildcard character  matching
              zero or more characters in a domain name.

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

       ExternalIgnoreList (string)
              Identifies  a  file  of  "external"  hosts  which  may send mail
              through the  server  as  one  of  the  signing  domains  without
              credentials  as  such.   Basically suppresses the "external host
              (hostname)  tried  to  send  mail  as  (domain)"  log  messages.
              Entries  in  the file should be of the same form as those of the
              PeerList option below.  The list is empty by default.

       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.

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

       InternalHosts (string)
              Identifies  a file of internal hosts whose mail should be signed
              rather than verified.  Entries in this file 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  address
              explicitly.

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

       KeyList (string)
              Gives the location of a file  listing  rules  for  signing  with
              multiple keys.  If present, overrides any KeyFile setting in the
              conifguration file.  The file named here should contain a set of
              lines  of  the  form sender-pattern:signing-domain:keypath where
              sender-pattern is a pattern to  match  against  message  senders
              (with  the  special  character  "*" interpreted as "zero or more
              characters"), signing-domain is the domain to  announce  as  the
              signing  domain  when  generating signatures, and keypath is the
              path to the PEM-formatted private key to  be  used  for  signing
              messages  which  match the sender-pattern.  The selector used in
              the signature will be the filename portion of keypath.   If  the
              file referenced by keypath cannot be opened, the filter will try
              again by appending ".pem" and then ".private" before giving  up.

       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 dkim-filter(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 (string)
              Defines  a set of MTA-provided macros which 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, 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.     The    general    format    of    the   string   is
              test1[,test2[,...]]    where   a   "test"   is   of   the   form
              macro[=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.

       MaximumHeaders (integer)
              Defines  the  maximum  number  of  bytes  the  header block of a
              message may consume before the filter will reject  the  message.
              This  mitigates  a  denial-of-service  attack  in which a client
              connects 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
              unspecified  amount of memory.  The default is 65536; a value of
              0 removes the 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  forces  BodyLengths  to  be
              "True".

       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
              formats: 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.

       Mode (string)
              Selects  operating  modes.   The  string  is  a concatenation of
              characters  which  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  dkim-filter(8)  man
              page) in which case the default is v.

       MTA (string)
              A  comma-separated  list  of  MTA  names  (a  la the sendmail(8)
              DaemonPortOptions Name parameter) whose mail should be signed by
              this filter.  There is no default.

       MustBeSigned (string)
              Specifies  a  list of headers which, if present, must be covered
              by the DKIM signature when  verifying  a  message.   The  string
              should  be  a comma-separated list of header names.  If a header
              in this list 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.

       OmitHeaders (string)
              Specifies a  list  of  headers  which  should  be  omitted  when
              generating  signatures.   The string should be a comma-separated
              list of header names.  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  which  will
              match  no  headers).   Note  that  specifying  a  list with this
              parameter replaces the default entirely.

       On-BadSignature (string)
              Selects the action  to  be  taken  when  a  signature  fails  to
              validate.    Possible   values   (with   abbreviated   forms  in
              parentheses): accept (a) accept the message; discard (d) discard
              the  message;  tempfail  (t)  temp-fail  the message; reject (r)
              reject the message.  The default is accept.

       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
              followed by specific overrides.

       On-DNSError (string)
              Selects  the  action  to  be taken when a transient DNS error is
              encountered.  Possible values are the  same  as  those  for  On-
              BadSignature.  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-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.

       PeerList (string)
              Identifies a file of  "peers"  which  identifies  clients  whose
              connections  should  be  accepted  without  processing  by  this
              filter.  The file 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 ("!")  character  means  "not",  allowing  exclusions  of
              specific  hosts  that are otherwise members of larger sets.  The
              order of entries in this file is therefore significant.

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

       POPDBFile (string)
              Requests  that  the filter consult a POP authentication database
              named in the string for IP addresses that should be allowed  for
              signing.   The  filter must be compiled with the POPAUTH flag to
              enable this feature, since it adds a library dependency.

       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.  The filter must be compiled
              with the QUERY_CACHE flag to enable this feature, since it  adds
              a library dependency.

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

       RemoveARFrom (string)
              Lists patterns of hostnames whose Authentication-Results: header
              fields should be  removed  before  the  message  is  passed  for
              delivery.   By  default  only  those  headers matching the local
              host’s canonical name will be removed.  If more than one pattern
              is  desired,  the  list  should be comma-separated.  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.

       ReportAddress (string)
              Specifies the string to  use  in  the  From:  header  field  for
              outgoing reports (see SendReports and SendASPReports below).  If
              not specified, the executing user and  local  hostname  will  be
              used to construct the address.

       Selector (string)
              Defines  the  name  of  the  selector  to  be  used when signing
              messages.  See the DKIM specification for  details.   Used  only
              when  signing with a single key; see the KeyList parameter above
              for more information.

       SendASPReports (Boolean)
              If true, when a policy evaluation fails  and  the  signing  site
              advertises  a  reporting  address  (i.e.   r=user  in its policy
              record) and a request for reports of such failures,  the  filter
              will send a structured report to that address containing details
              of the incident.

       SendReports (Boolean)
              If true, when a signature verification  fails  and  the  signing
              site  advertises a reporting address (i.e.  r=user in its policy
              record) and a request for reports of such failures,  the  filter
              will send a structured report to that address containing details
              needed to reproduce the problem.

       SignatureAlgorithm (string)
              Selects the signing algorithm to use when generating signatures.
              If  the  filter  was  compiled against version 0.9.8 or later of
              OpenSSL then both rsa-sha1 and rsa-sha256 are available and  the
              latter  is the default.  Otherwise, only the former is available
              and it is (obviously) the default.

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

       SignHeaders (string)
              Specifies the list of headers  which  should  be  included  when
              generating  signatures.   The string should be a comma-separated
              list of header names.  If the list omits  any  header  which  is
              mandated by the DKIM specification, those headers are implicitly
              added.   By  default,  those  headers   listed   in   the   DKIM
              specification  as  "SHOULD"  be  signed  will  be  signed by the
              filter.  Specifying a list here  replaces  that  list  entirely.
              See the OmitHeaders configuration option for more information.

       Socket (string)
              Specifies the socket that should be established by the filter to
              receive  connections  from  sendmail(8)  in  order  to   provide
              service.   socketspec  is  in one of two forms: local:path which
              creates  a  UNIX  domain  socket  at  the  specified  path,   or
              inet:port[@host]  which  creates  a  TCP socket on the specified
              port.  If the host is not given as either a hostname  or  an  IP
              address,  the  socket will be listening on all interfaces.  This
              option is mandatory either in the configuration file or  on  the
              command line.

       StrictTestMode (Boolean)
              Selects strict CRLF mode during testing (see the -t command line
              flag in the dkim-filter(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
              facility  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
              successful signing or verification of messages.

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

       UMask (integer)
              Requests  a  specific  permissions  mask  to  be  used  for file
              creation.  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
              which  enforces  a  specific file mode on creation regardless of
              the process umask.  See umask(2) for more information.

       UserID (string)
              Attempts  to  become  the  specified  userid   before   starting
              operations.   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.

       X-Header (Boolean)
              Causes  dkim-filter  to  add a header indicating the presence of
              this filter in  the  path  of  the  message  from  injection  to
              delivery.   The  product’s  name,  version,  and  the job ID are
              included in the header’s contents.

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
       interaction 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,  "1.2.3/24"  and  "1.2.3.0/24"  are  not the same
       thing).

VERSION

       This man page covers version 2.6.0 of dkim-filter.

COPYRIGHT

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

SEE ALSO

       dkim-filter(8), sendmail(8)

       RFC4871 - DomainKeys Identified Mail

       Authentication-Results Internet Draft

                                Sendmail, Inc.             dkim-filter.conf(5)