X-Git-Url: https://git.exim.org/users/heiko/exim.git/blobdiff_plain/cb78c1a805d1e86dad86d8eb031eb0517a62ec20..f3908561b1eef15d57608ab6b346125bf2a11478:/doc/doc-docbook/spec.xfpt?ds=sidebyside

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 295cb15c1..7d5b3b3cf 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
 
 
@@ -11936,6 +11938,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$&.
@@ -12891,6 +12900,7 @@ is compiled with the content-scanning extension. For details, see section
 .vitem &$spf_header_comment$& &&&
        &$spf_received$& &&&
        &$spf_result$& &&&
+       &$spf_result_guessed$& &&&
        &$spf_smtp_comment$&
 These variables are only available if Exim is built with SPF support.
 For details see section &<<SECSPF>>&.
@@ -26104,6 +26114,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
+
 
 
 
@@ -38916,6 +38932,20 @@ 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.
+
+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.
@@ -38930,6 +38960,21 @@ 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.
+
+As of writing, producing EC key materials is not well supported
+by the major libraries.  OpenSSL 1.1.1 and GnuTLS 3.6.0 can create private keys:
+.code
+openssl genpkey -algorithm ed25519 -out dkim_ed25519.private
+certtool --generate-privkey --key-type=ed25519 --outfile=dkim_ed25519.private
+.endd
+
+To help in producing the required public key value for a DNS record
+the release package &_util/_& directory contains source for a utility
+buildable with GnuTLS 3.6.0;
+use it like this:
+.code
+ed25519_privkey_pem_to_pubkey_raw_b64 dkim_ed25519.private
+.endd
 .wen
 
 .option dkim_hash smtp string&!! sha256
@@ -39000,6 +39045,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
@@ -39260,6 +39311,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"
@@ -39348,6 +39405,11 @@ variables:
   one of pass, fail, softfail, none, neutral, permerror or
   temperror.
 
+.vitem &$spf_result_guessed$&
+.vindex &$spf_result_guessed$&
+  This boolean is true only if a best-guess operation was used
+  and required in order to obtain a result.
+
 .vitem &$spf_smtp_comment$&
 .vindex &$spf_smtp_comment$&
   This contains a string that can be used in a SMTP response