.vitem &$dkim_verify_status$& &&&
Results of DKIM verification.
-For details see chapter &<<CHAPdkim>>&.
+For details see section &<<SECDKIMVFY>>&.
.vitem &$dkim_cur_signer$& &&&
&$dkim_verify_reason$& &&&
&$dkim_key_notes$& &&&
&$dkim_key_length$&
These variables are only available within the DKIM ACL.
-For details see chapter &<<CHAPdkim>>&.
+For details see section &<<SECDKIMVFY>>&.
.vitem &$dkim_signers$&
.vindex &$dkim_signers$&
When a message has been received this variable contains
a colon-separated list of signer domains and identities for the message.
-For details see chapter &<<CHAPdkim>>&.
+For details see section &<<SECDKIMVFY>>&.
.vitem &$dnslist_domain$& &&&
&$dnslist_matched$& &&&
is compiled with the content-scanning extension. For details, see section
&<<SECTscanspamass>>&.
+.new
+.vitem &$spf_header_comment$& &&&
+ &$spf_received$& &&&
+ &$spf_result$& &&&
+ &$spf_smtp_comment$&
+These variables are only available if Exim is built with SPF support.
+For details see section &<<SECSPF>>&.
+.wen
.vitem &$spool_directory$&
.vindex "&$spool_directory$&"
This option defines the ACL that is run for each DKIM signature
(by default, or as specified in the dkim_verify_signers option)
of a received message.
-See chapter &<<CHAPdkim>>& for further details.
+See section &<<SECDKIMVFY>>& for further details.
.option acl_smtp_etrn main string&!! unset
.cindex "ETRN" "ACL for"
This option gives a list of DKIM domains for which the DKIM ACL is run.
It is expanded after the message is received; by default it runs
the ACL once for each signature in the message.
-See chapter &<<CHAPdkim>>&.
+See section &<<SECDKIMVFY>>&.
.option dns_again_means_nonexist main "domain list&!!" unset
chapter &<<CHAPi18n>>& for details of Exim's support for internationalisation.
-.option spamd_address main string "see below"
+.option spamd_address main string "127.0.0.1 783"
This option is available when Exim is compiled with the content-scanning
extension. It specifies how Exim connects to SpamAssassin's &%spamd%& daemon.
-The default value is
-.code
-127.0.0.1 783
-.endd
See section &<<SECTscanspamass>>& for more details.
+.new
+.option spf_guess main string "v=spf1 a/24 mx/24 ptr ?all"
+This option is available when Exim is compiled with SPF support.
+See section &<<SECSPF>>& for more details.
+.wen
+
+
+
.option split_spool_directory main boolean false
.cindex "multiple spool directories"
.cindex "spool directory" "split"
&*Note*&: Under current versions of OpenSSL, when a list of more than one
file is used, the &$tls_in_ourcert$& veriable is unreliable.
-&*Note*&: OCSP stapling is not usable when a list of more than one file is used.
+&*Note*&: OCSP stapling is not usable under OpenSSL
+when a list of more than one file is used.
If the option contains &$tls_out_sni$& and Exim is built against OpenSSL, then
if the OpenSSL build supports TLS extensions and the TLS client sends the
.cindex "TLS" "server certificate revocation list"
.cindex "certificate" "revocation list for server"
This option specifies a certificate revocation list. The expanded value must
-be the name of a file that contains a CRL in PEM format.
+be the name of a file that contains CRLs in PEM format.
+
+.new
+Under OpenSSL the option can specify a directory with CRL files.
+
+&*Note:*& Under OpenSSL the option must, if given, supply a CRL
+for each signing element of the certificate chain (i.e. all but the leaf).
+For the file variant this can be multiple PEM blocks in the one file.
+.wen
See &<<SECTtlssni>>& for discussion of when this option might be re-expanded.
Usable for GnuTLS 3.4.4 or 3.3.17 or OpenSSL 1.1.0 (or later).
-&*Note*&: There is currently no support for multiple OCSP proofs to match the
-multiple certificates facility.
+.new
+For GnuTLS 3.5.6 or later the expanded value of this option can be a list
+of files, to match a list given for the &%tls_certificate%& option.
+The ordering of the two lists must match.
+.wen
.option tls_on_connect_ports main "string list" unset
during TLS session handshake, to permit alternative values to be chosen:
.ilist
-.vindex "&%tls_certificate%&"
&%tls_certificate%&
.next
-.vindex "&%tls_crl%&"
&%tls_crl%&
.next
-.vindex "&%tls_privatekey%&"
&%tls_privatekey%&
.next
-.vindex "&%tls_verify_certificates%&"
&%tls_verify_certificates%&
.next
-.vindex "&%tls_ocsp_file%&"
&%tls_ocsp_file%&
.endlist
This ACL is evaluated before &%acl_smtp_mime%& and &%acl_smtp_data%&.
-For details on the operation of DKIM, see chapter &<<CHAPdkim>>&.
+For details on the operation of DKIM, see section &<<SECDKIM>>&.
.section "The SMTP MIME ACL" "SECID194"
.vitem &*queue*&&~=&~<&'text'&>
+.cindex "&%queue%& ACL modifier"
+.cindex "named queues" "selecting in ACL"
This modifier specifies the use of a named queue for spool files
for the message.
It can only be used before the message is received (i.e. not in
.cindex "disable DKIM verify"
.cindex "DKIM" "disable verify"
This control turns off DKIM verification processing entirely. For details on
-the operation and configuration of DKIM, see chapter &<<CHAPdkim>>&.
+the operation and configuration of DKIM, see section &<<SECDKIM>>&.
.vitem &*control&~=&~dscp/*&<&'value'&>
If the value of &%av_scanner%& starts with a dollar character, it is expanded
before use.
The usual list-parsing of the content (see &<<SECTlistconstruct>>&) applies.
-The following scanner types are supported in this release:
+The following scanner types are supported in this release,
+.new
+though individual ones can be included or not at build time:
+.wen
.vlist
.vitem &%avast%&
to be scanned, which will should normally result in less I/O happening and be
more efficient. Normally in the TCP case, the data is streamed to ClamAV as
Exim does not assume that there is a common filesystem with the remote host.
-There is an option WITH_OLD_CLAMAV_STREAM in &_src/EDITME_& available, should
-you be running a version of ClamAV prior to 0.95.
The final example shows that multiple TCP targets can be specified. Exim will
randomly use one for each incoming email (i.e. it load balances them). Note
&` `& command list for &"no mail in SMTP session"&
&`CV `& certificate verification status
&`D `& duration of &"no mail in SMTP session"&
+&`DKIM`& domain verified in incoming message
&`DN `& distinguished name from peer certificate
&`DS `& DNSSEC secured lookups
&`DT `& on &`=>`& lines: time taken for a delivery
&` `& on &"Completed"& lines: time spent on queue
&`R `& on &`<=`& lines: reference for local bounce
&` `& on &`=>`& &`>>`& &`**`& and &`==`& lines: router name
+&`RT `& on &`<=`& lines: time taken for reception
&`S `& size of message in bytes
&`SNI `& server name indication from TLS client hello
&`ST `& shadow transport name
.endd
failed. The delivery was discarded.
.endlist olist
+.next
+.new
+.cindex DKIM "log line"
+&'DKIM: d='&&~&~Verbose results of a DKIM verification attempt, if enabled for
+logging and the message has a DKIM signature header.
+.wen
.endlist ilist
&`*delay_delivery `& immediate delivery delayed
&` deliver_time `& time taken to perform delivery
&` delivery_size `& add &`S=`&&'nnn'& to => lines
+&`*dkim `& DKIM verified domain on <= lines
+&` dkim_verbose `& separate full DKIM verification result line, per signature
&`*dnslist_defer `& defers of DNS list (aka RBL) lookups
&` dnssec `& DNSSEC secured lookups
&`*etrn `& ETRN commands
&` incoming_interface `& local interface on <= and => lines
&` incoming_port `& remote port on <= lines
&`*lost_incoming_connection `& as it says (includes timeouts)
-&` millisec `& millisecond timestamps and QT,DT,D times
+&` millisec `& millisecond timestamps and RT,QT,DT,D times
&` outgoing_interface `& local interface on => lines
&` outgoing_port `& add remote port to => lines
&`*queue_run `& start and end queue runs
&%deliver_time%&: For each delivery, the amount of real time it has taken to
perform the actual delivery is logged as DT=<&'time'&>, for example, &`DT=1s`&.
If millisecond logging is enabled, short times will be shown with greater
-precision, eg. &`DT=0.304`&.
+precision, eg. &`DT=0.304s`&.
.next
.cindex "log" "message size on delivery"
.cindex "size" "of message"
&%delivery_size%&: For each delivery, the size of message delivered is added to
the &"=>"& line, tagged with S=.
.next
+.new
+.cindex log "DKIM verification"
+.cindex DKIM "verification logging"
+&%dkim%&: For message acceptance log lines, when an DKIM signture in the header
+verifies successfully a tag of DKIM is added, with one of the verified domains.
+.next
+.cindex log "DKIM verification"
+.cindex DKIM "verification logging"
+&%dkim_verbose%&: A log entry is written for each attempted DKIM verification.
+.wen
+.next
.cindex "log" "dnslist defer"
.cindex "DNS list" "logging defer"
.cindex "black list (DNS)"
the local host is logged as QT=<&'time'&> on &"Completed"& lines, for
example, &`QT=3m45s`&. The clock starts when Exim starts to receive the
message, so it includes reception time as well as the total delivery time.
+.new
+.next
+.cindex "log" "receive duration"
+&%receive_time%&: For each message, the amount of real time it has taken to
+perform the reception is logged as RT=<&'time'&>, for example, &`RT=1s`&.
+If millisecond logging is enabled, short times will be shown with greater
+precision, eg. &`RT=0.204s`&.
+.wen
.next
.cindex "log" "recipients"
&%received_recipients%&: The recipients of a message are listed in the main log
. ////////////////////////////////////////////////////////////////////////////
. ////////////////////////////////////////////////////////////////////////////
-.chapter "Support for DKIM (DomainKeys Identified Mail)" "CHAPdkim" &&&
- "DKIM Support"
+.chapter "DKIM and SPF" "CHAPdkim" &&&
+ "DKIM and SPF Support"
.cindex "DKIM"
+.section "DKIM (DomainKeys Identified Mail)" SECDKIM
+
DKIM is a mechanism by which messages sent by some entity can be provably
linked to a domain which that entity controls. It permits reputation to
be tracked on a per-domain basis, rather than merely upon source IP address.
DKIM is documented in RFC 4871.
+.new
+As DKIM relies on the message being unchanged in transit, messages handled
+by a mailing-list (which traditionally adds to the message) will not match
+any original DKIM signature.
+.wen
+
DKIM support is compiled into Exim by default if TLS support is present.
It can be disabled by setting DISABLE_DKIM=yes in &_Local/Makefile_&.
After expansion, this can be a list.
Each element in turn is put into the &%$dkim_domain%& expansion variable
while expanding the remaining signing options.
-If it is empty after expansion, DKIM signing is not done.
+If it is empty after expansion, DKIM signing is not done,
+and no error will result even if &%dkim_strict%& is set.
.option dkim_selector smtp string list&!! unset
This sets the key selector string.
Each element in turn is put in the expansion
variable &%$dkim_selector%& which may be used in the &%dkim_private_key%&
option along with &%$dkim_domain%&.
-If the option is empty after expansion, DKIM signing is not done for this domain.
+If the option is empty after expansion, DKIM signing is not done for this domain,
+and no error will result even if &%dkim_strict%& is set.
.option dkim_private_key smtp string&!! unset
This sets the private key to use.
be signed. This case will not result in an error, even if &%dkim_strict%&
is set.
.endlist
-If the option is empty after expansion, DKIM signing is not done.
.option dkim_hash smtp string&!! sha256
Can be set alternatively to &"sha1"& to use an alternate hash
name will be appended.
-.section "Verifying DKIM signatures in incoming mail" "SECID514"
+.section "Verifying DKIM signatures in incoming mail" "SECDKIMVFY"
.cindex "DKIM" "verification"
Verification of DKIM signatures in SMTP incoming email is implemented via the
for more information of what they mean.
.endlist
+
+
+
+.new
+.section "SPF (Sender Policy Framework)" SECSPF
+.cindex SPF verification
+
+SPF is a mechanism whereby a domain may assert which IP addresses may transmit
+messages with its domain in the envelope from, documented by RFC 7208.
+For more information on SPF see &url(http://www.openspf.org).
+
+Messages sent by a system not authorised will fail checking of such assertions.
+This includes retransmissions done by traditional forwarders.
+
+SPF verification support is built into Exim if SUPPORT_SPF=yes is set in
+&_Local/Makefile_&. The support uses the &_libspf2_& library
+&url(http://www.libspf2.org/).
+There is no Exim involvement on the trasmission of messages; publishing certain
+DNS records is all that is required.
+
+For verification, an ACL condition and an expansion lookup are provided.
+
+.cindex SPF "ACL condition"
+.cindex ACL "spf condition"
+The ACL condition "spf" can be used at or after the MAIL ACL.
+It takes as an argument a list of strings giving the outcome of the SPF check,
+and will succeed for any matching outcome.
+Valid strings are:
+.vlist
+.vitem &%pass%&
+The SPF check passed, the sending host is positively verified by SPF.
+
+.vitem &%fail%&
+The SPF check failed, the sending host is NOT allowed to send mail for the
+domain in the envelope-from address.
+
+.vitem &%softfail%&
+The SPF check failed, but the queried domain can't absolutely confirm that this
+is a forgery.
+
+.vitem &%none%&
+The queried domain does not publish SPF records.
+
+.vitem &%neutral%&
+The SPF check returned a "neutral" state. This means the queried domain has
+published a SPF record, but wants to allow outside servers to send mail under
+its domain as well. This should be treated like "none".
+
+.vitem &%permerror%&
+This indicates a syntax error in the SPF record of the queried domain.
+You may deny messages when this occurs. (Changed in 4.83)
+
+.vitem &%temperror%&
+This indicates a temporary error during all processing, including Exim's
+SPF processing. You may defer messages when this occurs.
+(Changed in 4.83)
+
+.vitem &%err_temp%&
+Same as permerror, deprecated in 4.83, will be removed in a future release.
+
+.vitem &%err_perm%&
+Same as temperror, deprecated in 4.83, will be removed in a future release.
+.endlist
+
+You can prefix each string with an exclamation mark to invert
+its meaning, for example "!fail" will match all results but
+"fail". The string list is evaluated left-to-right, in a
+short-circuit fashion.
+
+Example:
+.code
+deny spf = fail
+ message = $sender_host_address is not allowed to send mail from \
+ ${if def:sender_address_domain \
+ {$sender_address_domain}{$sender_helo_name}}. \
+ Please see http://www.openspf.org/Why?scope=\
+ ${if def:sender_address_domain {mfrom}{helo}};\
+ identity=${if def:sender_address_domain \
+ {$sender_address}{$sender_helo_name}};\
+ ip=$sender_host_address
+.endd
+
+When the spf condition has run, it sets up several expansion
+variables:
+
+.cindex SPF "verification variables"
+.vlist
+.vitem &$spf_header_comment$&
+.vindex &$spf_header_comment$&
+ This contains a human-readable string describing the outcome
+ of the SPF check. You can add it to a custom header or use
+ it for logging purposes.
+
+.vitem &$spf_received$&
+.vindex &$spf_received$&
+ This contains a complete Received-SPF: header that can be
+ added to the message. Please note that according to the SPF
+ draft, this header must be added at the top of the header
+ list. Please see section 10 on how you can do this.
+
+ Note: in case of "Best-guess" (see below), the convention is
+ to put this string in a header called X-SPF-Guess: instead.
+
+.vitem &$spf_result$&
+.vindex &$spf_result$&
+ This contains the outcome of the SPF check in string form,
+ one of pass, fail, softfail, none, neutral, permerror or
+ temperror.
+
+.vitem &$spf_smtp_comment$&
+.vindex &$spf_smtp_comment$&
+ This contains a string that can be used in a SMTP response
+ to the calling party. Useful for "fail".
+.endlist
+
+
+.cindex SPF "ACL condition"
+.cindex ACL "spf_guess condition"
+.cindex SPF "best guess"
+In addition to SPF, you can also perform checks for so-called
+"Best-guess". Strictly speaking, "Best-guess" is not standard
+SPF, but it is supported by the same framework that enables SPF
+capability.
+Refer to &url(http://www.openspf.org/FAQ/Best_guess_record)
+for a description of what it means.
+
+To access this feature, simply use the spf_guess condition in place
+of the spf one. For example:
+
+.code
+deny spf_guess = fail
+ message = $sender_host_address doesn't look trustworthy to me
+.endd
+
+In case you decide to reject messages based on this check, you
+should note that although it uses the same framework, "Best-guess"
+is not SPF, and therefore you should not mention SPF at all in your
+reject message.
+
+When the spf_guess condition has run, it sets up the same expansion
+variables as when spf condition is run, described above.
+
+Additionally, since Best-guess is not standardized, you may redefine
+what "Best-guess" means to you by redefining the main configuration
+&%spf_guess%& option.
+For example, the following:
+
+.code
+spf_guess = v=spf1 a/16 mx/16 ptr ?all
+.endd
+
+would relax host matching rules to a broader network range.
+
+
+.cindex SPF "lookup expansion"
+.cindex lookup spf
+A lookup expansion is also available. It takes an email
+address as the key and an IP address as the database:
+
+.code
+ ${lookup {username@domain} spf {ip.ip.ip.ip}}
+.endd
+
+The lookup will return the same result strings as they can appear in
+&$spf_result$& (pass,fail,softfail,neutral,none,err_perm,err_temp).
+Currently, only IPv4 addresses are supported.
+
+
+. wen-for SPF section
+.wen
+
+
. ////////////////////////////////////////////////////////////////////////////
. ////////////////////////////////////////////////////////////////////////////
git://git.exim.org / exim.git / blobdiff