PRDR: append overall DATA acceptance message to delivery log line "C=" item. Bug...

[user/henk/code/exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index bb7e2cf97e50e505b1e0c145469de53ac9c60a31..f950a4dac31e9d6754c6e89b99c3f3f1bafcaa2b 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -9137,6 +9137,31 @@ the expansion result is an empty string.
 If the ACL returns defer the result is a forced-fail.  Otherwise the expansion fails.
 
 
+.new
+.vitem "&*${authresults{*&<&'authserv-id'&>&*}}*&"
+.cindex authentication "results header"
+.cindex headers "authentication-results:"
+This item returns a string suitable for insertion as an
+&'Authentication-Results"'&
+header line.
+The given <&'authserv-id'&> is included in the result; typically this
+will ba a domain name identifying the system performing the authentications.
+Methods that may be present in the result include:
+.code
+none
+iprev
+auth
+spf
+dkim
+.endd
+
+Example use (as an ACL modifier):
+.code
+      add_header = :at_start:${authresults {$primary_hostname}}
+.endd
+.wen
+
+
 .vitem "&*${certextract{*&<&'field'&>&*}{*&<&'certificate'&>&*}&&&
        {*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&"
 .cindex "expansion" "extracting certificate fields"
@@ -28128,7 +28153,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
-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
@@ -39015,11 +39049,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
-  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
-       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
@@ -39108,6 +39144,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.
+.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.
@@ -39141,6 +39180,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.
+As EC keys are much smaller, the check should only do this for RSA keys.
 .wen
 
 .endlist
@@ -39678,6 +39718,7 @@ expansion must check this, as it will be called for every possible event type.
 
 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
@@ -39706,6 +39747,7 @@ should define the event action.
 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
@@ -39733,15 +39775,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
-&`msg:delivery     `&  (ignored)
-&`msg:host:defer   `&  (ignored)
-&`msg:fail:delivery`&  (ignored)
 &`tcp:connect      `&  do not connect
-&`tcp:close        `&  (ignored)
 &`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