ARC: enhance debug for signing; explicitly init signing context

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 675b0f14608bd97d8f1928c4c12c7b6af3bc891b..2dbe6d2d34b14112e0ad9e18f3718c2bbb87856e 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -52,7 +52,7 @@
 .set I   "    "
 
 .macro copyyear
 .set I   "    "
 
 .macro copyyear

-2017
+2018

 .endmacro
 
 . /////////////////////////////////////////////////////////////////////////////
 .endmacro
 
 . /////////////////////////////////////////////////////////////////////////////


@@ -7839,6 +7839,19 @@ ${lookup redis{set keyname ${quote_redis:objvalue plus}}}
 ${lookup redis{get keyname}}
 .endd
 
 ${lookup redis{get keyname}}
 .endd
 

+.new
+As of release 4.91, "lightweight" support for Redis Cluster is available.
+Requires &%redis_servers%& list to contain all the servers in the cluster, all
+of which must be reachable from the running exim instance. If the cluster has
+master/slave replication, the list must contain all the master and slave
+servers.
+
+When the Redis Cluster returns a "MOVED" response to a query, exim does not
+immediately follow the redirection but treats the response as a DEFER, moving on
+to the next server in the &%redis_servers%& list until the correct server is
+reached.
+.wen
+

 .ecindex IIDfidalo1
 .ecindex IIDfidalo2
 
 .ecindex IIDfidalo1
 .ecindex IIDfidalo2
 


@@ -9138,9 +9151,10 @@ If the ACL returns defer the result is a forced-fail.  Otherwise the expansion f
 
 
 .new
 
 
 .new

-.vitem "&*${authresults{*&<&'authserv-id&>&*}}*&"
+.vitem "&*${authresults{*&<&'authserv-id'&>&*}}*&"

 .cindex authentication "results header"
 .cindex headers "authentication-results:"
 .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.


@@ -9159,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
 
 


@@ -11580,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"


@@ -11923,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$&.


@@ -12878,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>>&.


@@ -26091,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
+

 
 
 
 
 
 


