DKIM: add builtin macro with default list of headers for signing

[users/heiko/exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 862c8f91d901ea0d1fc38665cedbbacd669b3e74..d030ee238ee8c49c5943429c76bd415ba488c398 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -9967,7 +9967,7 @@ a regular expression, and a substitution string. For example:
 ${sg{abcdefabcdef}{abc}{xyz}}
 .endd
 yields &"xyzdefxyzdef"&. Because all three arguments are expanded before use,
-if any $ or \ characters are required in the regular expression or in the
+if any $, } or \ characters are required in the regular expression or in the
 substitution string, they have to be escaped. For example:
 .code
 ${sg{abcdef}{^(...)(...)\$}{\$2\$1}}
@@ -10118,7 +10118,15 @@ character. For example:
 .code
 ${addresses:>& Chief <ceo@up.stairs>, sec@base.ment (dogsbody)}
 .endd
-expands to &`ceo@up.stairs&&sec@base.ment`&. Compare the &*address*& (singular)
+expands to &`ceo@up.stairs&&sec@base.ment`&. The string is expanded
+first, so if the expanded string starts with >, it may change the output
+separator unintentionally. This can be avoided by setting the output
+separator explicitly:
+.code
+${addresses:>:$h_from:}
+.endd
+
+Compare the &*address*& (singular)
 expansion item, which extracts the working address from a single RFC2822
 address. See the &*filter*&, &*map*&, and &*reduce*& items for ways of
 processing lists.
@@ -23798,7 +23806,9 @@ of the message. Its value must not be zero. See also &%final_timeout%&.
 .option dkim_private_key smtp string&!! unset
 .option dkim_canon smtp string&!! unset
 .option dkim_strict smtp string&!! unset
-.option dkim_sign_headers smtp string&!! unset
+.option dkim_sign_headers smtp string&!! per RFC
+.option dkim_hash smtp string&!! sha256
+.option dkim_identity smtp string&!! unset
 DKIM signing options.  For details see section &<<SECDKIMSIGN>>&.
 
 
@@ -24137,7 +24147,7 @@ This option provides a list of servers to which, provided they announce
 CHUNKING support, Exim will attempt to use BDAT commands rather than DATA.
 BDAT will not be used in conjunction with a transport filter.
 
-.option hosts_try_fastopen smtp "host list!!" unset
+.option hosts_try_fastopen smtp "host list&!!" unset
 .cindex "fast open, TCP" "enabling, in client"
 .cindex "TCP Fast Open" "enabling, in client"
 .cindex "RFC 7413" "TCP Fast Open"
@@ -24153,6 +24163,9 @@ as the initiator must present a cookie in the SYN segment.
 
 On (at least some) current Linux distributions the facility must be enabled
 in the kernel by the sysadmin before the support is usable.
+There is no option for control of the server side; if the system supports
+it it is always enebled.  Note that legthy operations in the connect ACL,
+such as DNSBL lookups, will still delay the emission of the SMTP banner.
 
 .option hosts_try_prdr smtp "host list&!!" *
 .cindex "PRDR" "enabling, optional in client"
@@ -38525,13 +38538,15 @@ while expanding the remaining signing options.
 .wen
 If it is empty after expansion, DKIM signing is not done.
 
-.option dkim_selector smtp string&!! unset
+.option dkim_selector smtp string list&!! unset
 This sets the key selector string.
-You can use the &%$dkim_domain%& expansion variable to look up a matching selector.
-The result is put in the expansion
+.new
+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.
+If the option is empty after expansion, DKIM signing is not done for this domain.
+.wen
 
 .option dkim_private_key smtp string&!! unset
 This sets the private key to use.
@@ -38550,6 +38565,19 @@ is set.
 .endlist
 If the option is empty after expansion, DKIM signing is not done.
 
+.new
+.option dkim_hash smtp string&!! sha256
+Can be set alternatively to &"sha1"& to use an alternate hash
+method.  Note that sha1 is now condidered insecure, and deprecated.
+
+.option dkim_identity smtp string&!! unset
+If set after expansion, the value is used to set an "i=" tag in
+the signing header.  The DKIM standards restrict the permissible
+syntax of this optional tag to a mail address, with possibly-empty
+local part, an @, and a domain identical to or subdomain of the "d="
+tag value.  Note that Exim does not check the value.
+.wen
+
 .option dkim_canon smtp string&!! unset
 This option sets the canonicalization method used when signing a message.
 The DKIM RFC currently supports two methods: "simple" and "relaxed".
@@ -38563,11 +38591,13 @@ either "1" or "true", Exim will defer. Otherwise Exim will send the message
 unsigned. You can use the &%$dkim_domain%& and &%$dkim_selector%& expansion
 variables here.
 
-.option dkim_sign_headers smtp string&!! unset
-If set, this option must expand to (or be specified as) a colon-separated
+.option dkim_sign_headers smtp string&!! see below
+If set, this option must expand to a colon-separated
 list of header names. Headers with these names will be included in the message
 signature.
 When unspecified, the header names recommended in RFC4871 will be used.
+The default list is available for the expansion in the macro
+"_DKIM_SIGN_HEADERS".
 
 
 .section "Verifying DKIM signatures in incoming mail" "SECID514"
@@ -38578,7 +38608,7 @@ Verification of DKIM signatures in SMTP incoming email is implemented via the
 syntactically(!) correct signature in the incoming message.
 A missing ACL definition defaults to accept.
 If any ACL call does not accept, the message is not accepted.
-If a cutthrough delivery was in progress for the message it is
+If a cutthrough delivery was in progress for the message, that is
 summarily dropped (having wasted the transmission effort).
 
 To evaluate the signature in the ACL a large number of expansion variables