Man Linux: Main Page and Category List


       opendkim - DKIM signing and verifying filter for MTAs


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


       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.


       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

       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:


              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):


              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.

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

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

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

       j)     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


       -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

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

       -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

       -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

       -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  'dkim-filter  -V'  to see the list of supported algorithms.
              The default is rsa-sha256 if it is available, otherwise it  will
              be rsa-sha1.

       -t testfile
              Evaluates  (verifies)  an  RFC5322-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

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

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

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


       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.

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


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

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


       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 "" are not the same


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


       This man page covers version 2.1.3 of opendkim.


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

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


       opendkim.conf(5), sendmail(8)

       Sendmail Operations Guide

       RFC4871 - DomainKeys Identified Mail

       RFC5321 - Simple Mail Transfer Protocol

       RFC5322 - Internet Messages

       RFC5451 - Message Header Field for  Indicating  Message  Authentication

                             The OpenDKIM Project                  opendkim(8)