Add non-mtp source info to ${authres }

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 67ade7b04a524af83adc05111aa3f4482ede5cd8..b65b6fe5b6cc60e4e4b633d3fa5efaadffb94c60 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -11595,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"
@@ -38932,6 +38937,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.
@@ -38946,6 +38966,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