qconfirm - How it works

Sender mode

qconfirm-check checks for each message if the envelope sender of this message is allowed to send mail to the user owning the .qmail file it was invoked from.

If qconfirm-check already knows this envelope sender, or was told to accept mails from this sender, it immediately exits with 0, and so allows the mail to be processed further in the .qmail file. If not, qconfirm-check injects a confirmation request message to the envelope sender asking for a reply, and exits 99 to defer the message temporarily. The message will stay in the qmail queue and will be tried to be delivered in a little while.

qconfirm-check then defers this message on future delivery attempts and all other messages from the same envelope sender temporarily without injecting another confirmation request message until a reply to the confirmation request message is received (Exception: see the -t option). If queuelifetime has expired for a message before a reply to the confirmation request was received, the message is bounced and never delivered to the recipient.

Envelope sender address id

To check if the envelope sender is allowed, qconfirm-check creates an id based on the envelope sender mail address as follows:

The sender mail address is split into two parts, the local part and the host part. For example if the sender mail address is floyd@smarden.org, the local part is floyd, the host part is smarden.org. These two parts are concatenated in reverse order with a "=-" in between, any uppercase letter is converted to lowercase, and finally each dot, slash, and apostrophe is replaced by a colon. So the id for floyd@smarden.org is smarden:org=-floyd.

Matching envelope sender address id

qconfirm-check matches the id created from the envelope sender address against a file in the directory ~/.qconfirm/ok/ the same way qmail matches .qmail files for extension addresses. For example, the address floyd-extension@smarden.org with the id smarden:org=-floyd-extension is matched by the following files in the ~/.qconfirm/ok/ directory:

  smarden:org=-floyd-extension
  smarden:org=-floyd-default
  smarden:org=-default
  default

If at least one of these files exists in the ~/.qconfirm/ok/ directory, the message is allowed to be processed further in the .qmail file. If qconfirm-check runs with the -b option, the same matching takes place for the .qconfirm/bad/ directory.

Extended envelope sender domain matching

If qconfirm-check runs with the -d option, it additionally checks the host part of the id with a wildcard similar to qmail-smtpd's rcpthosts. For example, the address floyd-list@list.smarden.org with the id list:smarden:org=-floyd-list is matched by the following files:

  list:smarden:org
  :smarden:org
  :org

Extended domain matching is applied after matching the envelope sender address id.

Sending the confirmation request

If the envelope sender isn't matched to be allowed, qconfirm-check creates a random key, creates a file with the filename "id" in the ~/.qconfirm/pending/ directory containing the key, and creates a .qmail-qconfirm-key file in the user's home directory to handle the reply to the confirmation request. qconfirm-check injects the confirmation request message to the envelope sender address with the from header: user-qconfirm-key@host.

Handling the reply to the confirmation request

The reply to the confirmation request messages goes to the address user-qconfirm-key@host and so is handled by the .qmail-qconfirm-key file. qconfirm-check automatically has set up a program delivery to qconfirm-accept in this .qmail file. So if a mail to this address is received, qconfirm-accept is invoked. qconfirm-accept then moves the file with the filename "id" from the ~/.qconfirm/pending/ directory to the ~/.qconfirm/ok/ directory, writes the message (the reply to the confirmation request) to this file, and removes the .qmail-qconfirm-key file it was invoked from.

The next time qmail tries to deliver a temporarily deferred or a new message from this envelope sender, qconfirm-check matches the sender to be allowed and allows the message to be processed further in the .qmail file. If the file in the ~/.qconfirm/ok/ directory that matched the envelope sender is not empty, qconfirm-check optionally injects a confirmation acknowledgement message to the envelope sender, including the contents of the file at the bottom of the message, and then truncates this file to the size 0.

Handling bounces from confirmation requests

qconfirm can be configured to process bounces from confirmation request messages, and so to reduce the amount of doublebounces reaching the postmaster's mailboxes. See Handling bounce messages for details.

Message mode

If qconfirm-check is running in message mode, each single message must go through the confirmation process. The id qconfirm-check uses for identifying a message is not created from the envelope sender but is the inode number of the message stored in the qmail mail queue.

Gerrit Pape <pape@smarden.org>

$Id: technical.html,v 1.9 2003/01/02 13:52:03 pape Exp $