Docs: add notes on lack of multiple-OCSP-proof support

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 7a0841cb28ced57d9ed879dc830a2353c93cba55..28584912291eab0f900576709c5518a122d933bd 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -11665,8 +11665,11 @@ contain the trailing slash. If &$config_file$& does not contain a slash,
 .vindex "&$config_file$&"
 The name of the main configuration file Exim is using.
 
+.vitem &$dkim_verify_status$& &&&
+Results of DKIM verification.
+For details see chapter &<<CHAPdkim>>&.
+
 .vitem &$dkim_cur_signer$& &&&
-       &$dkim_verify_status$& &&&
        &$dkim_verify_reason$& &&&
        &$dkim_domain$& &&&
        &$dkim_identity$& &&&
@@ -17130,8 +17133,13 @@ use when sending messages as a client, you must set the &%tls_certificate%&
 option in the relevant &(smtp)& transport.
 
 .new
+&*Note*&: If you use filenames based on IP addresses, change the list
+separator in the usual way to avoid confusion under IPv6.
+
 &*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.
 .wen
 
 If the option contains &$tls_out_sni$& and Exim is built against OpenSSL, then
@@ -17273,6 +17281,11 @@ Certificate Authority.
 
 Usable for GnuTLS 3.4.4 or 3.3.17 or OpenSSL 1.1.0 (or later).
 
+.new
+&*Note*&: There is currently no support for multiple OCSP proofs to match the
+multiple certificates facility.
+.wen
+
 
 .option tls_on_connect_ports main "string list" unset
 .cindex SSMTP
@@ -27134,7 +27147,7 @@ let the Exim Maintainers know and we'll likely use it).
 .next
 .new
 With GnuTLS, if an explicit list is used for the &%tls_privatekey%& main option
-main option, it must be ordered to match the %&tls_certificate%& list.
+main option, it must be ordered to match the &%tls_certificate%& list.
 .wen
 .next
 Some other recently added features may only be available in one or the other.
@@ -31324,6 +31337,7 @@ address and some time-based randomizing information. The &%prvs%& expansion
 item creates a signed address, and the &%prvscheck%& expansion item checks one.
 The syntax of these expansion items is described in section
 &<<SECTexpansionitems>>&.
+The validity period on signed addresses is seven days.
 
 As an example, suppose the secret per-address keys are stored in an MySQL
 database. A query to look up the key for an address could be defined as a macro
@@ -38705,6 +38719,11 @@ dkim_verify_signers = $sender_address_domain:$dkim_signers
 If a domain or identity is listed several times in the (expanded) value of
 &%dkim_verify_signers%&, the ACL is only called once for that domain or identity.
 
+.new
+If multiple signatures match a domain (or identity), the ACL is called once
+for each matching signature.
+.wen
+
 
 Inside the &%acl_smtp_dkim%&, the following expansion variables are
 available (from most to least important):
@@ -38717,7 +38736,8 @@ an identity. This is one of the list items from the expanded main option
 &%dkim_verify_signers%& (see above).
 
 .vitem &%$dkim_verify_status%&
-A string describing the general status of the signature. One of
+Within the DKIM ACL,
+a string describing the general status of the signature. One of
 .ilist
 &%none%&: There is no signature in the message for the current domain or
 identity (as reflected by &%$dkim_cur_signer%&).
@@ -38731,6 +38751,22 @@ available in &%$dkim_verify_reason%&.
 &%pass%&: The signature passed verification. It is valid.
 .endlist
 
+.new
+This variable can be overwritten using an ACL 'set' modifier.
+This might, for instance, be done to enforce a policy restriction on
+hash-method or key-size:
+.code
+  warn condition =     ${if eq {$dkim_algo}{rsa-sha1}}
+       condition =     ${if eq {$dkim_verify_status}{pass}}
+       logwrite =      NOTE: forcing dkim verify fail (was pass)
+       set dkim_verify_status = fail
+       set dkim_verify_reason = hash too weak
+.endd
+
+After all the DKIM ACL runs have completed, the value becomes a
+colon-separated list of the values after each run.
+.wen
+
 .vitem &%$dkim_verify_reason%&
 A string giving a little bit more detail when &%$dkim_verify_status%& is either
 "fail" or "invalid". One of
@@ -38751,6 +38787,10 @@ re-written or otherwise changed in a way which is incompatible with
 DKIM verification. It may of course also mean that the signature is forged.
 .endlist
 
+.new
+This variable can be overwritten using an ACL 'set' modifier.
+.wen
+
 .vitem &%$dkim_domain%&
 The signing domain. IMPORTANT: This variable is only populated if there is
 an actual signature in the message for the current domain or identity (as