Man Linux: Main Page and Category List

NAME

       dk-filter - DomainKeys filter for sendmail

SYNOPSIS

       dk-filter  -p  socketspec  [-a peerlist] [-A] [-b modes] [-c canon] [-C
       config] [-d domains] [-D] [-f] [-i ilist] [-I eilist]  [-h]  [-H]  [-k]
       [-l]  [-m mtas] [-M macro[=value][,...]] [-o hdrlist] [-P pidfile] [-q]
       [-R] [-s keyfile] [-S selector] [-T secs] [-u userid] [-U popdb] [-V]

DESCRIPTION

       dk-filter implements  Yahoo!,  Inc.’s  DomainKeys  draft  standard  for
       signing and verifying e-mail messages on a per-domain basis.

       Details  regarding  the  protocol and other issues related to the draft
       standard can be found at http://antispam.yahoo.com/domainkeys.

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").

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

       -b modes
              Selects operating modes.  modes 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.

       -c canon
              Selects  the  canonicalization  method  to  be used when signing
              messages.  When verifying,  the  message’s  DomainKey-Signature:
              header  specifies  the  canonicalization method.  The recognized
              values are nofws and simple as defined by the DomainKeys  draft.
              The default is simple.

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

              If the value of this parameter starts with a "/"  character,  it
              is  assumed  to be a filename from which the domain list will be
              read, one per line, with "#" characters indicating the beginning
              of a comment.

              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.

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

       -f     Normally dk-filter forks  and  exits  immediately,  leaving  the
              service  running  in  the background.  This flag suppresses that
              behaviour so that it runs in the foreground.

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

       -H     Includes  on  DomainKey signatures the list of headers that were
              included in the signature.   This  makes  the  signature  header
              larger by explicitly listing the included headers, but this also
              allows verifying agents to ignore headers  that  were  added  in
              transit.

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

       -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 this file follow the same form as  those  of  the  -a
              option above.

       -k     Causes -s to be interpreted as the location of a key list, which
              is a file listing rules for signing with multiple keys.  The key
              list  should  contain  a  set  of  lines  of  the  form  sender-
              pattern:keypath where  sender-pattern  is  a  pattern  to  match
              against   message   senders  (with  the  special  character  "*"
              interpreted as "zero or more characters"), 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.

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

       -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.  There is no default.

       -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.  The list is empty by
              default.

       -o header [,...]
              A  comma-separated  list  of headers which should not be signed.
              Ignored when verifying.

       -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.   This
              option 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     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 keyfile
              Gives the location of a PEM-formatted private key to be used for
              message signing.

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

       -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
              Attempts  to  be  come  the  specified  userid  before  starting
              operations.

       -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     Print the version number and exit without doing anything else.

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;
              signaturemissing  (miss) no signature was present on the message
              which claims to sign all messages.

       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,  nosignature and signaturemissing are all accept, and the
       default for the others is tempfail.

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,  and  (2)  the
       client  connecting  to  the  MTA must (a) have authenticated, or (b) be
       listed in the file referenced by the -i command line switch (or  be  in
       the  default  list for that option), or (c) be connected to daemon port
       named by the -m command line switch.

       When signing a message, a DomainKey-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.

ENVIRONMENT

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

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

VERSION

       This man page covers version 1.0.0 of dk-filter.

COPYRIGHT

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

SEE ALSO

       sendmail(8)

       Sendmail Operations Guide

       RFC2821 - Simple Mail Transfer Protocol

       RFC2822 - Internet Messages

       DomainKeys Internet Draft

       http://antispam.yahoo.com/domainkeys

                                Sendmail, Inc.                    dk-filter(8)