DKIM: document proper Ed25519 key-generation methods; remove helper program

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 295cb15c19c5a4d856292f4cb2adca61bf87f635..814afc1ebe5810079e501175398a4df6467f9393 100644 (file)
--- 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:"
 .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.
 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
 .code
       add_header = :at_start:${authresults {$primary_hostname}}
 .endd

+This is safe even if no authentication reselts are available.

 .wen
 
 
 .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$&.
 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.
 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"
 
 .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$&.
 
 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$&.
 .vitem &$host_lookup_failed$&
 .vindex "&$host_lookup_failed$&"
 See &$host_lookup_deferred$&.


@@ -12891,6 +12905,7 @@ is compiled with the content-scanning extension. For details, see section
 .vitem &$spf_header_comment$& &&&
        &$spf_received$& &&&
        &$spf_result$& &&&
 .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>>&.
        &$spf_smtp_comment$&
 These variables are only available if Exim is built with SPF support.
 For details see section &<<SECSPF>>&.


@@ -26104,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.
 
 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 +38937,21 @@ is set.
 .endlist
 
 .new
 .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.
 Note that RFC 8301 says:
 .code
 Signers MUST use RSA keys of at least 1024 bits for all keys.


@@ -38930,6 +38966,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.
 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
 .wen
 
 .option dkim_hash smtp string&!! sha256


@@ -39000,6 +39048,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.
 
 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
 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 +39314,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.
 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"
 
 .cindex SPF "ACL condition"
 .cindex ACL "spf condition"


@@ -39348,6 +39408,11 @@ variables:
   one of pass, fail, softfail, none, neutral, permerror or
   temperror.
 
   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
 .vitem &$spf_smtp_comment$&
 .vindex &$spf_smtp_comment$&
   This contains a string that can be used in a SMTP response