The second form is used for scripting or testing. See OPTIONS below.
A DKIM signature on a message associates a domain with the message, thereby allowing domain owners to claim some responsibility for the messages.
For SMTP authentication, the domain name is determined after the user id, if it contains an "@" or from default_domain.
For non-empty RELAYCLIENT variable, typically set in smtpaccess files, zdkimfilter signs only if the value of RELAYCLIENT starts with "@". In that case, the domain name is the rest of the string. The local part of the user id is set to ``postmaster'' (e.g. for db_sql_check_user). CAUTION: this setting may conflict with Courier appending the value of RELAYCLIENT to message recipient(s). That is meant to force the message through local delivery, possibly using percentrelay. The filter removes the appended values as long as it is installed. To prevent that behavior set let_relayclient_alone. At any rate, when a client uses SMTP authentication, any RELAYCLIENT content is reset.
In any case, the domain name can be obtained from a suitable header field of the message, such as "From:". Use the key_choice_header configuration option to specify that.
The domain name is then looked up in the domain_keys directory. It should be a soft link to the actual key. The basename of the linked-to file contains the selector: If the basename starts with the same string as the domain name, then that initial part and an optional dot are skipped. In addition, an extension of ".private" or ".pem" is discarded. For example, the following will all result in assigning selector sel as the key for example.com:
example.com -> ../anywhere/sel.private example.com -> ../anywhere/sel example.com -> ../anywhere/example.com.sel example.com -> ../anywhere/example.comsel example.com -> ../anywhere/example.com.sel.private example.com -> ../anywhere/example.comsel.private example.com -> ../anywhere/example.com.sel.pem example.com -> ../anywhere/example.comsel.pem example.com -> ../anywhere/sel.pem
Keys can be created using opendkim-genkey. The public key must be published on the DNS in order to make it possible for remote receivers to verify the signatures. Domain owners should change selector on a regular basis, or whenever they think the private key might have been compromised. The soft link that enables signing with a given private key should be set after publishing the corresponding public key. The file existence is going to be effective on It is not necessary to restart zdkimfilter for that to take effect.
The user-id used for SMTP authentication is also reported in Courier's "Received:" header field. If the redact_received_auth configuration option is set, zdkimfilter obscures it. See redact(1).
After signing an outgoing message, zdkimfilter logs to the database the list of domains that appeared in any RCPT command. The database can be used for whitelisting and for rate-limiting users. See zfilter_db(1) for more details.
Messages can be rejected or dropped according to DMARC, ADSP, and NXDOMAIN configurations, summarized below, and also according to an action_header (see zdkimfilter.conf(5)) or the shoot_on_sight feature (see whitelisted in zfilter_db(1)). The decision to reject or drop a message can be revoked after DNSWL (see dnswl_worthiness_pass and whitelisted_pass in zdkimfilter.conf(5)). So, if a domain is tagged shoot_on_sight, but the message is authenticated by a domain which is whitelisted or DNSWL-worth, the latter wins and the message is not rejected. However, if the sender is DNSWL-worth but tagged shoot_on_sight, it worthiness is discarded and the message is rejected.
By default, zdkimfilter adds an "Authentication-Results:" (A-R) header field only when there are noticeable results to report. It uses the host name that Courier uses in its "Received:" field. Other A-R fields with that same name get zapped from the message, if found.
While per-domain flags (whitelisted, do_dmarc, do_adsp) are read during the verification process, the resulting data is logged to the database after handing the message back to Courier. Those results are used to send aggregate reports, and in general can contribute some insight on the email traffic. See zfilter_db(1) for the details.
Options honor_dmarc and honor_author_domain set to 0 or 1 the corresponding flags. Then a query db_sql_domain_flags can increase or decrease those values. A DMARC record is looked up unless DMARC flag is less than ADSP's. If no record is found, an ADSP record is looked up unless ADSP flag is less than DMARC's. Thus, if the flags are equal an ADSP record is looked up for domains that still don't have DMARC. Then, if its flag is greater than 0, the policy is honored. However, if an authenticated domain is whitelisted, vouched, or DNSWL allowed, the message is delivered even though the policy failed.
In order to look up a DMARC record correctly, the Public Suffix List file must be available and configured in publicsuffix. A supplemental file that list domains participating in PSDDMARCis distributed with this filter. In addition, to comply with DMARC, aggregate reports should be sent and received; see zaggregate(1).
A DMARC policy can ask to quarantine a message. If DMARC is honored, the filter just adds an A-R field contains a "(QUARANTINE)" comment and the message is delivered normally.
DMARC requires SPF, besides DKIM. To enable SPF checking in bofh see courier(8). The result of Courier's SPF check is read from Received-SPF header fields in the message. If SPF is not configured in Courier, turn off this behavior with no_spf, to avoid spurious authentications.
Upon receiving the signal, zdkimfilter reads its configuration file and opens new connections to OpenDKIM library and (possibly) to the database. If no error occurs, it then cleans up the old area, closing old connections, and writes LOG_INFO if verbosity is 2 or higher.
Copyright © 2012-2020 Alessandro Vesely