Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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

perl v5.32.1			  2021-03-01		      DKIMPROXY.OUT(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLE | CONFIGURATION FILE | SIGNATURE OPTIONS | MACROS | SENDER MAP FILE | LIST-ID MAP FILE | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dkimproxy_out&sektion=8&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help