dkimpy-milter.conf(5)

📦
version 1.2.3 · 2 versions
  • 1.2.3 · debian bookworm, debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
  • 1.2.2 · ubuntu jammy
, in debian bookworm, debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🌸 dkimpy-milter.conf 💖

(this is the dkimpy-milter.conf(5) page, bestie — File Formats Manual energy ✨)

✨ NAME ✨

dkimpy-milter — the Python milter that does DKIM signing and validation, no cap 👑

🎀 VERSION 🎀

1.2.0

💅 DESCRIPTION 💅

Okay so dkimpy-milter(8) implements the DKIM specification for signing and verifying e-mail messages on a per-domain basis. And this file? This file is its configuration file. Periodt.

Blank lines are ignored. Lines containing a hash ("#") character are truncated at the hash character, which is how you get 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. That's the whole vibe.

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. Not a thing. Don't try it, bestie.

🌈 USAGE 🌈

Usage:

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

🦋 OTHER DOCUMENTATION 🦋

This documentation assumes you have read Postfix's README_FILES/MILTER_README (or the Sendmail equivalent) and are generally familiar with Domain Keys Identified Mail (DKIM). See RFC 6376 for the deets, iykyk.

⭐ SYNOPSIS ⭐

dkimpy-milter operates with a default installed configuration file and a 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 though. If an unsupported option from OpenDKIM is specified, an error will be raised. So like, it will tell you.

💜 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. cute, right?
  • 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, so it's not up to you there. 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. slay 💅
  • 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 of 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. the way that this is a whole workaround 😭

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. fr fr, Mode is the main character here 🔥

  • MinimumKeyBits (integer) — establishes a minimum key size for acceptable RSA signatures. Signatures with smaller key sizes, even if they otherwise pass DKIM validation, will be 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) — okay so this one is a whole set of header fields that should be omitted when you’re generating signatures. If any entry names a header field that the DKIM spec says is mandated, that entry just gets ignored, periodt. The DKIM spec (RFC6376, Section 5.4) lists a bunch of header fields as “SHOULD NOT” be signed, and the default list for this parameter contains exactly those: Return-Path, Received, Comments, Keywords, Bcc, Resent-Bcc, and DKIM-Signature. Want to omit no headers? Just use the string "." (or literally any string that won’t match any header field names). And if you specify a list, it replaces the default entirely — unless one entry is "*", in which case the list is treated as a delta to the default. So like "*,+foobar" means the entire default list plus foobar, while "*,-Bcc" means the entire default list except Bcc. 💖
🚨 NOT IMPLEMENTED: OmitHeaders is included for reference only, bestie. Don’t come for me.
  • DNSOverride (string) — give it a text string, and a verifying milter will use that instead of consulting the DNS on each message. It’s mainly for testing when changing your system’s DNS resolution is awkward. Do not use this in production, fr fr. 🙈
  • DNSTimeout (integer) — sets the DNS timeout in seconds. A value of 0 causes no wait (yes, that’s different from opendkim). Default is 5. Also peep the NOTES section below. ⏱️
  • PeerList (dataset) — this identifies a set of “peers” — clients whose connections get accepted without processing by this filter. Each line should have a hostname, domain name (like .example.com), IP address, IPv6 address (including an IPv4 mapped address), or a CIDR-style IP spec (like 192.168.1.0/24). An entry starting with a bang (!) means “not”, so you can exclude specific hosts that would otherwise be in a bigger set. Host and domain names are matched first, then the IP or IPv6 address depending on connection type. More precise entries win over less precise ones — so 192.168.1.1 matches before !192.168.1.0/24. IPv6 text form gets forced to lowercase when queried (RFC5952), so keep your data set lowercase too. The IP address part can optionally have square brackets; both forms get checked. 🦋
🚨 NOT IMPLEMENTED: PeerList is included for reference only.
  • PidFile (string) — path to a file that gets created at process start, containing the process ID. If you don’t specify it, no such file is created. No cap. 📝
  • Selector (string) — defines the name of the selector used when signing messages with RSA. Check the DKIM spec for the deets. This is only used when signing with a single key — see the SigningTable parameter below for more. This parameter is ignored if a KeyTable is defined. 🔑
  • SelectorEd25519 (string) — same vibe but for signing messages with Ed25519. See the DKIM spec. Used only when signing with a single key; see SigningTable below. This parameter is ignored if a KeyTableEd25519 is defined. ✨
  • SignHeaders (dataset) — the set of header fields that should be included when generating signatures. If your list omits any header field the DKIM spec mandates, those fields get implicitly added. By default, the fields the DKIM spec says “SHOULD” be signed (RFC6376, Section 5.4) will be signed by the filter. See the OmitHeaders configuration option for more about the format and interpretation of this field. 📝
  • SigningTable (dataset) — this defines a table used to pick a signing identity for a message based on the address in the From: header field. Keys vary depending on the table type; values should include one field with a name found in the KeyTable (see above) that says which key to use when generating the signature, plus an optional second field naming the signer of the message that’ll be included in the "i=" tag in the generated signature. Note: 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 gets replaced by the domain found in the From: header field. Same for any % in the optional second field. If this table specifies a regular expression file ("refile"), then the keys are wildcard patterns matched against the address in From:. Entries are checked in the order they appear in the file. Note: these are <em>not</em> true regular expressions — the terminology is inherited from opendkim, and only wildcards ("*") are supported. For all other database types, the full user@host is checked first, then just 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) — the socket the filter should establish to receive connections from postfix(1) and provide service. socketspec is one of two forms: local:path creates a UNIX domain socket at the specified path, or inet:port[@host] / inet6:port[@host] creates a TCP socket on the specified port and in the specified protocol family. If the host isn’t given as a hostname or IP address, the socket listens 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 any interesting activity via calls to syslog(3). 📋
  • SyslogFacility (string) — log via calls to syslog(3) using the named facility. Facility names are the same as those allowed in syslog.conf(5). Default is "mail". 📬
  • SyslogSuccess (Boolean) — log additional entries via syslog(3) indicating successful signing or verification of messages. ✅
  • UMask (integer) — requests a specific permissions mask for file creation. This really only applies to creating the socket when Socket specifies a UNIX domain socket, and to the PidFile (if any). Temporary files are created by mkstemp(3), which enforces a specific file mode on creation regardless of the process umask. See umask(2) for more. 🔒
  • UserID (string) — tries to become the specified userid before starting operations. The value is userid[:group]. The process gets all the groups and the primary group ID of the named userid unless an alternate group is specified. 🫶

📝 NOTES 📝

When you’re using DNS timeouts (peep DNSTimeout above), make sure your timeout isn’t larger than the timeout used for interaction between sendmail and the filter. Otherwise the MTA could abort a message while waiting for a reply from the filter, which is itself still waiting for a DNS reply. Remember the timeout is per DNS lookup, so total DNS wait time can be way longer than the value in DNSTimeout. There’s one lookup for the InternalHosts option if it’s in use, and one for DKIM public key record lookup for each algorithm per signature per message (so 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’s 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.

That’s the tea, bestie! This was dkimpy-milter.conf(5), dated 2019-04-25 — go forth and sign with main character energy. 💅✨🦋

📦 where this page comes from