NAME
dkimproxy.out - SMTP proxy for adding DKIM signatures to email
DESCRIPTION
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.
SYNOPSIS
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|nowsp|relaxed|nofws
--domain=DOMAIN
daemon options:
--daemonize
--user=USER
--group=GROUP
--pidfile=PIDFILE
--min_servers=NUM
dkimproxy.out --help
to see a full description of the various options
OPTIONS
--daemonize
If specified, the server will run in the background.
--domain=DOMAIN
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 always use that domain to sign, 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.
--group=GROUP
If specified, the daemonized process will setgid() to the specified
GROUP.
--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 C<--selector>, under the domain(s)
specified in C<--domain>.
--method=simple|nowsp|relaxed|nofws
This option specifies the canonicalization algorithm to use for signing
messages. For DKIM signatures, the options are C<simple>, C<nowsp>, or
C<relaxed>; the default is C<relaxed>. For DomainKeys signatures, the
options are C<simple> and C<nofws>; the default is C<nofws>.
--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.
--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.
--selector=SELECTOR
This is a required argument. Use it to specify the name of the key
selector.
--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
L</"SENDER MAP FILE">.
--signature=dkim|domainkeys
This specifies what type of signature to add. Use C<dkim> to sign with
IETF standardized DKIM signatures. Use C<domainkeys> to sign with the
older, but more common, Yahoo! DomainKeys signatures. The default is
C<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 L</"SENDER MAP FILE">.
--user=USER
If specified, the daemonized process will setuid() to USER after
completing any necessary privileged operations, but before accepting
connections.
--min_servers=NUM
Number of process that DKIMproxy shall spawn and get ready for signing.
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.
CONFIGURATION FILE
Parameters can be stored in a separate file instead of specifying them
all on the command line. Use the C<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
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. The following signature parameters
are recognized:
key
the private key file to use
a
the algorithm to use
c
the canonicalization method to use
d
the domain to use, default is to use the domain matched
s
the selector to use
SEE ALSO
dkimproxy.in(8), dkim_responder(8), dkimsign(8), dkimverify(8)
dkimproxy.out(8)