dkimpy-milter - Python milter for DKIM signing and validation
dkimpy-milter(8) implements the DKIM specification
for signing and verifying e-mail messages on a per-domain basis. This file
is its configuration file.
Blank lines are ignored. Lines containing a hash ("#")
character are truncated at the hash character to allow for comments in the
file.
Other content should be the name of a parameter, followed by white
space, followed by the value of that parameter, each on a separate line.
For parameters that are Boolean in nature, only the first byte of
the value is processed. For positive values, the following are accepted:
"T", "t", "Y", "y", "1".
For negative values, the following are accepted: "F",
"f", "N", "n", "0".
The provided setup.py installs this configuration file in /etc or
/usr/local/etc based on the value of expand sysconfigdir= used when the
package was installed.
Command line invocation of parameters as is done by OpenDKIM is
not supported.
Usage:
dkimpy-milter [/etc/dkimpy-milter/dkimpy-milter.conf]
This documentation assumes you have read Postfix's
README_FILES/MILTER_README (or Sendmail equivalent) and are generally
familiar with Domain Keys Identified Mail (DKIM). See RFC 6376 for
details.
dkimpy-milter operates with a default installed configuration file
and set of default configuration options that are used if the configuration
file cannot be found. These options can be changed by changing the installed
configuration files. For users transitioning from OpenDKIM, OpenDKIM config
files can be used directly. Not all OpenDKIM options are supported. If an
unsupported option from OpenDKIM is specified, an error will be raised.
Configuration options are described here and in the configuration
file provided with the package. The provided setup.py installs this
configuration file in /etc or /usr/local/etc.
- AuthservID
(string)
- Sets the "authserv-id" to use when generating the
Authentication-Results: header field after verifying a message. The
default is to use the name of the MTA processing the message. If the
string "HOSTNAME" is provided, the name of the host running the
filter (as returned by the gethostname(3) function) will be used.
- Canonicalization
(string)
- Selects the canonicalization method(s) to be used when signing messages.
When verifying, the message's DKIM-Signature: header field specifies the
canonicalization method. The recognized values are relaxed and
simple as defined by the DKIM specification. The default is
relaxed / simple. The value may include two different
canonicalizations separated by a slash ("/") character, in which
case the first will be applied to the header and the second to the body.
- DiagnosticDirectory
(string)
- Directory into which to write diagnostic reports when message verification
fails. If not set (the default), these files are not generated. The
directory must exist, dkimpy-milter will not create it and an error will
be raised if it does not. [Unlike OpenDKIM, this applies to all messages,
not just on messages bearing a "z=" tag because dkimpy does not
yet support "z=" processing.]
- Domain
(dataset)
- A set of domains whose mail should be signed by this filter. Mail from
other domains will be verified rather than being signed.
This parameter is not required if a SigningTable is in
use; in that case, the list of signed domains is implied by the lines in
that file.
This parameter is ignored if a KeyTable or
KeyTableD25119 is defined.
- InternalHosts
(dataset)
- Identifies a set internal hosts whose mail should be signed rather than
verified. Entries in this data set follow the same form as those of the
PeerList option below. 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. [PeerList NOT
IMPLEMENTED]
Mail sent via connections from InternalHosts will not have any
existing DKIM signatures verified. This is not overridden by MacroList
or Mode. If the Mode is 'v', then no actions will be performed.
- KeyFile
(string)
- Gives the location of a PEM-formatted private key to be used for RSA
signing all messages. Ignored if a KeyTable is defined.
- KeyFileEd25519
(string)
- Gives the location of a Ed25519 private key to be used for Ed25519 signing
all messages. File is the Base64 encoded output of RFC 8032 Ed25519
private Key generation (as used in dkimpy). Ignored if a
KeyTableEd25519 is defined.
- KeyTable
(dataset)
- Gives the location of a file mapping key names to RSA signing keys. If
present, overrides any KeyFile setting in the configuration file. The data
set named here maps each key name to three values: (a) the name of the
domain to use in the signature’s "d=" value; (b) the name
of the selector to use in the signature’s "s=" value; and
(c) the path to a file containing a private key. If the first value
consists solely of a percent sign ("%") character, it will be
replaced by the apparent domain of the sender when generating a signature.
The third value must start with a slash ("/") character, or
"./" or "../" to indicate it refers to a file from
which the private key should be read. The SigningTable (see below) is used
to select records from this table to be used to add signatures based on
the message sender.
See the COMPLEX SIGNING CONFIGURATIONS section of README.md
for examples.
- KeyTableEd25519
(dataset)
- Gives the location of a file mapping key names to Ed25519 signing keys. If
present, overrides any KeyFile setting in the configuration file. The data
set named here maps each key name to three values: (a) the name of the
domain to use in the signature’s "d=" value; (b) the name
of the selector to use in the signature’s "s=" value; and
(c) the path to a file containing a private key. If the first value
consists solely of a percent sign ("%") character, it will be
replaced by the apparent domain of the sender when generating a signature.
The third value must start with a slash ("/") character, or
"./" or "../" to indicate it refers to a file from
which the private key should be read. The SigningTable (see below) is used
to select records from this table to be used to add signatures based on
the message sender. NOTE: There is a limitation of the current
implementation that a private key can't be directly included in the file
if it starts with '/', './', or '../'. If you have such a key, you may
store it in a file and reference the file in the table.
See the COMPLEX SIGNING CONFIGURATIONS section of README.md
for examples.
- MacroList
(dataset)
- Defines a set of MTA-provided macros that 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
matching a macro name in the data set, the value of the macro must match a
value specified (matching is case-sensitive), otherwise the macro must be
defined but may contain any value. The set is empty by default, meaning
macros are not considered when making the sign-verify decision. The
general format of the value is 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.
In order for the macro and its value to be available to the
filter for checking, the MTA must send it during the protocol exchange.
This is either accomplished via manual configuration of the MTA to send
the desired macros or, for MTA/filter combinations that support the
feature, the filter can request those macros that are of interest. The
latter is a feature negotiated at the time the filter receives a
connection from the MTA and its availability depends upon the version of
milter used to compile the filter and the version of the MTA making the
connection.
Mail sent via connections where macros that are in MacroList
are provided will not have any existing DKIM signatures verified. If the
Mode is 'v', then no actions will be performed.
- MacroListVerify
(dataset)
- Defines a set of MTA-provided macros that should be checked to see
if the sender has been determined to be an external source and therefore
whether or not the message should be signed. Entries in this data set
follow the same form as those of the MacroList option above. [this
option is not inhereted from OpenDKIM]
Mail sent via connections where macros that are in
MacroListVerify are provided will be not DKIM signed. If the Mode is
's', then no actions will be performed.
- Mode (string)
- Selects operating modes. The string 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 the opendkim(8) man page) in which case the default is
v. When signing mode is enabled, one of the following combinations
must also be set: (a) Domain, KeyFile, Selector, no KeyTable, no
SigningTable; (b) KeyTable, SigningTable, no Domain, no KeyFile, no
Selector;
The action to sign or verify is also affected by the
InternalHosts, MacroList, and MacroListVerify options. Those options may
preclude signing or verification in some cases, but will not enable
signing or verifying if not allowed by Mode.
- MinimumKeyBits
(integer)
- Establishes a minimum key size for acceptable RSA signatures. Signatures
with smaller key sizes, even if they otherwise pass DKIM validation, will
me marked as invalid. The default is 1024, which accepts all signatures. A
value of 0 causes the default to be used. Not Applicable to ed25519
signatures.
- Specifies a set of header fields that should be omitted when generating
signatures. If an entry in the list names any header field that is
mandated by the DKIM specification, the entry is ignored. A set of header
fields is listed in the DKIM specification (RFC6376, Section 5.4) as
"SHOULD NOT" be signed; the default list for this parameter
contains those fields (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 header field names).
Specifying a list with this parameter replaces the default entirely,
unless one entry is "*" in which case the list is interpreted as
a delta to the default; for example, "*,+foobar" will use the
entire default list plus the name "foobar", while
"*,-Bcc" would use the entire default list except for the
"Bcc" entry. [OmitHeaders NOT IMPLEMENTED - included for
reference only]
- DNSOverride
(string)
- Provide a text string that a verifying milter should use instead of
consulting the DNS on each message. This is useful primarily for testing
purposes in environments where it is awkward to modify the system DNS
resolution. It should not be used in production.
- DNSTimeout
(integer)
- Sets the DNS timeout in seconds. A value of 0 causes no wait (this is
different than opendkim). The default is 5. See also the NOTES section
below.
- PeerList
(dataset)
- Identifies a set of "peers" that identifies clients whose
connections should be accepted without processing by this filter. The set
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. Host and domain
names are matched first, then the IP or IPv6 address depending on the
connection type. More precise entries are preferred over less precise
ones, i.e. "192.168.1.1" will match before
"!192.168.1.0/24". The text form of IPv6 addresses will be
forced to lowercase when queried (RFC5952), so the contents of this data
set should also use lowercase. The IP address portion of an entry may
optionally contain square brackets; both forms (with and without) will be
checked. [PeerList NOT IMPLEMENTED - included for reference only]
- PidFile
(string)
- Specifies the path to a file that should be created at process start
containing the process ID. If not specified, no such file will be created.
- Selector
(string)
- Defines the name of the selector to be used when signing messages using
RSA. See the DKIM specification for details. Used only when signing
with a single key; see the SigningTable parameter below for more
information.
This parameter is ignored if a KeyTable is defined.
- SelectorEd25519
(string)
- Defines the name of the selector to be used when signing messages using
Ed25519. See the DKIM specification for details. Used only when
signing with a single key; see the SigningTable parameter below for
more information.
This parameter is ignored if a KeyTableEd25519 is
defined.
- Specifies the set of header fields that should be included when generating
signatures. If the list omits any header field that is mandated by the
DKIM specification, those fields are implicitly added. By default, those
fields listed in the DKIM specification as "SHOULD" be signed
(RFC6376, Section 5.4) will be signed by the filter. See the
OmitHeaders configuration option for more information about the
format and interpretation of this field.
- SigningTable
(dataset)
-
Defines a table used to select a signing identity to apply to
a message based on the address found in the From: header field. Keys in
this table vary depending on the type of table used; values in this data
set should include one field that contains a name found in the KeyTable
(see above) that identifies which key should be used in generating the
signature, and an optional second field naming the signer of the message
that will be included in the "i=" tag in the generated
signature. Note that the "i=" value will not be included in
the signature if it conflicts with the signing domain (the
"d=" value).
If the first field contains only a "%" character, it
will be replaced by the domain found in the From: header field.
Similarly, within the optional second field, any "%" character
will be replaced by the domain found in the From: header field.
If this table specifies a regular expression file
("refile"), then the keys are wildcard patterns that are
matched against the address found in the From: header field. Entries are
checked in the order in which they appear in the file. Note: These are
not true regular expressions. The terminology is inherited from
opendkim. Only wildcards ("*") are supported.
For all other database types, the full user@host is checked
first, then simply host, then user@.domain (with all superdomains
checked in sequence, so "foo.example.com" would first check
"user@foo.example.com", then "user@.example.com",
then "user@.com"), then .domain, then user@*, and finally
*.
In any case, only the first match is applied.
See the COMPLEX SIGNING CONFIGURATIONS section of README.md
for examples.
- Socket
(string)
- Specifies the socket that should be established by the filter to receive
connections from postfix(1) 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] or inet6:port[@host] which creates a TCP
socket on the specified port and in the specified protocol family.
If the host is not given as either a hostname or an IP address, the
socket will be listening on all interfaces. A literal IP address must be
enclosed in square brackets. This option is mandatory in the configuration
file.
- SubDomains
(Boolean)
- Sign subdomains of those listed by the Domain parameter as well as
the actual domains.
- Syslog
(Boolean)
- Log via calls to syslog(3) any interesting activity.
- SyslogFacility
(string)
- Log via calls to syslog(3) using the named facility. The facility
names are the same as the ones allowed in syslog.conf(5). The
default is "mail".
- SyslogSuccess
(Boolean)
- Log via calls to syslog(3) additional entries indicating successful
signing or verification of messages.
- UMask
(integer)
- Requests a specific permissions mask to be used for file creation. This
only really applies to creation of the socket when Socket specifies
a UNIX domain socket, and to the PidFile (if any); temporary files
are created by the mkstemp(3) function that enforces a specific
file mode on creation regardless of the process umask. See umask(2)
for more information.
- UserID
(string)
- Attempts to become the specified userid before starting operations. The
value is of the form userid[:group]. The process will be assigned
all of the groups and primary group ID of the named userid unless
an alternate group is specified.
When using DNS timeouts (see the DNSTimeout 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. This must take into accout that the timeout
is per DNS lookup so the total DNS wait time may be subustantially loner
than the value specified in DNSTimeout InternalHosts option is
in use and one for DKIM public key record lookup for each algorithm per
signature per message (i.e. potentially two lookups per signature).
- /etc/dkimpy-milter/dkimpy-milter.conf
- Default location of this file.
dkimpy-milter was written by Scott Kitterman
<scott@kitterman.com>. It is based on dkim-milter.py Copyright (c)
2001-2013 Business Management Systems, Inc. Copyright (c) 2013-2015 Stuart
D. Gathman Copyright (c) 2018,2019 Scott Kitterman
<scott@kitterman.com>.
This man-page was created by Scott Kitterman
<scott@kitterman.com>.
Configuration items derived from OpenDKIM 2.11.0
opendkim.conf.5.in: Copyright (c) 2007, 2008, Sendmail, Inc. and its
suppliers. All rights reserved. See LICENSE.Sendmail.
Copyright (c) 2009-2015, The Trusted Domain Project. All rights
reserved. See LICENSE.
Updated for dkimpy-milter. Updates licensed under the same terms
as the rest of the package. Copyright (c) 2018,2019 Scott Kitterman
<scott@kitterman.com>