DKIM: permit dkim_private_key to override dkim_strict on signing. Bug 2220
[users/jgh/exim.git] / doc / doc-docbook / spec.xfpt
index f5eda68cdd461570fa068689978322f5683385ab..b6d283b95f48264e19cb74eaf7117bce0d3dff12 100644 (file)
@@ -11661,7 +11661,7 @@ The name of the main configuration file Exim is using.
 
 .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$& &&&
@@ -11683,13 +11683,13 @@ For details see chapter &<<CHAPdkim>>&.
        &$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$& &&&
@@ -12833,6 +12833,14 @@ A number of variables whose names start with &$spam$& are available when Exim
 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$&"
@@ -14086,7 +14094,7 @@ acknowledgment is sent. See chapter &<<CHAPACL>>& for further details.
 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"
@@ -14619,7 +14627,7 @@ to handle IPv6 literal addresses.
 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
@@ -16804,17 +16812,21 @@ response to EHLO only to those client hosts that match this option. See
 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"
@@ -27737,19 +27749,14 @@ option (prior to expansion) then the following options will be re-expanded
 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
 
@@ -28120,7 +28127,7 @@ otherwise specified, the default action is to accept.
 
 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"
@@ -29186,7 +29193,7 @@ contexts):
 .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'&>
@@ -31541,7 +31548,10 @@ av_scanner = sophie:/var/run/sophie
 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%&
@@ -36048,6 +36058,7 @@ the following table:
 &`    `&        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
@@ -36117,6 +36128,12 @@ A delivery set up by a router configured with
 .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
 
 
@@ -36144,6 +36161,8 @@ selection marked by asterisks:
 &`*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
@@ -36250,6 +36269,17 @@ precision, eg. &`DT=0.304`&.
 &%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)"
@@ -38485,15 +38515,23 @@ There is no dot-stuffing (and no dot-termination).
 . ////////////////////////////////////////////////////////////////////////////
 . ////////////////////////////////////////////////////////////////////////////
 
-.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_&.
 
@@ -38541,7 +38579,8 @@ The domain(s) you want to sign with.
 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.
@@ -38549,7 +38588,8 @@ After expansion, which can use &$dkim_domain$&, this can be a list.
 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.
@@ -38566,7 +38606,6 @@ be "0", "false" or the empty string, in which case the message will not
 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
@@ -38614,7 +38653,7 @@ will be signed, and one signtature added for a missing header with the
 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
@@ -38831,6 +38870,178 @@ see the documentation of the &%$dkim_verify_status%& expansion variable above
 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
+
+
 . ////////////////////////////////////////////////////////////////////////////
 . ////////////////////////////////////////////////////////////////////////////