DANE: smtp transport option dane_require_tls_ciphers

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index bb7e2cf97e50e505b1e0c145469de53ac9c60a31..8e78c7bad6e102c59555b339fa4813f1d2804c77 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.
 
 
 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"
 .vitem "&*${certextract{*&<&'field'&>&*}{*&<&'certificate'&>&*}&&&
        {*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&"
 .cindex "expansion" "extracting certificate fields"


@@ -23888,6 +23913,24 @@ For testing purposes, this value can be overridden by the &%-oB%& command line
 option.
 
 
 option.
 
 

+.new
+.option dane_require_tls_ciphers smtp string&!! unset
+.cindex "TLS" "requiring specific ciphers for DANE"
+.cindex "cipher" "requiring specific"
+.cindex DANE "TLS ciphers"
+This option may be used to override &%tls_require_ciphers%& for connections
+where DANE has been determined to be in effect.
+If not set, then &%tls_require_ciphers%& will be used.
+Normal SMTP delivery is not able to make strong demands of TLS cipher
+configuration, because delivery will fall back to plaintext.  Once DANE has
+been determined to be in effect, there is no plaintext fallback and making the
+TLS cipherlist configuration stronger will increase security, rather than
+counter-intuitively decreasing it.
+If the option expands to be empty or is forced to fail, then it will
+be treated as unset and &%tls_require_ciphers%& will be used instead.
+.wen
+
+

 .option data_timeout smtp time 5m
 This sets a timeout for the transmission of each block in the data portion of
 the message. As a result, the overall timeout for a message depends on the size
 .option data_timeout smtp time 5m
 This sets a timeout for the transmission of each block in the data portion of
 the message. As a result, the overall timeout for a message depends on the size


@@ -28043,8 +28086,7 @@ that DNS lookups they do for the server have not been tampered with.  The domain
 to this server, its A record, its TLSA record and any associated CNAME records must all be covered by
 DNSSEC.
 2) add TLSA DNS records.  These say what the server certificate for a TLS connection should be.
 to this server, its A record, its TLSA record and any associated CNAME records must all be covered by
 DNSSEC.
 2) add TLSA DNS records.  These say what the server certificate for a TLS connection should be.

-3) offer a server certificate, or certificate chain, in TLS connections which is traceable to the one
-defined by (one of?) the TSLA records
+3) offer a server certificate, or certificate chain, in TLS connections which is is anchored by one of the TLSA records.

 
 There are no changes to Exim specific to server-side operation of DANE.
 Support for client-side operation of DANE can be included at compile time by defining SUPPORT_DANE=yes
 
 There are no changes to Exim specific to server-side operation of DANE.
 Support for client-side operation of DANE can be included at compile time by defining SUPPORT_DANE=yes


@@ -28099,8 +28141,9 @@ This modification of hosts_request_ocsp is only done if it has the default value
 those who use &%hosts_require_ocsp%&, should consider the interaction with DANE in their OCSP settings.
 
 
 those who use &%hosts_require_ocsp%&, should consider the interaction with DANE in their OCSP settings.
 
 

-For client-side DANE there are two new smtp transport options, &%hosts_try_dane%& and &%hosts_require_dane%&.
-The latter variant will result in failure if the target host is not DNSSEC-secured.
+For client-side DANE there are three new smtp transport options, &%hosts_try_dane%&, &%hosts_require_dane%&
+and &%dane_require_tls_ciphers%&.
+The require variant will result in failure if the target host is not DNSSEC-secured.

 
 DANE will only be usable if the target host has DNSSEC-secured MX, A and TLSA records.
 
 
 DANE will only be usable if the target host has DNSSEC-secured MX, A and TLSA records.
 


@@ -28109,6 +28152,14 @@ If a TLSA lookup is done and succeeds, a DANE-verified TLS connection
 will be required for the host.  If it does not, the host will not
 be used; there is no fallback to non-DANE or non-TLS.
 
 will be required for the host.  If it does not, the host will not
 be used; there is no fallback to non-DANE or non-TLS.
 

+If DANE is requested and usable, then the TLS cipher list configuration
+prefers to use the option &%dane_require_tls_ciphers%& and falls
+back to &%tls_require_ciphers%& only if that is unset.
+This lets you configure "decent crypto" for DANE and "better than nothing
+crypto" as the default.  Note though that while GnuTLS lets the string control
+which versions of TLS/SSL will be negotiated, OpenSSL does not and you're
+limited to ciphersuite constraints.
+

 If DANE is requested and useable (see above) the following transport options are ignored:
 .code
   hosts_require_tls
 If DANE is requested and useable (see above) the following transport options are ignored:
 .code
   hosts_require_tls


@@ -28128,7 +28179,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


@@ -31772,9 +31832,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.


@@ -31801,6 +31861,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"


@@ -39015,11 +39077,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


@@ -39108,6 +39172,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.


@@ -39141,6 +39208,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


@@ -39678,6 +39746,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


@@ -39706,6 +39775,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


@@ -39733,15 +39803,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