DKIM: support timestamp and expiry tags in signing. Bug 2260

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index f865fc9a1b43aed8423668d52462aaff810eb93b..863a6b949f9bc820cbb9e126af0c308665eff4d6 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -9434,11 +9434,14 @@ letters appear. For example:
         &*$h_*&<&'header&~name'&>&*:*&" &&&
        "&*$bheader_*&<&'header&~name'&>&*:*&&~or&~&&&
         &*$bh_*&<&'header&~name'&>&*:*&" &&&
+       "&*$lheader_*&<&'header&~name'&>&*:*&&~or&~&&&
+        &*$lh_*&<&'header&~name'&>&*:*&"
        "&*$rheader_*&<&'header&~name'&>&*:*&&~or&~&&&
         &*$rh_*&<&'header&~name'&>&*:*&"
 .cindex "expansion" "header insertion"
 .vindex "&$header_$&"
 .vindex "&$bheader_$&"
+.vindex "&$lheader_$&"
 .vindex "&$rheader_$&"
 .cindex "header lines" "in expansion strings"
 .cindex "header lines" "character sets"
@@ -9451,7 +9454,7 @@ The newline that terminates a header line is not included in the expansion, but
 internal newlines (caused by splitting the header line over several physical
 lines) may be present.
 
-The difference between &%rheader%&, &%bheader%&, and &%header%& is in the way
+The difference between the four pairs of expansions is in the way
 the data in the header line is interpreted.
 
 .ilist
@@ -9459,6 +9462,15 @@ the data in the header line is interpreted.
 &%rheader%& gives the original &"raw"& content of the header line, with no
 processing at all, and without the removal of leading and trailing white space.
 
+.next
+.cindex "list" "of header lines"
+&%lheader%& gives a colon-separated list, one element per header when there
+are multiple headers with a given name.
+Any embedded colon characters within an element are doubled, so normal Exim
+list-processing facilities can be used.
+The terminating newline of each element is removed; in other respects
+the content is &"raw"&.
+
 .next
 .cindex "base64 encoding" "in header lines"
 &%bheader%& removes leading and trailing white space, and then decodes base64
@@ -13861,6 +13873,7 @@ listed in more than one group.
 .row &%av_scanner%&                  "specify virus scanner"
 .row &%check_rfc2047_length%&        "check length of RFC 2047 &""encoded &&&
                                       words""&"
+.row &%dns_cname_loops%&             "follow CNAMEs returned by resolver"
 .row &%dns_csa_search_limit%&        "control CSA parent search depth"
 .row &%dns_csa_use_reverse%&         "en/disable CSA IP reverse search"
 .row &%header_maxsize%&              "total size of message header"
@@ -14763,6 +14776,19 @@ This option controls whether or not an IP address, given as a CSA domain, is
 reversed and looked up in the reverse DNS, as described in more detail in
 section &<<SECTverifyCSA>>&.
 
+.new
+.option dns_cname_loops main integer 1
+.cindex DNS "CNAME following"
+This option controls the following of CNAME chains, needed if the resolver does
+not do it internally.
+As of 2018 most should, and the default can be left.
+If you have an ancient one, a value of 10 is likely needed.
+
+The default value of one CNAME-follow is needed
+thanks to the observed return for an MX request,
+given no MX presence but a CNAME to an A, of the CNAME.
+.wen
+
 
 .option dns_dnssec_ok main integer -1
 .cindex "DNS" "resolver options"
@@ -23950,14 +23976,15 @@ the message. As a result, the overall timeout for a message depends on the size
 of the message. Its value must not be zero. See also &%final_timeout%&.
 
 
+.option dkim_canon smtp string&!! unset
 .option dkim_domain smtp string list&!! unset
-.option dkim_selector smtp string&!! unset
+.option dkim_hash smtp string&!! sha256
+.option dkim_identity smtp string&!! unset
 .option dkim_private_key smtp string&!! unset
-.option dkim_canon smtp string&!! unset
+.option dkim_selector smtp string&!! unset
 .option dkim_strict smtp string&!! unset
 .option dkim_sign_headers smtp string&!! "per RFC"
-.option dkim_hash smtp string&!! sha256
-.option dkim_identity smtp string&!! unset
+.option dkim_timestamps smtp string&!! unset
 DKIM signing options.  For details see section &<<SECDKIMSIGN>>&.
 
 
@@ -31148,6 +31175,15 @@ connection, HELO, or MAIL).
 The main use of these variables is expected to be to distinguish between
 rejections of MAIL and rejections of RCPT in callouts.
 
+.new
+The above variables may also be set after a &*successful*&
+address verification to:
+
+.ilist
+&%random%&: A random local-part callout succeeded
+.endlist
+.wen
+
 
 
 
@@ -39067,6 +39103,18 @@ If a '+' prefix if used, all headers that are present with this name
 will be signed, and one signature added for a missing header with the
 name will be appended.
 
+.new
+.option dkim_timestamps smtp integer&!! unset
+This option controls the inclusion of timestamp information in the signature.
+If not set, no such information will be included.
+Otherwise, must be an unsigned number giving an offset in seconds from the current time
+for the expiry tag
+(eg. 1209600 for two weeks);
+both creation (t=) and expiry (x=) tags will be included.
+
+RFC 6376 lists these tags as RECOMMENDED.
+.wen
+
 
 .section "Verifying DKIM signatures in incoming mail" "SECDKIMVFY"
 .cindex "DKIM" "verification"
@@ -39240,6 +39288,12 @@ strict enforcement should code the check explicitly.
 The number of signed body bytes. If zero ("0"), the body is unsigned. If no
 limit was set by the signer, "9999999999999" is returned. This makes sure
 that this variable always expands to an integer value.
+.new
+&*Note:*& The presence of the signature tag specifying a signing body length
+is one possible route to spoofing of valid DKIM signatures.
+A paranoid implementation might wish to regard signature where this variable
+shows less than the "no limit" return as being invalid.
+.wen
 
 .vitem &%$dkim_created%&
 UNIX timestamp reflecting the date and time when the signature was created.