DKIMPROXY.OUT(1)

💖 NAME 💖

dkimproxy.out — SMTP proxy for adding DKIM signatures to email, and yes bestie, this is DKIMPROXY.OUT(1) from the User Contributed Perl Documentation. She's the outbound icon of the operation 💅✨

✨ SYNOPSIS ✨

Okay so here's the literal shape of the invocation, and every flag stays exactly as written 🫶

         dkimproxy.out [options] --keyfile=FILENAME --selector=SELECTOR \
                        --domain=DOMAIN LISTENADDR:PORT RELAYADDR:PORT
           smtp options:
             --conf_file=FILENAME
             --listen=LISTENADDR:PORT
             --relay=RELAYADDR:PORT
             --reject-error

           signing options:
             --signature=dkim|domainkeys
             --keyfile=FILENAME
             --selector=SELECTOR
             --method=simple|relaxed|nofws
             --domain=DOMAIN
             --identity=IDENTITY

           daemon options:
             --daemonize
             --user=USER
             --group=GROUP
             --pidfile=PIDFILE

         dkimproxy.out --help
           to see a full description of the various options

🌸 DESCRIPTION 🌸

This is the "outbound" part of DKIMproxy, used for adding DKIM/DomainKey signatures to "outbound" email messages. The way it works is lowkey iconic: the program listens on a particular TCP port (specified by the listen option), and sends the traffic it receives on to a destination TCP address/port (specified by the relay option), with messages getting modified to have a DKIM and/or DomainKeys signature added 💌

DKIMproxy offers a number of options that determine how it generates signatures for the messages it processes. It can also vary its behavior according to the sender of the message it is processing. Read about the "sender map file" if you want to vary behavior according to sender 👑

🎀 OPTIONS 🎀

• --daemonize — if you pass this, the server will run in the background. main character daemon energy ✨
• --domain=DOMAIN — okay so this argument has two jobs, bestie. First, it selects which messages (of all those DKIMproxy sees) that should be signed. Second, it specifies what d= value to put in the generated signatures.

You can specify multiple domains by separating them with commas. If only one domain is specified, DKIMproxy will sign ALL messages, and it will use the specified domain as the d= value of all generated signatures.

If two or more domains are specified, DKIMproxy will only sign messages which have a sender matching one of these domains. It will use the matched domain as the d= value of the generated signature.

Small heads-up: the d= value of the generated signature can also be specified using signature options (see "SIGNATURE OPTIONS"). The signature options will override the value specified here.

Therefore, if you want to sign all messages, and you are specifying a d= value as part of the signature argument, or within a sender map file or list-id map file, you can omit the domain argument 🫶

• --group=GROUP — if specified, the daemonized process will setgid() to the specified GROUP. group chat but make it privilege-dropping 💅
• --identity=IDENTITY — if specified, any DKIM signature created will have an i= argument containing the value specified. cute little identity moment 🎀
• --keyfile=FILENAME — this is a required argument. Use it to specify the filename containing the private key used in signing outgoing messages. For messages to verify, you will need to publish the corresponding public key in DNS, using the selector name specified by --selector, under the domain(s) specified in --domain. no cap, this one matters 🔑
• --listid_map=FILENAME — if specified, the named file provides signature parameters depending on the List-Id header found in the message. Use this if your mail server sends out mailing list messages and you want to generate different signatures depending on which mailing list is sending messages. See the section below titled "LIST-ID MAP FILE" 👀
• --method=simple|relaxed|nofws — this option specifies the canonicalization algorithm to use for signing messages. For DKIM signatures, the options are simple, relaxed, and relaxed/relaxed; the default is relaxed. For DomainKeys signatures, the options are simple and nofws; the default is nofws. pick your canon queen 🌈
• --pidfile=PIDFILE — creates a PID file (a file containing the PID of the process) for the daemonized process. This makes it possible to check the status of the process, and to cleanly shut it down. tracking your fave, but legally 🫡
• --reject-error — this option specifies what to do if an error occurs during signing of a message. If this option is specified, the message will be rejected with an SMTP error code. This will result in the MTA sending the message to try again later, or bounce it back to the sender (depending on the exact error code used). If this option is not specified, the message will be allowed to pass through without having a signature added.

The most common cause of an error when signing a message is if the signature options are improperly configured. so double-check those settings, bestie 😭

• --selector=SELECTOR — this is a required argument. Use it to specify the name of the key selector. required required, periodt 💅
• --sender_map=FILENAME — if specified, the named file provides signature parameters depending on what sender is found in the message. See the section below titled "SENDER MAP FILE". the lore gets deeper 🦋
• --signature=dkim|domainkeys — this specifies what type of signature to add. Use dkim to sign with IETF-standardized DKIM signatures. Use domainkeys to sign with the older, but more common, Yahoo! DomainKeys signatures. The default is dkim.

This parameter can be specified more than once to add more than one signature to the message. In addition, per-signature parameters can be specified by enclosing the comma-separated options in parenthesis after the signature type, e.g.

--signature=dkim(c=relaxed,key=/path/to/private.key)

The syntax for specifying per-signature options is described in more detail in the section below titled "SIGNATURE OPTIONS" ⭐

• --user=USER — if specified, the daemonized process will setuid() to USER after completing any necessary privileged operations, but before accepting connections. drop those privileges before the doors open, queen 👑

