Provided by: dkim-filter_2.8.3.dfsg-0ubuntu4_i386 bug

NAME

       dkim-filter - DKIM filter for sendmail

SYNOPSIS

       dkim-filter  -p socketspec [-a peerlist] [-A] [-b modes] [-c canon] [-C
       config] [-d domains] [-D] [-f] [-F time] [-i ilist]  [-I  eilist]  [-h]
       [-k keyfile] [-K] [-l] [-L min] [-m mtas] [-M macro[=value][,...]] [-n]
       [-o hdrlist] [-P pidfile] [-q] [-r] [-R] [-s selector] [-S signalg] [-t
       testfile]  [-T  secs] [-u userid[:group]] [-U popdb] [-v] [-V] [-W] [-x
       configfile]

DESCRIPTION

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

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

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

OPTIONS

       -a peerlist
              Identifies a file of  "peers"  which  identifies  clients  whose
              connections  should  be  accepted  without  processing  by  this
              filter.  The peerlist 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.

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

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

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

       -C config
              Configuration  control.   See  the  CONFIGURATION  section   for
              details.

       -d domain [,...]
              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.

              Matching is case-insensitive.

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

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

       -f     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.

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

       -h     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.

       -i ilist
              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 -a option above.  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.

       -I eilist
              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 eilist file should be of the same form as those
              of the -a option above.  The list is empty by default.

       -K     Requests multiple-key processing.  See also -k below.

       -k keyfile
              Without -K, gives the location of a PEM-formatted private key to
              be  used  for signing all messages.  With -K, gives the location
              of a file listing rules for signing with multiple keys.

              In the latter mode, the keyfile 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.

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

       -L min[%+]
              Instructs the verification code to fail  messages  for  which  a
              partial  signature  was  received.   There  are  three  possible
              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.

       -m mta[,...]
              A  comma-separated  list  of  MTA  names  (a  la the sendmail(8)
              DaemonPortOptions Name parameter) whose mail should be signed by
              this filter.  If not set, the MTA name is not used when deciding
              whether or not a message should be signed.

       -M macro[=value][,...]
              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 the value
              specified (matching is case-insensitive),  otherwise  the  macro
              must  be  defined but may contain any value.  Multiple tests may
              be specified, separated by commas.  The set is empty by default,
              meaning  macros  are  not  used  when  deciding whether or not a
              message should be signed.

              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.

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

       -o hdrlist
              Specifies  a  list  of  headers  which  should  be  omitted when
              generating signatures.  hdrlist 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).

       -p socketspec
              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.  If
              neither socket type is specified, local is assumed, meaning  the
              parameter is interpreted as a path at which the socket should be
              created.  This parameter is mandatory.

       -P pidfile
              Writes the process ID  of  the  filter,  once  started,  to  the
              filename given.

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

       -r     Checks  all  messages  for  compliance with RFC2822 header count
              requirements.  Non-compliant messages are rejected.

       -R     When  a  signature  verification  fails  and  the  signing  site
              advertises  a reporting address (i.e.  r=user@host in its policy
              record), send a structured report  to  that  address  containing
              details needed to reproduce the problem.

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

       -S signalg
              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.

       -t testfile
              Evaluates  (verifies)  an  RFC2822-formatted  message  found  in
              testfile  and  exits.   The  value of testfile may be "-" if the
              message should be read from standard input.

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

       -u userid[:group]
              Attempts  to  be  come  the  specified  userid  before  starting
              operations.  The process will be assigned all of the groups  and
              primary  group  ID of the named userid unless an alternate group
              is specified.

       -U popdb
              Requests that the filter consult a POP  authentication  database
              for IP addresses that should be allowed for signing.  The filter
              must be specially compiled to enable this feature, since it adds
              a library dependency.

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

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

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

       -x configfile
              Read the named configuration file.  See the  dkim-filter.conf(5)
              man  page  for  details.   Values  in the configuration file are
              overridden when their equivalents are provided  on  the  command
              line until a configuration reload occurs.  The OPERATION section
              describes how reloads are triggered.

ACTION CONFIGURATION

       The value of the -C switch is a comma-separated list of settings of the
       form  result=action  which  defines  what  the  filter  should  do with
       messages that produce certain results.  Each result and each action has
       a  full  name and an abbreviated name.  Either is accepted.  Below, the
       abbreviated name appears in parentheses.

       results
              badsignature (bad) the signature found in the  message  did  not
              verify successfully against the message; dnserror (dns) an error
              was encountered attempting to retrieve a  public  key  from  the
              nameserver;   internal   (int)   an   internal  error  occurred;
              nosignature (no)  no  signature  was  present  on  the  message;
              security  (sec)  the  message tripped internal security concerns
              (e.g. unusually large header blocks).  There is also  a  special
              result  called  default (def) whose action is copied onto all of
              the other results.

       action accept (a) accept the message; discard (d) discard the  message;
              tempfail  (t)  temp-fail  the  message;  reject  (r)  reject the
              message.

       In  the  interests  of  minimal  initial  impact,  the   defaults   for
       badsignature and nosignature are accept, and the default for the others
       is tempfail.

       Results and actions are processed in  order,  so  use  of  the  default
       action  can  be overridden by later specifications.  For example, using
       "def=a,int=t" sets all result actions to "accept" except  for  internal
       errors which will generate a temporary failure.

OPERATION

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

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

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

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

ENVIRONMENT

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

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

NOTES

       When using DNS timeouts (see the -T option above), be sure not to use a
       timeout that is larger than the  timeout  being  used  for  interaction
       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.

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

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

HISTORY

       DKIM is  an  amalgam  of  Yahoo!’s  DomainKeys  proposal,  and  Cisco’s
       Internet Identified Mail (IIM) proposal.

VERSION

       This man page covers version 2.8.0 of dkim-filter.

COPYRIGHT

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

SEE ALSO

       dkim-filter.conf(5), sendmail(8)

       Sendmail Operations Guide

       RFC2821 - Simple Mail Transfer Protocol

       RFC2822 - Internet Messages

       RFC4871 - DomainKeys Identified Mail

       RFC5451 - Message Header Field for  Indicating  Message  Authentication
       Status

                                Sendmail, Inc.                  dkim-filter(8)