@@ -28153,7 +28187,16 @@ If verification was successful using DANE then the "CV" item in the delivery log
 
 There is a new variable &$tls_out_dane$& which will have "yes" if
 verification succeeded using DANE and "no" otherwise (only useful
 
 There is a new variable &$tls_out_dane$& which will have "yes" if
 verification succeeded using DANE and "no" otherwise (only useful

-in combination with EXPERIMENTAL_EVENT), and a new variable &$tls_out_tlsa_usage$& (detailed above).
+in combination with events; see &<<CHAPevents>>&),
+and a new variable &$tls_out_tlsa_usage$& (detailed above).
+
+.cindex DANE reporting
+An event (see &<<CHAPevents>>&) of type "dane:fail" will be raised on failures
+to achieve DANE-verified connection, if one was either requested and offered, or
+required.  This is intended to support TLS-reporting as defined in
+&url(https://tools.ietf.org/html/draft-ietf-uta-smtp-tlsrpt-17).
+The &$event_data$& will be one of the Result Types defined in
+Section 4.3 of that document.

 
 Under GnuTLS, DANE is only supported from version 3.0.0 onwards.
 .wen
 
 Under GnuTLS, DANE is only supported from version 3.0.0 onwards.
 .wen


@@ -31797,9 +31840,9 @@ though individual ones can be included or not at build time:
 .vitem &%avast%&
 .cindex "virus scanners" "avast"
 This is the scanner daemon of Avast. It has been tested with Avast Core
 .vitem &%avast%&
 .cindex "virus scanners" "avast"
 This is the scanner daemon of Avast. It has been tested with Avast Core

-Security (currently at version 1.1.7).
-You can get a trial version at &url(http://www.avast.com) or for Linux
-at &url(http://www.avast.com/linux-server-antivirus).
+Security (currently at version 2.2.0).
+You can get a trial version at &url(https://www.avast.com) or for Linux
+at &url(https://www.avast.com/linux-server-antivirus).

 This scanner type takes one option,
 which can be either a full path to a UNIX socket,
 or host and port specifiers separated by white space.
 This scanner type takes one option,
 which can be either a full path to a UNIX socket,
 or host and port specifiers separated by white space.


@@ -31826,6 +31869,8 @@ $ socat UNIX:/var/run/avast/scan.sock STDIO:
     PACK
 .endd
 
     PACK
 .endd
 

+Only the first virus detected will be reported.
+

 
 .vitem &%aveserver%&
 .cindex "virus scanners" "Kaspersky"
 
 .vitem &%aveserver%&
 .cindex "virus scanners" "Kaspersky"


@@ -38879,7 +38924,8 @@ The result can either
 be a valid RSA private key in ASCII armor (.pem file), including line breaks
 .new
 .next
 be a valid RSA private key in ASCII armor (.pem file), including line breaks
 .new
 .next

-with GnuTLS 3.6.0 or later, be a valid Ed25519 private key (same format as above)
+with GnuTLS 3.6.0 or OpenSSL 1.1.1 or later,
+be a valid Ed25519 private key (same format as above)

 .wen
 .next
 start with a slash, in which case it is treated as a file that contains
 .wen
 .next
 start with a slash, in which case it is treated as a file that contains


@@ -38891,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.


@@ -38905,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


@@ -38975,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


@@ -39040,11 +39119,13 @@ This variable can be overwritten using an ACL 'set' modifier.
 This might, for instance, be done to enforce a policy restriction on
 hash-method or key-size:
 .code
 This might, for instance, be done to enforce a policy restriction on
 hash-method or key-size:
 .code

-  warn condition =     ${if eq {$dkim_algo}{rsa-sha1}}
-       condition =     ${if eq {$dkim_verify_status}{pass}}
+  warn condition =     ${if eq {$dkim_verify_status}{pass}}
+       condition =     ${if eq {$len_3:$dkim_algo}{rsa}}
+       condition =     ${if or {eq {$dkim_algo}{rsa-sha1}} \
+                               {< {$dkim_key_length}{1024}} }

        logwrite =      NOTE: forcing dkim verify fail (was pass)
        set dkim_verify_status = fail
        logwrite =      NOTE: forcing dkim verify fail (was pass)
        set dkim_verify_status = fail

-       set dkim_verify_reason = hash too weak
+       set dkim_verify_reason = hash too weak or key too short

 .endd
 
 After all the DKIM ACL runs have completed, the value becomes a
 .endd
 
 After all the DKIM ACL runs have completed, the value becomes a


@@ -39088,7 +39169,8 @@ The key record selector string.
 .vitem &%$dkim_algo%&
 The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'.
 .new
 .vitem &%$dkim_algo%&
 The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'.
 .new

-If running under GnuTLS 3.6.0 or later, may also be 'ed25519-sha256'.
+If running under GnuTLS 3.6.0 or OpenSSL 1.1.1 or later,
+may also be 'ed25519-sha256'.

 The "_CRYPTO_SIGN_ED25519" macro will be defined if support is present
 for EC keys.
 .wen
 The "_CRYPTO_SIGN_ED25519" macro will be defined if support is present
 for EC keys.
 .wen


@@ -39133,6 +39215,9 @@ UNIX timestamp reflecting the date and time when the signer wants the
 signature to be treated as "expired". When this was not specified by the
 signer, "9999999999999" is returned. This makes it possible to do useful
 integer size comparisons against this value.
 signature to be treated as "expired". When this was not specified by the
 signer, "9999999999999" is returned. This makes it possible to do useful
 integer size comparisons against this value.

+.new
+Note that Exim does not check this value.
+.wen

 
 .vitem &%$dkim_headernames%&
 A colon-separated list of names of headers included in the signature.
 
 .vitem &%$dkim_headernames%&
 A colon-separated list of names of headers included in the signature.


@@ -39166,6 +39251,7 @@ less than 1024 bits as valid signatures.
 
 To enforce this you must have a DKIM ACL which checks this variable
 and overwrites the &$dkim_verify_status$& variable as discussed above.
 
 To enforce this you must have a DKIM ACL which checks this variable
 and overwrites the &$dkim_verify_status$& variable as discussed above.

+As EC keys are much smaller, the check should only do this for RSA keys.

 .wen
 
 .endlist
 .wen
 
 .endlist


@@ -39228,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"


@@ -39257,18 +39349,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.
 
 .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.
 
 .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
 .endlist
 
 You can prefix each string with an exclamation mark to  invert


@@ -39316,6 +39401,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


@@ -39703,6 +39793,7 @@ expansion must check this, as it will be called for every possible event type.
 
 The current list of events is:
 .display
 
 The current list of events is:
 .display

+&`dane:fail              after    transport  `& per connection

 &`msg:complete           after    main       `& per message
 &`msg:delivery           after    transport  `& per recipient
 &`msg:rcpt:host:defer    after    transport  `& per recipient per host
 &`msg:complete           after    main       `& per message
 &`msg:delivery           after    transport  `& per recipient
 &`msg:rcpt:host:defer    after    transport  `& per recipient per host


@@ -39731,6 +39822,7 @@ should define the event action.
 An additional variable, &$event_data$&, is filled with information varying
 with the event type:
 .display
 An additional variable, &$event_data$&, is filled with information varying
 with the event type:
 .display

+&`dane:fail            `& failure reason

 &`msg:delivery         `& smtp confirmation message
 &`msg:rcpt:host:defer  `& error string
 &`msg:rcpt:defer       `& error string
 &`msg:delivery         `& smtp confirmation message
 &`msg:rcpt:host:defer  `& error string
 &`msg:rcpt:defer       `& error string


@@ -39758,15 +39850,12 @@ The expansion of the event_action option should normally
 return an empty string.  Should it return anything else the
 following will be forced:
 .display
 return an empty string.  Should it return anything else the
 following will be forced:
 .display

-&`msg:delivery     `&  (ignored)
-&`msg:host:defer   `&  (ignored)
-&`msg:fail:delivery`&  (ignored)

 &`tcp:connect      `&  do not connect
 &`tcp:connect      `&  do not connect

-&`tcp:close        `&  (ignored)

 &`tls:cert         `&  refuse verification
 &`smtp:connect     `&  close connection
 .endd
 &`tls:cert         `&  refuse verification
 &`smtp:connect     `&  close connection
 .endd

-No other use is made of the result string.
+All other message types ignore the result string, and
+no other use is made of it.

 
 For a tcp:connect event, if the connection is being made to a proxy
 then the address and port variables will be that of the proxy and not
 
 For a tcp:connect event, if the connection is being made to a proxy
 then the address and port variables will be that of the proxy and not