Ubuntu Manpage: dkimpy-milter - Python milter for DKIM signing and validation

NAME

       dkimpy-milter - Python milter for DKIM signing and validation

VERSION

       1.2.0

DESCRIPTION

       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

       Usage:
         dkimpy-milter [/etc/dkimpy-milter/dkimpy-milter.conf]

SYNOPSIS

       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.

DESCRIPTION

       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.

OPTIONS

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.

OmitHeaders (dataset)
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.

SignHeaders (dataset)
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.

NOTES

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

FILES

       /etc/dkimpy-milter/dkimpy-milter.conf
              Default location of this file.

AUTHORS

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

COPYRIGHT

       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>

                                                   2019-04-25                              dkimpy-milter.conf(5)

NAME

VERSION

DESCRIPTION

USAGE

OTHER DOCUMENTATION

SYNOPSIS

DESCRIPTION

OPTIONS

NOTES

FILES

AUTHORS

COPYRIGHT