Provided by: opendkim_2.5.2+dfsg-1ubuntu3_i386 bug

NAME

       opendkim - DKIM signing and verifying filter for MTAs

SYNOPSIS

       opendkim  -p  socketspec  [-A]  [-b modes] [-c canon] [-d domain[,...]]
       [-D] [-e name] [-f] [-F time] [-k  keyfile]  [-l]  [-L  min]  [-n]  [-o
       hdrlist]  [-P  pidfile]  [-q]  [-Q] [-r] [-s selector] [-S signalg] [-t
       testfiles] [-T secs] [-u userid[:group]] [-v] [-V] [-W] [-x configfile]

DESCRIPTION

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

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

DATA SETS

       Many of the command line and configuration file parameters  will  refer
       to  a  "dataset"  as their values.  This refers to a string that either
       contains the list of desirable values, or to a file that contains them,
       or (if enabled at compile time) a database containing the data.

       Some data sets require that the value contain more than one entry.  How
       this is done depends on which data set type is used.

       Which type is used depends on the format of the  specification  string.
       In particular:

       a)     If  the  string  begins  with "file:", then the remainder of the
              string is presumed  to  refer  to  a  flat  file  that  contains
              elements  of  the  data  set,  one per line.  If a line contains
              whitespace-separated values, then the line is preusmed to define
              a key and its corresponding value.  Blank lines are ignored, and
              the hash ("#") character denotes the start of a comment.   If  a
              value contains multiple entries, the entries should be separated
              by colons.

       b)     If the string begins with "refile:", then the remainder  of  the
              string  is  presumed  to  specify  a file that contains a set of
              patterns, one  per  line,  and  their  associated  values.   The
              pattern  is  taken  as  the  start  of  the  line  to  the first
              whitespace, and the portion after that whitespace  is  taken  as
              the value to be used when that pattern is matched.  Patterns are
              simple wildcard patterns, matching  all  text  except  that  the
              asterisk  ("*")  character is considered a wildcard.  If a value
              contains multiple entries, the entries should  be  separated  by
              colons.

       c)     If  the  string  begins  with "db:" and the program was compiled
              with Sleepycat DB support, then the remainder of the  string  is
              presumed  to  identify  a Sleepycat database containing keys and
              corresponding values.  These  may  be  used  only  to  test  for
              membership   in   the   data   set,  or  for  storing  keys  and
              corresponding values.  If a value contains multiple entries, the
              entries should be separated by colons.

       d)     If  the  string  begins with "dsn:" and the OpenDKIM library was
              compiled to support that database type, then  the  remainder  of
              the  string  is  a Data Store Name describing the type, location
              parameters and access credentials for an ODBC or  SQL  database.
              The DSN is of the form:

              backend://[user[:pwd]@][port+]host/dbase[/key=value[?...]]

              where  backend  is  the  name  of  a  supported backend database
              mechanism (e.g. "mysql"), user and password are  optional  login
              credentials  for  the  database,  port  and  host  describe  the
              destination of a TCP connection to  connect  to  that  database,
              dbase  is  the  name  of  the  database  to be accessed, and the
              key=value pairs must specify  at  least  "table",  "keycol"  and
              "datacol"  values  specifying the name of the table, the name of
              the column to consider as  the  key,  and  the  name(s)  of  the
              column(s)  to be considered as the values (separated by commas).
              For example (all in one line):

              mysql:://dbuser:dbpass@3306+dbhost/odkim/table=macros
                       ?keycol=host?datacol=v1,v2

              defines  a  MySQL  database  listening  at  port  3306  on  host
              "dbhost";  the  userid  "dbuser" and password "dbpass" should be
              used to access the database; the database name is  "odkim",  and
              the data are in columns "host" (the keys) and "v1" and "v2" (the
              values) inside table "macros".  This example would  thus  return
              two values when a match is found.

              No  value  within the DSN may contain any of the six punctuation
              characters (":", "/", "@", "+", "?" and "=")  used  to  separate
              portions of the DSN from each other.

       e)     If  the  string begins with "ldap:", "ldaps:" or "ldapi:", it is
              presumed to be a space-separated set of one or  more  LDAP  URLs
              that  identify  a  set  of servers to be queried.  The first one
              should be a full RFC4516 LDAP URL indicating a base DN  template
              and  optional  scope,  filter  and  attribute  names  to  use in
              queries.  When constructing a DN template or filter, the special
              tokens "$d" and "$D" are replaced with the key being queried and
              they key broken into components, separated  at  "."  characters,
              each  component  preceded  by  "dc="  and  followed  by  "," (so
              "example.com" would become "dc=example,dc=com").  If a data  set
              requires   multiple  values  to  be  returned,  the  appropriate
              attribute names should be given in the correct order to  satisfy
              such requests.

       f)     If  the  string begins with "lua:", it is presumed to refer to a
              file that contains a Lua script to be executed whenever a  query
              is  performed.   The  key  for  the  query is placed in a global
              variable called  "query",  which  the  called  script  can  then
              access.   The script may return any number of values as required
              for the type of query being performed.

       g)     If the string begins with "memcache:", it is presumed  to  refer
              to a memory cache database provided by memcached.  The remainder
              of the string is a comma-separated list of hosts to which  query
              attempts  should  be made, each optionally followed by ":" and a
              port number; that  list  must  be  followed  by  a  slash  ("/")
              character  and a string that will be used to prefix queries send
              to the cache.  For example:

              memcache:localhost,otherhost/keyname

              This would use either  "localhost"  or  "otherhost"  to  conduct
              queries,  and  all  strings sent to the dataset will be prefixed
              with "keyname:".

       h)     If the string contains none of  these  prefixes  but  ends  with
              ".db",  it  is  presumed to be a Sleepycat DB as described above
              (if support for same is compiled in).

       i)     If the string contains none of these prefixes but starts with  a
              slash  ("/")  character,  it  is  presumed  to be a flat file as
              described above.

       j)     If the string begins with "csl:", the string  is  treated  as  a
              comma-separated list as described in k) below.

       k)     In  any  other  case,  the  string  is  presumed  to be a comma-
              separated list.  Elements in the list  are  either  simple  data
              elements that are part of the set or, in the case of an entry of
              the form "x=y", are  stored  as  key-value  pairs  as  described
              above.

