X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/db4dcd57f3ce2d62b5a86feadd736836c2909025..baabef80f200a5e028a6f1487276a441caa40255:/doc/doc-docbook/spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index e3ac7f3b9..3b5cbbf5b 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -17138,6 +17138,8 @@ 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
@@ -17279,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
@@ -27653,11 +27660,10 @@ if it requests it. If the server is Exim, it will request a certificate only if
 
 If the &%tls_verify_certificates%& option is set on the &(smtp)& transport, it
 specifies a collection of expected server certificates.
-These may be the system default set (depending on library version),
-a file or,
-depending on library version, a directory,
-must name a file or,
-for OpenSSL only (not GnuTLS), a directory.
+These may be
+the system default set (depending on library version),
+a file,
+or (depending on library version) a directory.
 The client verifies the server's certificate
 against this collection, taking into account any revoked certificates that are
 in the list defined by &%tls_crl%&.
@@ -38557,8 +38563,12 @@ In typical Exim style, the verification implementation does not include any
 default "policy". Instead it enables you to build your own policy using
 Exim's standard controls.
 
+.new
 Please note that verification of DKIM signatures in incoming mail is turned
-on by default for logging purposes. For each signature in incoming email,
+on by default for logging (in the <= line) purposes.
+
+Additional log detail can be enabled using the &%dkim_verbose%& log_selector.
+When set, for each signature in incoming email,
 exim will log a line displaying the most important signature details, and the
 signature status. Here is an example (with line-breaks added for clarity):
 .code
@@ -38567,6 +38577,8 @@ signature status. Here is an example (with line-breaks added for clarity):
     c=relaxed/relaxed a=rsa-sha1
     i=@facebookmail.com t=1252484542 [verification succeeded]
 .endd
+.wen
+
 You might want to turn off DKIM verification processing entirely for internal
 or relay mail sources. To do that, set the &%dkim_disable_verify%& ACL
 control modifier. This should typically be done in the RCPT ACL, at points
@@ -38577,6 +38589,18 @@ senders).
 .section "Signing outgoing messages" "SECDKIMSIGN"
 .cindex "DKIM" "signing"
 
+.new
+For signing to be usable you must have published a DKIM record in DNS.
+Note that RFC 8301 says:
+.code
+rsa-sha1 MUST NOT be used for signing or verifying.
+
+Signers MUST use RSA keys of at least 1024 bits for all keys.
+Signers SHOULD use RSA keys of at least 2048 bits.
+.endd
+.wen
+.wen
+
 Signing is enabled by setting private options on the SMTP transport.
 These options take (expandable) strings as arguments.
 
@@ -38587,7 +38611,8 @@ 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.
 .wen
-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.
@@ -38596,8 +38621,9 @@ 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.
 .wen
+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.
@@ -38614,12 +38640,25 @@ 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.
 
 .new
+Note that RFC 8301 says:
+.code
+Signers MUST use RSA keys of at least 1024 bits for all keys.
+Signers SHOULD use RSA keys of at least 2048 bits.
+.endd
+.wen
+
 .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.
+method.
+
+.new
+Note that RFC 8301 says:
+.code
+rsa-sha1 MUST NOT be used for signing or verifying.
+.endd
+.wen
 
 .option dkim_identity smtp string&!! unset
 If set after expansion, the value is used to set an "i=" tag in
@@ -38781,7 +38820,7 @@ 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.
+This variable can be overwritten, with any value, using an ACL 'set' modifier.
 .wen
 
 .vitem &%$dkim_domain%&
@@ -38800,6 +38839,19 @@ The key record selector string.
 .vitem &%$dkim_algo%&
 The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'.
 
+.new
+Note that RFC 8301 says:
+.code
+rsa-sha1 MUST NOT be used for signing or verifying.
+
+DKIM signatures identified as having been signed with historic
+algorithms (currently, rsa-sha1) have permanently failed evaluation
+.endd
+
+To enforce this you must have a DKIM ACL which checks this variable
+and overwrites the &$dkim_verify_status$& variable as discussed above.
+.wen
+
 .vitem &%$dkim_canon_body%&
 The body canonicalization method. One of 'relaxed' or 'simple'.
 
@@ -38850,6 +38902,18 @@ Notes from the key record (tag n=).
 
 .vitem &%$dkim_key_length%&
 Number of bits in the key.
+
+.new
+Note that RFC 8301 says:
+.code
+Verifiers MUST NOT consider signatures using RSA keys of
+less than 1024 bits as valid signatures.
+.endd
+
+To enforce this you must have a DKIM ACL which checks this variable
+and overwrites the &$dkim_verify_status$& variable as discussed above.
+.wen
+
 .endlist
 
 In addition, two ACL conditions are provided: