SYNOPSIS

       qmail-dkverify

DESCRIPTION

       qmail-dkverify is invoked faciliting the QMAILQUEUE(_EXTRA) mechanism.

CALLING CHAIN

       Verifying DKIM signatures upon receipt involves the following calling
       chain:

       1.  qmail-smtpd called from sslserver / tcpserver.

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

       3.  qmail-dkim is called by qmail-dkverify as a child performing the
       actual verification on 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 queue/dkim/[split]/zyx.

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

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

INVOCATION AND USAGE

       In order to invoke qmail-dkverify the environment variable
       QMAILQUEUE="bin/qmail-dkverify" has to be populated in the context of
       qmail-smtpd.

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

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

       Usually, qmail-dkverify works in annotation mode only.

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

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

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:

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

SYSTEM IMPACT

       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.

SEE ALSO

       qmail-queue(8), qmail-remote(8), qmail-dkim(8), qmail-dksign(8), 
       qmail-log(8).




                                       8              s/qmail:(qmail-dkverify)