X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/0719afe27105e35ad40805dabb66dbbcb44dab52..405074adb94eb8402e9ffd0abe7da4f7c8c827bc:/doc/doc-docbook/spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index c29ab47ba..9722c0063 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -9154,6 +9154,7 @@ If the ACL returns defer the result is a forced-fail.  Otherwise the expansion f
 .vitem "&*${authresults{*&<&'authserv-id'&>&*}}*&"
 .cindex authentication "results header"
 .cindex headers "authentication-results:"
+.cindex authentication "expansion item"
 This item returns a string suitable for insertion as an
 &'Authentication-Results"'&
 header line.
@@ -9172,6 +9173,7 @@ Example use (as an ACL modifier):
 .code
       add_header = :at_start:${authresults {$primary_hostname}}
 .endd
+This is safe even if no authentication reselts are available.
 .wen
 
 
@@ -11593,10 +11595,15 @@ preserve some of the authentication information in the variable
 user/password authenticator configuration might preserve the user name for use
 in the routers. Note that this is not the same information that is saved in
 &$sender_host_authenticated$&.
+
 When a message is submitted locally (that is, not over a TCP connection)
 the value of &$authenticated_id$& is normally the login name of the calling
 process. However, a trusted user can override this by means of the &%-oMai%&
 command line option.
+.new
+This second case also sets up inforamtion used by the
+&$authresults$& expansion item.
+.wen
 
 .vitem &$authenticated_fail_id$&
 .cindex "authentication" "fail" "id"
@@ -11936,6 +11943,13 @@ lookup succeeds, but there is a lookup problem such as a timeout when checking
 the result, the name is not accepted, and &$host_lookup_deferred$& is set to
 &"1"&. See also &$sender_host_name$&.
 
+.new
+.cindex authentication "expansion item"
+Performing these checks sets up information used by the
+&$authresults$& expansion item.
+.wen
+
+
 .vitem &$host_lookup_failed$&
 .vindex "&$host_lookup_failed$&"
 See &$host_lookup_deferred$&.
@@ -26105,6 +26119,12 @@ public name) of the authenticator driver that successfully authenticated the
 client from which the message was received. This variable is empty if there was
 no successful authentication.
 
+.new
+.cindex authentication "expansion item"
+Successful authentication sets up information used by the
+&$authresults$& expansion item.
+.wen
+
 
 
 
@@ -28082,8 +28102,7 @@ that DNS lookups they do for the server have not been tampered with.  The domain
 to this server, its A record, its TLSA record and any associated CNAME records must all be covered by
 DNSSEC.
 2) add TLSA DNS records.  These say what the server certificate for a TLS connection should be.
-3) offer a server certificate, or certificate chain, in TLS connections which is traceable to the one
-defined by (one of?) the TSLA records
+3) offer a server certificate, or certificate chain, in TLS connections which is is anchored by one of the TLSA records.
 
 There are no changes to Exim specific to server-side operation of DANE.
 Support for client-side operation of DANE can be included at compile time by defining SUPPORT_DANE=yes
@@ -28138,8 +28157,9 @@ This modification of hosts_request_ocsp is only done if it has the default value
 those who use &%hosts_require_ocsp%&, should consider the interaction with DANE in their OCSP settings.
 
 
-For client-side DANE there are two new smtp transport options, &%hosts_try_dane%& and &%hosts_require_dane%&.
-The latter variant will result in failure if the target host is not DNSSEC-secured.
+For client-side DANE there are three new smtp transport options, &%hosts_try_dane%&, &%hosts_require_dane%&
+and &%dane_require_tls_ciphers%&.
+The require variant will result in failure if the target host is not DNSSEC-secured.
 
 DANE will only be usable if the target host has DNSSEC-secured MX, A and TLSA records.
 
@@ -28148,6 +28168,14 @@ If a TLSA lookup is done and succeeds, a DANE-verified TLS connection
 will be required for the host.  If it does not, the host will not
 be used; there is no fallback to non-DANE or non-TLS.
 
+If DANE is requested and usable, then the TLS cipher list configuration
+prefers to use the option &%dane_require_tls_ciphers%& and falls
+back to &%tls_require_ciphers%& only if that is unset.
+This lets you configure "decent crypto" for DANE and "better than nothing
+crypto" as the default.  Note though that while GnuTLS lets the string control
+which versions of TLS/SSL will be negotiated, OpenSSL does not and you're
+limited to ciphersuite constraints.
+
 If DANE is requested and useable (see above) the following transport options are ignored:
 .code
   hosts_require_tls
@@ -38917,6 +38945,21 @@ is set.
 .endlist
 
 .new
+To generate keys under OpenSSL:
+.code
+openssl genrsa -out dkim_rsa.private 2048
+openssl rsa -in dkim_rsa.private -out /dev/stdout -pubout -outform PEM
+.endd
+Take the base-64 lines from the output of the second command, concatenated,
+for the DNS TXT record.
+See section 3.6 of RFC6376 for the record specification.
+
+Under GnuTLS:
+.code
+certtool --generate-privkey --rsa --bits=2048 --password='' -8 --outfile=dkim_rsa.private
+certtool --load-privkey=dkim_rsa.private --pubkey-info
+.endd
+
 Note that RFC 8301 says:
 .code
 Signers MUST use RSA keys of at least 1024 bits for all keys.
@@ -38931,6 +38974,18 @@ As they are a recent development, users should consider dual-signing
 for some transition period.
 The "_CRYPTO_SIGN_ED25519" macro will be defined if support is present
 for EC keys.
+
+OpenSSL 1.1.1 and GnuTLS 3.6.0 can create Ed25519 private keys:
+.code
+openssl genpkey -algorithm ed25519 -out dkim_ed25519.private
+certtool --generate-privkey --key-type=ed25519 --outfile=dkim_ed25519.private
+.endd
+
+To produce the required public key value for a DNS record:
+.code
+openssl pkey -outform DER -pubout -in dkim_ed25519.private | tail -c +13 | base64
+certtool --load_privkey=dkim_ed25519.private --pubkey_info --outder | tail -c +13 | base64
+.endd
 .wen
 
 .option dkim_hash smtp string&!! sha256
@@ -39001,6 +39056,12 @@ To evaluate the signature in the ACL a large number of expansion variables
 containing the signature status and its details are set up during the
 runtime of the ACL.
 
+.new
+.cindex authentication "expansion item"
+Performing verification sets up information used by the
+&$authresults$& expansion item.
+.wen
+
 Calling the ACL only for existing signatures is not sufficient to build
 more advanced policies. For that reason, the global option
 &%dkim_verify_signers%&, and a global expansion variable
@@ -39261,6 +39322,12 @@ 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.
+.new
+.cindex authentication "expansion item"
+Performing verification sets up information used by the
+&$authresults$& expansion item.
+.wen
+
 
 .cindex SPF "ACL condition"
 .cindex ACL "spf condition"
@@ -39290,18 +39357,11 @@ 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)
+You may deny messages when this occurs.
 
 .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