.TH s/qmail: qmail-dkverify 8
.SH "NAME"
qmail-dkverify \- verification of DKIM signatures in messages upon receipt
.SH "SYNOPSIS"
.B qmail-dkverify
.SH "DESCRIPTION"
.B qmail-dkverify
is invoked faciliting the
.I QMAILQUEUE(_EXTRA)
mechanism.

.SH "CALLING CHAIN"
Verifying DKIM signatures upon receipt involves the
following calling chain:

1. 
.B qmail-smtpd 
called from 
.B sslserver
/
.BR tcpserver.

2. 
.B qmail-dkverify 
called by the 
.I QMAILQUEUE(_EXTRA) 
mechanism as (first) replacement for 
.B qmail-queue 
as a stub.
The incoming message is enhanced by the required CR 
characters line-by-line and stored in 
.IR queue/dkim/[split]/xyz .

3. 
.B qmail-dkim 
is called by 
.B qmail-dkverify 
as a child performing the actual verification on 
.I queue/dkim/[split]/xyz
while using a DNS TXT lookup for the sender's public key
given in the DKIM message header and
calling the fehQlibs DNS routines.
The verification results are persisted at
.IR queue/dkim/[split]/zyx .

4. 
.B qmail-dkverify 
(as parent) reading the evaluated DKIM information from 
.B qmail-dkim 
and assembling a DKIM header line with the results
prepended to the message.

5. 
.B qmail-queue
is finally called to queue the message for delivery.

.SH "INVOCATION AND USAGE"
In order to invoke 
.B qmail-dkverify 
the environment variable
.I QMAILQUEUE="bin/qmail-dkverify" 
has to be populated in the context of 
.BR qmail-smtpd .

Since 
.B qmail-smtpd
is typically called by means of
.B sslserver
or
.BR tcpserver ,
the 
.I tcpd.smtp.cdb
database as compiled by
.B tcprules
can be enhanced to include a line like
.I :alllow:QMAILQUEUE="bin/qmail-dkverify" 
making use of the QMAILQUEUE_EXTRA mechanism.

Alternatively, this environment variable could be 
defined as part of 
.BR qmail-smtpd 's
start script which would now enable to 
provide DKIM signature checking for all 
SMTP sessions irrespectively of their origin.

Usually, 
.B qmail-dkverify
works in annotation mode only.

However, setting additionally the environment variable
.I DKIM="+"
would command 
.B qmail-dkverify 
to reject mails failing the 
DKIM signature verification.
In case of a rejection, the 
.B qmail-smtpd
log shows the following message:
.IR Reject::DKIM::Signature .

Note: 
.B qmail-dkverify
shall not be used for authenticated 
SMTP sessions, typically provided on the
.I Submission 
port.

.SH "LOGGING"
No particular logging is currently forseen.
Rather, each individual RFC 822 message is enhanced by 
the following header line in case a DKIM signature 
is recognized:

.I X-Authentication-Results: sender dkim=[pass|fail (verbose error message)] MTA
including the 
.I sender
and the evaluating
.I MTA
as given in 
.IR control/me .
In case of a \fIfail\fR, the verbose reason
follows in parenthesis.

.SH "SYSTEM IMPACT"
.B qmail-dkverify
does several reads and writes on the 
received messages. Apart from the cryptographic
operations, this will slow down message exchange
and increase the load on the system.

.SH "SEE ALSO"
qmail-queue(8),
qmail-remote(8),
qmail-dkim(8),
qmail-dksign(8),
qmail-log(8).