.TH qmail-dk 8
.SH NAME
qmail-dk \- sign/verify and queue a mail message for delivery
.SH SYNOPSIS
.B qmail-dk
.SH DESCRIPTION
.B qmail-dk
has the same interface as
.B qmail-queue
except that it inserts an appropriate DomainKeys header before it
queues the message.  There are two separate ways to invoke
.BR qmail-dk .
For one way, you can patch qmail with the http://qmail.org/qmailqueue
patch and set QMAILQUEUE to point to qmail-dk in the environment when
you send or receive email.
For another way, you can rename qmail-queue to qmail-queue.orig, and set DKQUEUE=bin/qmail-queue.orig.

.B qmail-dk
supports DomainKey signing and verification.  It uses the libdomainkey
and OpenSSL libraries.  To sign a message, set the
.B DKSIGN
environment variable to the pathname to the private key that will be
used to sign the message.  If there is a % character in the environment
variable, it is removed and replaced by the domain name in the From: header.
If, after substituting the %, that file does not exist, the message will not be signed.
If there is no % and the file does not exist, the message will be rejected with error 32.
The selector will be taken from the
basename of the file.  The private key should be created by 
.BR dknewkey ,
which comes with libdomainkey.

To verify a message, set the
.B DKVERIFY
environment variable to a desired set of letters.  Precisely, if you
want a libdomainkey return status to generate an error, include that
letter, where A is the first return status (DK_STAT_OK), B is the
second (DK_STAT_BADSIG), etc.  The letter should be uppercase if you
want a permanent error to be returned (exit code 13), and lowercase if
you want a temporary error to be returned (exit code 82).

For example, if you want to permanently reject messages that have a
signature that has been revoked, include the letter 'K' in the
.B DKVERIFY
environment variable.  A conservative set of letters is
.BR DEGIJKfh .
Reject permanently BADSIG, NOKEY, BADKEY, SYNTAX, ARGS, REVOKED, and
INTERNAL errors, and temporarily CANTVRFY and NORESOURCE.  Add in
.B B
if you want to reject messages that have a signature that doesn't
verify (presumably because the message is a forgery or has been
damaged in transit.  Note that
.B qmail-dk
always inserts the 
.B DomainKey-Status
header, so that messages can be
rejected at delivery time, or in the mail reader.

Typically, you would sign messages generated on-host by setting
.B DKSIGN
in the environment before running an email program.  DKSIGN will be carried
through qmail's sendmail emulation through 
.B qmail-inject
to
.BR qmail-dk .
You would also set it for
.B qmail-smtpd
at the same time
.B RELAYCLIENT
is set, most often in the tcpserver cdb file.  If a host is authorized
to relay, you probably want to sign messages sent by that host.
.B DKVERIFY
should be set for all other hosts.

If neither
.B DKSIGN
nor
.B DKVERIFY
are set, then
.B DKSIGN
will be set to /etc/domainkeys/%/default.  If such a private key exists, it will be used to sign the domain.

.B qmail-dk
will ordinarily spawn qmail-queue, but if DKQUEUE is set in the environment,
the program that it points to will be executed instead.  If DKQUEUE is not set, and
.B qmail-dk
has been invoked as
.B qmail-queue
then
.B qmail-queue.orig
is spawned instead.

.SH "EXIT CODES"
.B qmail-dk
returns the same exit codes as qmail-queue with these additions:
.TP 5
.B 32
The private key file does not exist.
.TP 5
.B 57
Trouble waiting for qmail-queue to exit.
.TP 5
.B 58
Unable to vfork.
.TP 5
.B 59
Unable to create a pipe to qmail-queue.
.SH "SEE ALSO"
addresses(5),
envelopes(5),
qmail-header(5),
qmail-inject(8),
qmail-qmqpc(8),
qmail-queue(8),
qmail-send(8),
qmail-smtpd(8)