.TH DKIM-MILTER.CONF 5 2024-06-13 "DKIM Milter 0.2.0-alpha.1"
.SH NAME
dkim-milter.conf \- DKIM Milter configuration file
.SH SYNOPSIS
.B /etc/dkim-milter/dkim-milter.conf
.SH DESCRIPTION
.I dkim-milter.conf
is the configuration file for DKIM Milter.
.BR dkim-milter (8)
is a milter application that signs and verifies messages using the
.I DomainKeys Identified Mail
protocol (RFC\~6376).
.PP
DKIM Milter accepts incoming connections from the MTA, and then handles each
message transaction in either signing mode or verifying mode.
That is, it either signs the message, or verifies the message’s signatures
according to the configuration.
The decision whether the message should undergo signing or verification is made
in the following way:
If a message comes from a
.I trusted source
and is submitted by an
.I originator
that matches a configured
.IR "signing sender" ,
then the message is signed.
If a message comes from an untrusted source, it is verified instead.
Trusted sources and signing senders are configured with parameters
.BR trusted_networks ,
.BR trust_authenticated_senders ,
and
.BR signing_senders .
The originator of a message is taken from the message’s
.I Sender
header if present, else from the message’s
.I From
header.
.PP
The configuration file format uses a flat key–value scheme with one parameter
per line.
Key and value are separated with the character
.BR = .
Whitespace before and after key and value is not significant.
Blank lines and lines whose first non-blank character is
.B #
are ignored.
Configuration can be reloaded from disk during operation by sending the signal
.B SIGHUP
to the milter process.
If reloading fails, an error is logged and the in-memory configuration remains
active.
A small set of parameters configured at program start cannot be reloaded: the
parameters
.BR socket ,
.BR log_destination ,
.BR log_level ,
and
.BR syslog_facility .
Options passed on the command-line are also not reloaded.
.SH PARAMETERS
This section lists all configuration parameters available in the three
categories “General”, “Signing”, and “Verification” in alphabetical order.
.PP
Possible values for each parameter are given in parentheses.
Below, a
.I boolean
value is either
.B yes
or
.B no
(alias
.B true
and
.BR false ).
A
.I duration
is an integer optionally followed by
.B d
(days),
.B h
(hours),
.B m
(minutes), or
.B s
(seconds; the default unit).
A
.I colon-separated
value is a possibly empty list or set of elements separated by “:”.
.PP
A
.I data source
is some persistent storage providing a list or set of configuration data.
Currently, the following data sources are available.
The
.I cached
or
.I in-memory filesystem data source
is represented as a path prefixed with
.B <
or
.B slurp:
(for example,
.BR </path/to/file ).
Data is read from this file at startup, and the filesystem is not accessed
during operation.
The
.I live filesystem data source
is represented as a path prefixed with
.B file:
(for example,
.BR file:/path/to/file ).
Data is read from this file on demand, and discarded from memory after use.
The term
.I table
is used to refer to a filesystem data source containing tabular data.
A table contains lines with whitespace-separated columns of table-specific data.
As in configuration files, blank lines and lines whose first non-blank character
is
.B #
are ignored in tables.
Further, the
.I SQLite data source
is represented as an SQLite database URI with prefix
.B sqlite:
(for example,
.BR sqlite://dkim-milter.db ).
Data is queried from a table in this database when needed.
The table name can be customized by appending “#” followed by the table name.
This data source is only available if DKIM Milter was compiled with feature
“sqlite”.
The database schema is documented elsewhere.
.SS General parameters
General parameters allow configuration of basic properties of DKIM Milter.
These parameters are available only in the main configuration file.
They cannot be overridden.
.TP
.BR authserv_id " (\fIstring\fR)"
The
.I authserv-id
or
.I authentication service identifier
to use in
.I Authentication-Results
header fields.
Refer to RFC 8601, section 2.5 for a description of this element.
Only the unquoted syntax is supported for the
.I authserv-id
value.
Defaults to the MTA’s hostname (the value of the sendmail macro
.BR j ).
.TP
.BR connection_overrides " (\fIdata-source\fR)"
Data source providing a list of per-connection configuration overrides.
The following describes the filesystem data source (pointing to a table).
The table should list, in whitespace-separated columns, (1) a network address,
(2) a filesystem data source pointing to a configuration file containing signing
and verification parameters.
.IP
When processing a message, if an entry matches the connecting IP address, its
associated configuration parameters override the main configuration settings.
.IP
Note that if the data source lookup fails, the current message transaction is
aborted with a transient SMTP error.
.TP
.BR delete_incoming_authentication_results " (\fIboolean\fR)"
Whether to delete incoming
.I Authentication-Results
header fields whose
.I authserv-id
matches the
.B authserv_id
setting.
When this setting is enabled,
.I Authentication-Results
headers purporting to carry results from this authentication service (that is,
forged results) are deleted.
.I Authentication-Results
headers with a foreign
.I authserv-id
pass through unaltered.
The default is
.BR yes .
.TP
.BR dry_run " (\fIboolean\fR)"
Whether to take action or apply modifications during processing.
When this setting is enabled, the normal signing and verification logic is
performed, but no messages are rejected at the SMTP level, and no headers are
added to or deleted from messages.
The default is
.BR no .
.TP
.BR log_destination " (" syslog " | " stderr )
The destination for log messages.
Log destination
.B syslog
causes log messages to be written to the system logger.
Log destination
.B stderr
causes log messages to be written to standard error.
This setting cannot be reloaded.
The default is
.BR syslog .
.TP
.BR log_level " (" error " | " warn " | " info " | " debug )
The minimum severity level of messages to log.
The log levels are, in descending severity order and with the conventional
meaning,
.BR error ,
.BR warn ,
.BR info ,
and
.BR debug .
This setting cannot be reloaded.
The default is
.BR info .
.TP
.BR lookup_timeout " (\fIduration\fR)"
Maximum time to allow when querying for DKIM public key records.
The default is
.BR 10s .
.TP
.BR mode " (" auto " | " sign " | " verify )
The milter’s operating mode.
In mode
.BR auto ,
messages are either signed or verified according to the decision algorithm
described further above.
In mode
.BR sign ,
the milter performs signing for trusted senders configured for signing, but does
not perform verification.
In mode
.BR verify ,
the milter performs verification for untrusted senders, but does not sign.
The default is
.BR auto .
.TP
.BR recipient_overrides " (\fIdata-source\fR)"
Data source providing a list of per-recipient configuration overrides.
The following describes the filesystem data source (pointing to a table).
The table should list, in whitespace-separated columns, (1) a recipient
expression (the same format as a sender expression, see below), (2) a filesystem
data source pointing to a configuration file containing signing and verification
parameters.
.IP
When processing a message, if an entry matches an envelope recipient addresses
(SMTP command
.IR "RCPT TO" ),
its associated configuration parameters override the main configuration
settings.
.IP
Note that if the data source lookup fails, the current message transaction is
aborted with a transient SMTP error.
.TP
.BR require_envelope_sender_match " (\fIboolean\fR)"
Whether to accept for signing only senders (in the
.I Sender
or
.I From
header) that match the envelope sender in the MAIL FROM command.
When this setting is disabled, the originator email address taken from the
.I Sender
or
.I From
header will be used for the signing senders lookup even if it differs from the
envelope address.
This parameter is intended to prevent cross-user signing, where one (trusted)
user would be able to use signing key and configuration for a different user.
The default is
.BR no .
.TP
.BR signing_keys " (\fIdata-source\fR)"
Data source providing the available signing keys.
The following describes the filesystem data source (pointing to a table).
The table should list, in whitespace-separated columns, (1) a unique, arbitrary
key name, (2) a filesystem data source pointing to a PKCS#8 PEM file, containing
an RSA or Ed25519 signing key.
.IP
When signing a message, if an entry is selected via its key name, then the
associated signing key is used to produce the cryptographic signature.
.IP
Note that if the data source lookup fails, the current message transaction is
aborted with a transient SMTP error.
.TP
.BR signing_senders " (\fIdata-source\fR)"
Data source providing the available signing senders.
The following describes the filesystem data source (pointing to a table).
The table should list, in whitespace-separated columns, (1) a sender expression,
(2) a domain name or an identity expression, (3) a selector, (4) a key name
listed in
.BR signing_keys ,
(5) optionally, a filesystem data source pointing to a configuration file
containing signing parameters.
.IP
A sender expression may be (a) a domain name, (b) a domain name prefixed with
“.”, which will match both the domain and all subdomains, (c) a glob pattern,
that is a string where occurrences of “*” will match arbitrary substrings.
An identity expression is an email address where the local-part may be omitted,
that is
.RI [ local-part "]\fB@\fR" domain .
In an identity expression the domain may contain one occurrence of “..” (for
example,
.BR @mail..example.com ),
this is treated as the cut between
.I d=
tag domain
.RB ( d=example.com )
and
.I i=
tag subdomain
.RB ( i=@mail.example.com ),
see below.
In column (2), a single dot (if an identity expression, a single dot after the
“@”) copies the domain of the matched sender address; a single dot before the
“@” copies the local-part of the matched sender address.
.IP
When signing a message, each entry matching an originator email address (in the
.I Sender
or
.I From
header) will result in a signature being produced and attached to the message.
Columns (2) and (3) are used to produce the
.I d=
and
.I s=
tags.
If column (2) contains an identity expression it also produces the
.I i=
tag.
The signing key referred to by name in column (4) is used to calculate the
cryptographic signature.
Finally, the optional associated signing configuration parameters in column (5)
override the main configuration settings.
.IP
Note that if the data source lookup fails, the current message transaction is
aborted with a transient SMTP error.
.TP
.BR socket " (\fIsocket-spec\fR)"
The listening socket of the milter.
This parameter is mandatory.
The
.I socket-spec
string is a description of the socket that the milter should open for the
connection from the MTA.
It can be either an IPv4/IPv6 TCP socket in the form
.BI inet: host : port
(for example,
.BR inet:localhost:3000 ),
or a UNIX domain socket in the form
.BI unix: path
(for example,
.BR unix:/run/dkim-milter.sock ).
This setting cannot be reloaded.
.TP
.BR syslog_facility " (\fIfacility\fR)"
The facility to use for syslog messages.
The facility must be one of the named facilities defined by syslog (in lower
case minus the
.B LOG_
prefix).
See
.BR syslog (3).
This setting cannot be reloaded.
The default is
.BR mail .
.TP
.BR trust_authenticated_senders " (\fIboolean\fR)"
Whether message transactions from authenticated senders are eligible for
signing.
The default is
.BR yes .
.TP
.BR trusted_networks " (\fInetworks\fR)"
Comma-separated list of network addresses whose message transactions are
eligible for signing.
Network addresses are IPv4 or IPv6 addresses and networks in CIDR notation.
The shorthand token
.B loopback
can be included to trust connections from any loopback address.
The default is
.BR loopback .
.SS Signing parameters
Signing parameters allow configuration of the signing process.
They apply when a message transaction is handled in signing mode.
These parameters can be overridden per connection, recipient, and sender.
.TP
.BR ascii_only_signatures " (\fIboolean\fR)"
Whether to only emit ASCII characters in signatures.
This parameter is mainly intended to improve interoperation when signing for an
internationalized, Unicode domain.
The default is
.BR no .
.TP
.BR canonicalization " (\fIcanonicalization\fR)"
The canonicalization algorithm to use in the
.I c=
tag.
The default is
.BR relaxed/simple .
.TP
.BR copy_headers " (\fIboolean\fR)"
Whether to record the header fields seen in the original message in the
.I z=
tag.
The default is
.BR no .
.TP
.BR default_signed_headers " (\fIcolon-separated\fR)"
The default set of headers to sign.
This set is used for value
.B default
in parameter
.BR sign_headers .
The default is not documented, but follows recommendations in RFC\~6376, section
5.4.1.
.TP
.BR default_unsigned_headers " (\fIcolon-separated\fR)"
The default set of headers to exclude from being signed.
This set is used for value
.B all
in parameter
.BR sign_headers .
The default is not documented, but follows recommendations in RFC\~6376, section
5.4.1.
.TP
.BR expiration " (\fIduration\fR | " never )
The validity period to declare in the
.I x=
tag.
The token
.B never
suppresses inclusion of an
.I x=
tag.
The default is
.BR 5d .
.TP
.BR hash_algorithm " (" sha256 " | " sha1 )
The hash algorithm to use in the
.I a=
tag.
The default is
.BR sha256 .
.IP
Value
.B sha1
is only available if DKIM Milter was compiled with the legacy compatibility
feature “pre-rfc8301”.
.TP
.BR limit_body_length " (\fIboolean\fR)"
Whether to record the length of the signed message content in the
.I l=
tag.
The default is
.BR no .
.TP
.BR oversign_headers " (\fIoversigned-headers\fR)"
Headers to oversign, that is, sign once more than actually present and signed.
The given value may be in one of the following formats:
.BR signed ,
oversign all headers already selected for signing.
.BR signed-extended ,
oversign all headers already selected for signing plus all headers configured in
.BR sign_headers ,
even if they are not present in the message header and so were not selected for
signing.
.IR colon-separated ,
the listed colon-separated headers.
The default is empty.
.TP
.BR request_reports " (\fIboolean\fR)"
Whether to include the extension tag
.I r=y
in the signature, in order to signal interest in DKIM Failure Reports
(RFC\~6651).
The default is
.BR no .
.TP
.BR sign_headers " (\fIsigned-headers\fR)"
Headers to include in the signature.
The given value may be in one of the following formats:
.BR default ,
the default set of headers, optionally followed by a semicolon and additional,
colon-separated headers to include.
.BR all ,
all headers present, minus the set of excluded headers.
.IR colon-separated ,
the listed colon-separated headers.
The default is
.BR default .
.IP
When a signature is prepared, the headers specified here are selected from the
message’s header in order from the bottom up, that is, in evaluation order.
Of headers that occur multiple times, all instances are selected.
.SS Verification parameters
Verification parameters allow configuration of the verification process.
They apply when a message transaction is handled in verifying mode.
These parameters can be overridden per connection and per recipient.
.TP
.BR allow_expired " (\fIboolean\fR)"
Whether to evaluate expired signatures as passing.
If this setting is disabled, expired signatures evaluate to result
.IR policy .
The default is
.BR no .
.TP
.BR allow_sha1 " (\fIboolean\fR)"
Whether to evaluate signatures using the SHA-1 hash algorithm as passing.
If this setting is disabled, signatures using the SHA-1 hash algorithm always
evaluate to result
.IR policy ,
regardless of the cryptographic validity of the signature.
The default is
.BR no .
.IP
This parameter is only effective if DKIM Milter was compiled with the legacy
compatibility feature “pre-rfc8301”, else it is ignored and all SHA-1 signatures
evaluate to
.I permerror
without being verified.
.TP
.BR allow_timestamp_in_future " (\fIboolean\fR)"
Whether to evaluate signatures with a timestamp in the future as passing.
The default is
.BR no .
.TP
.BR forbid_unsigned_content " (\fIboolean\fR)"
Whether to evaluate signatures that don’t cover the entire message body content
as not passing.
The default is
.BR no .
.TP
.BR max_signatures_to_verify " (\fIinteger\fR)"
Maximum number of signatures to verify in a message.
.I DKIM-Signature
header fields are selected starting from the top.
The default is
.BR 10 .
.TP
.BR min_rsa_key_bits " (\fIinteger\fR)"
The minimum allowed RSA key size in bits.
If a signature was created with an RSA key of a size below this threshold, the
signature evaluates to result
.IR policy ,
regardless of the cryptographic validity of the signature.
Note that there is an additional, mandatory hard lower limit of 1024 bits for
RSA key sizes, smaller sizes always evaluate to result
.IR permerror ,
independent of this setting.
The default is
.BR 1024 .
.IP
If DKIM Milter was compiled with the legacy compatibility feature “pre-rfc8301”,
the hard lower limit for RSA key sizes is 512 bits.
.TP
.BR reject_failures " (\fIcomma-separated\fR: " missing ", " no-pass ", " author-mismatch ", " author-mismatch-strict )
The set of signature verification results to reject with an SMTP error reply.
The value is a comma-separated set of the following failure specifications.
.BR missing ,
reject messages without DKIM signature.
.BR no-pass ,
reject messages without a passing DKIM signature.
.BR author-mismatch ,
reject messages that don’t have a passing DKIM signature where the author domain
found in the
.I From
header matches (ie, is equal to, or, unless the public key record is marked
.IR t=s ,
a subdomain of) the signing domain in the
signature’s
.I d=
tag.
.BR author-mismatch-strict ,
same as
.BR author-mismatch ,
but allows only exact domain matches, no subdomains.
The failure specifications correspond to the three DKIM failure status codes
specified in RFC\~7372, section\~3.1.
Note that a failing signature is treated as passing if the DKIM public key
record is marked as being in test mode
.RI ( t=y ).
The default is empty.
.IP
According to RFC\~6376, section\~6.3 use of this parameter is discouraged.
However, it may be useful when applied to certain known senders only, for
example, through an entry in
.BR connection_overrides .
.TP
.BR required_signed_headers " (\fIcolon-separated\fR)"
The set of headers required to be included in a signature.
A signature with missing headers evaluates to result
.IR policy .
A bare header name requires that header to be included in a signature’s
.I h=
tag at least once.
A header name followed by
.B +
also requires that
.I all
instances of that header be signed.
A header name followed by
.B *
makes the header optional, but if it is included, then
.I all
instances must be signed.
In conformance with RFC\~6376, the header
.I From
is always required to be included in a signature independent of this setting.
The default is
.BR From* .
.TP
.BR time_tolerance " (\fIduration\fR)"
Time tolerance when evaluating timestamp and expiration in signatures, in order
to allow for clock drift.
The default is
.BR 5m .
.SH FILES
.I /etc/dkim-milter/dkim-milter.conf
.SH SEE ALSO
.BR dkim-milter (8)