OPTIONS

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

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

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

       -e name
              Extracts the value of name from the configuration file (if any).

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

       -k keyfile
              Gives the location of a PEM-formatted private key to be used for
              signing  all  messages.   Ignored  if  a  configuration  file is
              referenced that defines a KeyTable.

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

       -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 dataset
              Specifies  a  list  of  headers  that  should  be  omitted  when
              generating signatures.  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 that 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
              Specifies  a file into which the filter should write its process
              ID at startup.

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

       -Q     Query test mode.  The filter will read two lines  from  standard
              input,  one  containing  a database description to be opened and
              one containing a string of the form "q/n" where "q" is the query
              to be performed and "n" is the number of fields to be retrieved.

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

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

       -t testfiles
              Evaluates (verifies) one or more RFC5322-formatted message found
              in  testfiles  and  exits.   The  value of testfiles should be a
              comma-separated list of one or more filenames, one of which  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  an
              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.   See  the  FILE  PERMISSIONS  section  for  more
              information.

       -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 opendkim.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.  The default is to  read  a
              configuration  file  from  /etc/opendkim.conf  if one exists, or
              otherwise to apply defaults to all values.

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  InternalHosts
       configuration file setting (or be in the default list for that option),
       or  (c) the client must be connected to a daemon port named by the MTAs
       configuration file setting, or (d) the MTA must have set  one  or  more
       macros  matching  the  criteria set by the MacroList configuration file
       setting.

       For (a) above, the test is whether or not the MTA  macro  "{auth_type}"
       is  set and contains any non-empty value.  This means the MTA must pass
       the value of that macro to the filter  before  or  during  the  end-of-
       header  (EOH)  phase  in  order for its value to be tested.  Check your
       MTA's configuration documentation for details.

       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.

MTA MACROS

       opendkim  makes  use of three MTA-provided macros, plus any demanded by
       configuration.  The basic three are: "i" (the envelope ID,  also  known
       as   the  job  ID  or  the  queue  ID),  which  is  used  for  logging;
       "daemon_name" (the  symbolic  name  given  to  the  MTA  instance  that
       accepted  the  connection), which is used when performing tests against
       any "MTAs" setting used; and "auth_type", which is  used  to  determine
       whether  or  not  the SMTP client authenticated to the MTA.  If the MTA
       does not provide them to opendkim then it is not able  to  apply  their
       corresponding   tests   or   do   useful  logging.   Consult  your  MTA
       documentation to determine how to adjust your its configuration if some
       or all of these are not available.

FILE PERMISSIONS

       When the filter is started as the superuser and the UserID (-u) setting
       is used, the filter gives up its root privileges  by  changing  to  the
       specified   user   after   the  following  steps  are  taken:  (1)  the
       configuration file (if any) is loaded; (2) if the KeyFile (-k)  setting
       is  used,  that  key  is  loaded  into memory; (3) all data sets in the
       configuration file are opened, and those that are based on  flat  files
       are  also  read into memory; and (4) if ChangeRootDirectory is set, the
       process root is changed to that directory.  This means on configuration
       reload,   the   filter  will  not  be  accessing  these  files  or  the
       configuration file as the superuser  (and  possibly  from  a  different
       root),  and  any  key  files  referenced  by  the KeyTable will also be
       accessed by the new user.

       Thus, keys referenced by the KeyTable must  always  be  accessible  for
       read by the unprivileged user.  Also, run-time reloads are not possible
       if any of the other files will not  be  readable  by  the  unprivileged
       user.

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,  "192.0.2/24" and "192.0.2.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.5.2 of opendkim.

COPYRIGHT

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

       Copyright (c) 2009-2011, The OpenDKIM Project.  All rights reserved.

SEE ALSO

       opendkim.conf(5), sendmail(8)

       Sendmail Operations Guide

       RFC5321 - Simple Mail Transfer Protocol

       RFC5322 - Internet Messages

       RFC5451 - Message Header Field for  Indicating  Message  Authentication
       Status

       RFC6008 - Authentication-Results Registration for Differentiating among
       Cryptographic Results

       RFC6376 - DomainKeys Identified Mail

                             The OpenDKIM Project                  opendkim(8)