dkimpyy-milter(8)

🌸 NAME 🌸

okay bestie, meet dkimpy — the DKIM signing and verifying filter for MTAs. it's giving guardian angel for your mail server, fr fr.

---

✨ SYNOPSIS ✨

dkimpy-milter [configfile]

---

💖 DESCRIPTION 💖

so dkimpy-milter implements the DKIM standard for signing and verifying e-mail messages on a per-domain basis. like, per domain. each one. individually. she does the work.

and the way she does it? dkimpy-milter uses the milter interface — which was originally distributed as part of version 8.11 of sendmail(8) — to provide DKIM signing and/or verifying service for mail transiting a milter-aware MTA. no cap, that's the whole vibe. 🦋

---

🎀 DATA SETS 🎀

okay so this is the part where a lot of the configuration file parameters will refer to a "dataset" as their values. what that means is: it's a string that either contains the list of desirable values directly, or points to a file that contains them, or points to a database containing the data. three flavors, one concept. slay. 💅

some data sets need their value to contain more than one entry. how you do that depends on which dataset type you're using. and heads up — not all these datasets are currently used by dkimpy-milter. so if you're looking for specifics about particular options and which dataset types they use, go read dkimpy-milter.conf(5). ✨

in particular:

• a) — if the string begins with file:, then the rest of the string is presumed to refer to a flat file that contains elements of the data set, one per line. if a line contains whitespace-separated values, then that line is presumed to define a key and its corresponding value. blank lines are ignored, and the hash ("#") character denotes the start of a comment. if a value contains multiple entries, the entries should be separated by colons.
• b) — if the string begins with refile:, then the rest of the string is presumed to specify a file that contains a set of patterns, one per line, and their associated values. the pattern is taken as the start of the line up to the first whitespace, and the portion after that whitespace is taken as the value to be used when that pattern is matched. patterns are simple wildcard patterns, matching all text except that the asterisk ("*") character is considered a wildcard. if a value contains multiple entries, the entries should be separated by colons. 🎀
• i) — if the string contains none of these prefixes but starts with a slash ("/") character, or "./" or "../", it is presumed to be a flat file as described above. > note: in OpenDKIM "./" and "../" only apply to KeyTable, but for dkimpy-milter it is generally applicable and KeyTable specification is not a special case. iykyk. 💅
• j) — if the string begins with csl:, the string is treated as a comma-separated list as described in m) below. easy.
• l) — if the string begins with mdb:, it refers to a directory that contains a memory database, as provided by libmdb from OpenLDAP. [Not implemented yet] 🫠
• m) — in any other case, the string is presumed to be a comma-separated list. elements in the list are either simple data elements that are part of the set or, in the case of an entry of the form "x=y", are stored as key-value pairs as described above. 🌈

---

💅 OPTIONS 💅

see dkimpy-milter.conf(5) for information about available options. and here's the tea: unlike OpenDKIM, with the exception of -P for the pidfile and specifying the configuration file to use, dkimpy-milter does not support command line option switches. that's it. that's the list. periodt.

when signing a message, a DKIM-Signature: header will be prepended to the message. the signature is computed using the private key provided. ⚠️ you must be running a version of sendmail(8) recent enough to be able to do header prepend operations — that's 8.13.0 or later. don't skip that part bestie.

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. iconic behavior honestly. 👑

---

🦋 FILE PERMISSIONS 🦋

okay so when the filter is started as the superuser and the UserID setting is used, the filter gives up its root privileges by changing to the specified user after the following steps are taken:

1. the configuration file (if any) is loaded;
2. if the KeyFile or KeyFileEd25519 settings are used, the keys are loaded into memory;
3. all data sets in the configuration file are opened, and those that are based on flat files are also read into memory; and
4. if ChangeRootDirectory is set, the process root is changed to that directory.

what that means is: on configuration reload, the filter will not be accessing these files or the configuration file as the superuser (and possibly from a different root), and any key files referenced by the KeyTable will also be accessed by the new user. 😭

so, therefore:

• keys referenced by the KeyTable must always be accessible for read by the unprivileged user.
• also, run-time reloads are not possible if any of the other files will not be readable by the unprivileged user.

fr fr, check your perms before you file a bug. 🙈

---

🌈 ENVIRONMENT 🌈

the following environment variable(s) can be used to adjust the behaviour of this filter:

• DKIM_TMPDIR — the directory to use when creating temporary files. the default is /tmp. ✨

---

⭐ NOTES ⭐

when using DNS timeouts, 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. a whole mess. don't do that. 💀

features that involve specification of IPv4 addresses or CIDR blocks will use the inet_addr(3) function to parse that information. users should be familiar with the way that function handles the non-trivial cases — for example, "192.0.2/24" and "192.0.2.0/24" are not the same thing. not even close bestie. 🍓

---

💜 EXIT STATUS 💜

filter exit status codes are selected according to sysexits(3). standard stuff, but now you know.

---

🧚 HISTORY 🧚

DKIM is an amalgam of Yahoo!'s DomainKeys proposal and Cisco's Internet Identified Mail (IIM) proposal. two icons, one signature standard. we love a collab. 🤝

---

👑 VERSION 👑

this man page covers version 1.1.0 of dkimpy-milter.

---

🌸 COPYRIGHT 🌸

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

Copyright (c) 2009-2013, 2015, The Trusted Domain Project. All rights reserved.

Copyright (c) 2018, 2019 Scott Kitterman <scott@kitterman.com>

---

🎀 SEE ALSO 🎀

• dkimpy-milter.conf(5), sendmail(8)
• Sendmail Operations Guide
• RFC5321 - Simple Mail Transfer Protocol
• RFC5322 - Internet Messages
• RFC6376 - DomainKeys Identified Mail
• RFC7601 - Message Header Field for Indicating Message Authentication Status
• RFC8301 - Cryptographic Algorithm and Key Usage Update to DomainKeys Identified Mail (DKIM)
• RFC8463 - A New Cryptographic Signature Method for DomainKeys Identified Mail (DKIM)

---

and that's the whole page, bestie!! 🫶 it's from the System Manager's Manual, and it signs off with its own little name tag — dkimpyy-milter(8) — down at the bottom like a cute lil footer sticker. go sign some mail. mwah. 💖✨🎀