summaryrefslogtreecommitdiff
path: root/man/qmail-dkverify.8
diff options
context:
space:
mode:
authorJannis Hoffmann <jannis@fehcom.de>2024-07-03 15:48:04 +0200
committerJannis Hoffmann <jannis@fehcom.de>2024-07-03 15:48:04 +0200
commit89b7b67a13ebb7965cc7f13ad0595e2194a2d34c (patch)
tree25efd77a90ae87236e6730d8ea3846bbe0fd126f /man/qmail-dkverify.8
add sqmail-4.2.29asqmail-4.2
Diffstat (limited to 'man/qmail-dkverify.8')
-rw-r--r--man/qmail-dkverify.8137
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).
+