dkimproxy.out - SMTP proxy for adding DKIM signatures to email
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
dkimproxy.out listens on the IP address and TCP port specified by its first argument (the "listen" port), and sends the traffic it receives onto the second argument (the "relay" port), with messages getting modified to have a DKIM or DomainKeys signature.
If specified, the server will run in the background.
Use this argument to specify what domain(s) you can sign for. You may specify multiple domains by separating them with commas. If a single domain is specified, DKIMproxy will sign every message it sees with that domain, if it can. If multiple domains are specified, DKIMproxy will try to match the domain to the message's sender, and only generate a signature that will match the sender's domain.
If specified, the daemonized process will setgid() to the specified
GROUP.
If specified, any DKIM signature created will have an i= argument containing the value specified.
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.
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.
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.
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.
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.
This is a required argument. Use it to specify the name of the key selector.
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.
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=private.key)
The syntax for specifying per-signature options is described in more detail in the section below titled SENDER MAP FILE.
If specified, the daemonized process will setuid() to USER after
completing any necessary privileged operations, but before accepting
connections.
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.
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
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. The following signature parameters are recognized:
the private key file to use
the algorithm to use
the canonicalization method to use
the domain to use, default is to use the domain matched
the identity to use, default is to not include an i= parameter
the selector to use
This works very much like a sender map file, except it selects based on the "List-Id" header rather than the "Sender" or "From" header. You can match on the full list-id value, or just a suffix. Here is an example file:
kernel.org dkim(d=kernel.org) xorg-devel.lists.x.org dkim(d=lists.x.org) dev.spamassassin.apache.org dkim(d=apache.org)
For details on the syntax of the right-hand values, see SENDER MAP FILE above.
If no "List-Id" header is found in the message to be signed, or no entry in the map file matches the found "List-Id" header, then DKIMproxy will proceed as if no listid_map option was specified. That is, it will add the default signature (if a "domain" or "signature" option was specified), or leave the message as is.
Jason Long