Provided by: dkim-filter_2.5.4.dfsg-0ubuntu2_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.

       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.

       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.

       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.

       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.

       On-SignatureMissing (string)
              Selects the action to be taken when a message  arrives  unsigned
              from  a  domain  which advertises a "we sign everything" policy.
              Possible values are the same as those for On-BadSignature.   The
              default is accept.

       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.

       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.

       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.

       SendReports (Boolean)
              If  true,  when  a  signature verification fails and the signing
              site advertises a reporting address (i.e.   r=user@host  in  its
              policy record), 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.

       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.

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

       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.

VERSION

       This man page covers version 2.5.4 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)