DKIMPROXY.OUT(1) User Contributed Perl Documentation DKIMPROXY.OUT(1)NAME
dkimproxy.out - SMTP proxy for adding DKIM signatures to email
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|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. This 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 specified, the server will run in the background.
--domain=DOMAIN
This argument serves two purposes. 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.
Please note that 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.
--identity=IDENTITY
If specified, any DKIM signature created will have an i= argument
containing the value specified.
--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".
--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".
--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.
The most common cause of an error when signing a message is if the
signature options are improperly configured.
--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 "SENDER MAP FILE".
--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.
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 "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.
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.
LIST-ID MAP FILE
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)
The syntax of the right-hand values is the same as a sender map file,
i.e. a comma-separated list of signatures to add to the message. For
more details, see "SIGNATURE OPTIONS" 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.
AUTHOR
Jason Long
POD ERRORS
Hey! The above document had some coding errors, which are explained
below:
Around line 715:
Unterminated L<...> sequence
perl v5.10.1 2010-11-15 DKIMPROXY.OUT(1)
