1 files changed, 137 insertions, 0 deletions
diff --git a/man/qmail-dkverify.8 b/man/qmail-dkverify.8
new file mode 100644
index 0000000..eb56952
--- /dev/null
+++ b/man/qmail-dkverify.8
@@ -0,0 +1,137 @@
+.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).
+