.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DKIMPROXY.OUT 1"
.TH DKIMPROXY.OUT 1 "2009-07-12" "perl v5.10.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
dkimproxy.out \- SMTP proxy for adding DKIM signatures to email
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 7
\&  dkimproxy.out [options] \-\-keyfile=FILENAME \-\-selector=SELECTOR \e
\&                 \-\-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
\&      \-\-identity=IDENTITY
\&
\&    daemon options:
\&      \-\-daemonize
\&      \-\-user=USER
\&      \-\-group=GROUP
\&      \-\-pidfile=PIDFILE
\&
\&  dkimproxy.out \-\-help
\&    to see a full description of the various options
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
dkimproxy.out listens on the \s-1IP\s0 address and \s-1TCP\s0 port specified by its
first argument (the \*(L"listen\*(R" port), and sends the traffic it receives
onto the second argument (the \*(L"relay\*(R" port), with messages getting
modified to have a \s-1DKIM\s0 or DomainKeys signature.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-\-daemonize\fR" 4
.IX Item "--daemonize"
If specified, the server will run in the background.
.IP "\fB\-\-domain=DOMAIN\fR" 4
.IX Item "--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 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.
.IP "\fB\-\-group=GROUP\fR" 4
.IX Item "--group=GROUP"
If specified, the daemonized process will \fIsetgid()\fR to the specified
\&\s-1GROUP\s0.
.IP "\fB\-\-identity=IDENTITY\fR" 4
.IX Item "--identity=IDENTITY"
If specified, any \s-1DKIM\s0 signature created will have an i= argument
containing the value specified.
.IP "\fB\-\-keyfile=FILENAME\fR" 4
.IX Item "--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
\&\s-1DNS\s0, using the selector name specified by \f(CW\*(C`\-\-selector\*(C'\fR, under
the domain(s) specified in \f(CW\*(C`\-\-domain\*(C'\fR.
.IP "\fB\-\-method=simple|nowsp|relaxed|nofws\fR" 4
.IX Item "--method=simple|nowsp|relaxed|nofws"
This option specifies the canonicalization algorithm to use for signing
messages. For \s-1DKIM\s0 signatures, the options are \f(CW\*(C`simple\*(C'\fR, \f(CW\*(C`nowsp\*(C'\fR, or
\&\f(CW\*(C`relaxed\*(C'\fR; the default is \f(CW\*(C`relaxed\*(C'\fR. For DomainKeys signatures, the
options are \f(CW\*(C`simple\*(C'\fR and \f(CW\*(C`nofws\*(C'\fR; the default is \f(CW\*(C`nofws\*(C'\fR.
.IP "\fB\-\-pidfile=PIDFILE\fR" 4
.IX Item "--pidfile=PIDFILE"
Creates a \s-1PID\s0 file (a file containing the \s-1PID\s0 of the process) for
the daemonized process. This makes it possible to check the status
of the process, and to cleanly shut it down.
.IP "\fB\-\-reject\-error\fR" 4
.IX Item "--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 \s-1SMTP\s0 error code. This will result in the \s-1MTA\s0 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.
.Sp
The most common cause of an error when signing a message is if the
signature options are improperly configured.
.IP "\fB\-\-selector=SELECTOR\fR" 4
.IX Item "--selector=SELECTOR"
This is a required argument. Use it to specify the name of the key
selector.
.IP "\fB\-\-sender_map=FILENAME\fR" 4
.IX Item "--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"\s-1SENDER\s0 \s-1MAP\s0 \s-1FILE\s0\*(R".
.IP "\fB\-\-signature=dkim|domainkeys\fR" 4
.IX Item "--signature=dkim|domainkeys"
This specifies what type of signature to add. Use \f(CW\*(C`dkim\*(C'\fR to sign with
IETF-standardized \s-1DKIM\s0 signatures. Use \f(CW\*(C`domainkeys\*(C'\fR to sign with
the older, but more common, Yahoo! DomainKeys signatures.
The default is \f(CW\*(C`dkim\*(C'\fR.
.Sp
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.
.Sp
.Vb 1
\&  \-\-signature=dkim(c=relaxed,key=private.key)
.Ve
.Sp
The syntax for specifying per-signature options is described in more
detail in the section below titled \*(L"\s-1SENDER\s0 \s-1MAP\s0 \s-1FILE\s0\*(R".
.IP "\fB\-\-user=USER\fR" 4
.IX Item "--user=USER"
If specified, the daemonized process will \fIsetuid()\fR to \s-1USER\s0 after
completing any necessary privileged operations, but before accepting
connections.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
For example, if dkimproxy.out is started with:
.PP
.Vb 2
\&  dkimproxy.out \-\-keyfile=private.key \-\-selector=postfix \e
\&          \-\-domain=example.org 127.0.0.1:10027 127.0.0.1:10028
.Ve
.PP
the proxy will listen on port 10027 and send the signed messages to
some other \s-1SMTP\s0 service on port 10028.
.SH "CONFIGURATION FILE"
.IX Header "CONFIGURATION FILE"
Parameters can be stored in a separate file instead of specifying
them all on the command-line. Use the \f(CW\*(C`conf_file\*(C'\fR option to specify
the path to the configuration file, e.g.
.PP
.Vb 1
\&  dkimproxy.out \-\-conf_file=/etc/dkimproxy_out.conf
.Ve
.PP
The format of the configuration file is one option per line:
name of the option, space, then the value of the option. E.g.
.PP
.Vb 5
\&  # this is an example config file
\&  domain example.org,example.com
\&  keyfile private.key
\&  selector postfix
\&  signature dkim
.Ve
.PP
is equivalent to
.PP
.Vb 2
\&  dkimproxy.out \-\-domain=example.org,example.com \-\-keyfile=private.key \e
\&                \-\-selector=postfix \-\-signature=dkim
.Ve
.SH "SENDER MAP FILE"
.IX Header "SENDER MAP FILE"
If you want to use different signature properties depending on the
sender of the message being signed, use a \*(L"sender map file\*(R". This
is a lookup file containing sender email addresses on the left
and signature properties on the right. E.g.
.PP
.Vb 2
\&  # 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)
.Ve
.PP
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:
.IP "key" 4
.IX Item "key"
the private key file to use
.IP "a" 4
.IX Item "a"
the algorithm to use
.IP "c" 4
.IX Item "c"
the canonicalization method to use
.IP "d" 4
.IX Item "d"
the domain to use, default is to use the domain matched
.IP "i" 4
.IX Item "i"
the identity to use, default is to not include an i= parameter
.IP "s" 4
.IX Item "s"
the selector to use
.SH "AUTHOR"
.IX Header "AUTHOR"
Jason Long