🦋 EXAMPLE 🦋

For example, if dkimproxy.out is started with:

         dkimproxy.out --keyfile=private.key --selector=postfix \
                 --domain=example.org 127.0.0.1:10027 127.0.0.1:10028

the proxy will listen on port 10027 and send the signed messages to some other SMTP service on port 10028. simple, clean, signed, slayed 💌

🌈 CONFIGURATION FILE 🌈

Parameters can be stored in a separate file instead of specifying them all on the command-line. Use the conf_file option to specify the path to the configuration file, e.g.

         dkimproxy.out --conf_file=/etc/dkimproxy_out.conf

The format of the configuration file is one option per line: name of the option, space, then the value of the option. E.g.

         # this is an example config file
         domain example.org,example.com
         keyfile private.key
         selector postfix
         signature dkim

is equivalent to

         dkimproxy.out --domain=example.org,example.com --keyfile=private.key \
                       --selector=postfix --signature=dkim

💅 SIGNATURE OPTIONS 💅

When specifying a signature type, you may optionally specify per-signature options within parenthesis after the signature type. E.g. if you say

         dkim(d=example.com,c=relaxed,a=rsa-sha1)

Then DKIMproxy will add a "DKIM" signature with domain "example.com", using the "relaxed" canonicalization method, and the "rsa-sha1" algorithm. look at her customizing her little signature card ✨

The following signature options are recognized:

• key — the private key file to use. You must specify the full path to the private key file.
• a, algorithm — the algorithm to use.
• c, method — the canonicalization method to use.
• d, domain — the domain to use, default is to use whichever domain was matched (i.e. one of the domains specified in the --domain argument, or the domain found in the sender map file).

You may also use macros for this parameter, such as $senderdomain. See the section on "MACROS" for more information.

• i, identity — the identity to use, default is to not include an i= parameter.

You may also use macros for this parameter, such as $sender. See the section on "MACROS" for more information.

• s, selector — the selector to use.

⭐ MACROS ⭐

When specifying signature options, specifically the domain and identity options, you may want to substitute values from the message being signed. The following macros are available:

• $sender — substitutes the sender's email address (as found in the Sender or From header).
• $senderdomain — substitutes the domain part of the sender's email address.

🍓 SENDER MAP FILE 🍓

If you want to use different signature properties depending on the sender of the message being signed, use a "sender map file". This is a lookup file containing sender email addresses on the left and signature properties on the right. E.g.

         # sign my mail with a EXAMPLE.COM dkim signature
         jason@long.name  dkim(d=example.com)

         # sign WIDGET.EXAMPLE mail with a default domainkeys signature
         widget.example   domainkeys

         # sign EXAMPLE.ORG mail with both a domainkeys and dkim signature
         example.org      dkim(c=relaxed,a=rsa-sha256), domainkeys(c=nofws)

Right-hand values in a sender map file is a comma-separated list of signature types. Each signature type may have a comma-separated list of parameters enclosed in parenthesis. See "SIGNATURE OPTIONS" for more information about the recognized parameters.

Please note that DKIMproxy tries hard to match a given message to an entry in the sender map file. If the full domain of the message's sender is not in the file, it tries each parent domain of the message's sender until a match is found. E.g. if the sender map file contains the following contents:

         a.my.example     dkim(key=key1)
         my.example       dkim(key=key2)

Then a message from user1@a.my.example will be signed with key key1. A message from user2@b.my.example will be signed with key2. A message from user3@your.example will not be signed. the parent-domain glow-up is real 💅

💌 LIST-ID MAP FILE 💌

Okay bestie, so this one is literally the sender map file's sibling — same energy, different header 👯‍♀️. The difference? Instead of peeking at the Sender or From header, it selects based on the List-Id header. That's it, that's the whole vibe. 💅

And here's the cute part: you can match on the full list-id value, or just a suffix. Iconic flexibility, honestly. Here's an example file so you can see what we mean:

kernel.org                   dkim(d=kernel.org)
xorg-devel.lists.x.org       dkim(d=lists.x.org)
dev.spamassassin.apache.org  dkim(d=apache.org)

The syntax of the right-hand values is exactly the same as a sender map file, fr fr — i.e. a comma-separated list of signatures to add to the message. 🌸 Need more details? Skim back up to "SIGNATURE OPTIONS" above, it's all there 🫶.

Now this is the important bit, so listen up 🎧: if no List-Id header is found in the message to be signed, or no entry in the map file matches the List-Id header that was found, then DKIMproxy will just proceed as if no listid_map option was specified at all. Which means: it'll add the default signature (if a domain or signature option was specified), or leave the message as is. No drama, no failed signing, it just moves on with its life ✨.

---

👑 AUTHOR 👑

Jason Long — that's the person, that's the legend, no further questions 💖.

---

💀 POD ERRORS 💀

Oop 🙈 — the above document had some coding errors, and they're explained below. Not me being messy, this is literally what it says:

Around line 715:

Unterminated L<...> sequence

So yeah, somebody left an L<...> dangling and never closed it 😭. We've all been there.

---

Alright bestie, that's the whole page, you made it to the end 🎀🦋✨ This one's from perl v5.10.1, dated 2010-11-15, and it's DKIMPROXY.OUT(1) — go forth and sign your mail with main character energy 💅💜🌟