Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
dk-filter(8)		    System Manager's Manual		  dk-filter(8)

       dk-filter - DomainKeys filter for sendmail

       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]

       dk-filter implements Yahoo!, Inc.'s DomainKeys draft standard for sign-
       ing 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

       -a peerlist
	      Identifies a file	of "peers" which identifies clients whose con-
	      nections	should	be accepted without processing by this filter.
	      The peerlist should contain on each line a hostname, domain name
	      (e.g. ""), IP	address, an IPv6 address (including an
	      IPv4 mapped address), or a  CIDR-style  IP  specification	 (e.g.

       -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 mes-
	      sages.   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 de-

       -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 char-
	      acter "*"	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 ser-
	      vice  running  in	the background.	 This flag suppresses that be-
	      haviour 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

       -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 "" is	applied.

       -I eilist
	      Identifies a file	 of  "external"	 hosts	which  may  send  mail
	      through the server as one	of the signing domains without creden-
	      tials as such; basically suppresses the  "external  host	(host-
	      name)  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-pat-
	      tern: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)  Dae-
	      monPortOptions  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

       -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  ser-
	      vice.   socketspec is in one of two forms: local:path which cre-
	      ates  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	 file-
	      name given.

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

       -R     When  a signature	verification fails and the signing site	adver-
	      tises a reporting	 address  (i.e.	  r=user@host  in  its	policy
	      record), send a structured report	to that	address	containing de-
	      tails 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 mes-
	      sages.  See the DomainKeys specification for details.

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

       -u userid
	      Attempts to be come the specified	userid before starting	opera-

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

       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 mes-
       sages that produce certain results.  Each result	and each action	has  a
       full name and an	abbreviated name.  Either is accepted.	Below, the ab-
       breviated name appears in parentheses.

	      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; nosigna-
	      ture (no)	no signature was present on  the  message;  signature-
	      missing  (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 mes-

       In the interests	of minimal initial impact, the defaults	for  badsigna-
       ture,  nosignature and signaturemissing are all accept, and the default
       for the others is tempfail.

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

       The following environment variable(s) can be used to adjust the	behav-
       iour 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 be-
       tween sendmail and the filter.  Otherwise, the MTA could	abort  a  mes-
       sage  while waiting for a reply from the	filter,	which in turn is still
       waiting for a DNS reply.

       This man	page covers version 1.0.1 of dk-filter.

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


       Sendmail	Operations Guide

       RFC2821 - Simple	Mail Transfer Protocol

       RFC2822 - Internet Messages

       DomainKeys Internet Draft

				Sendmail, Inc.			  dk-filter(8)


Want to link to this manual page? Use this URL:

home | help