Docs for transport tls_verify_hosts &c.

[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 cab1c82dd56ec925b188f5b9450fb187c3076540..8ddc3df5170f053bcbf7a7933a6bf61aa1390e85 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -10247,7 +10247,7 @@ If the ACL returns defer the result is a forced-fail.
 .cindex "&%bool%& expansion condition"
 This condition turns a string holding a true or false representation into
 a boolean state.  It parses &"true"&, &"false"&, &"yes"& and &"no"&
 .cindex "&%bool%& expansion condition"
 This condition turns a string holding a true or false representation into
 a boolean state.  It parses &"true"&, &"false"&, &"yes"& and &"no"&

-(case-insensitively); also positive integer numbers map to true if non-zero,
+(case-insensitively); also integer numbers map to true if non-zero,

 false if zero.
 An empty string is treated as false.
 Leading and trailing whitespace is ignored;
 false if zero.
 An empty string is treated as false.
 Leading and trailing whitespace is ignored;


@@ -23027,6 +23027,14 @@ unknown state), opens a new one to the same host, and then tries the delivery
 in clear.
 
 
 in clear.
 
 

+.option tls_try_verify_hosts smtp "host list&!! unset
+.cindex "TLS" "server certificate verification"
+.cindex "certificate" "verification of server"
+This option gives a list of hosts for which, on encrypted connections,
+certificate verification will be tried but need not succeed.
+The &%tls_verify_certificates%& option must also be set.
+
+

 .option tls_verify_certificates smtp string&!! unset
 .cindex "TLS" "server certificate verification"
 .cindex "certificate" "verification of server"
 .option tls_verify_certificates smtp string&!! unset
 .cindex "TLS" "server certificate verification"
 .cindex "certificate" "verification of server"


@@ -23041,6 +23049,20 @@ single file if you are using GnuTLS. The values of &$host$& and
 &$host_address$& are set to the name and address of the server during the
 expansion of this option. See chapter &<<CHAPTLS>>& for details of TLS.
 
 &$host_address$& are set to the name and address of the server during the
 expansion of this option. See chapter &<<CHAPTLS>>& for details of TLS.
 

+For back-compatability,
+if neither tls_verify_hosts nor tls_try_verify_hosts are set
+and certificate verification fails the TLS connection is closed.
+
+
+.option tls_verify_hosts smtp "host list&!! unset
+.cindex "TLS" "server certificate verification"
+.cindex "certificate" "verification of server"
+This option gives a list of hosts for which. on encrypted connections,
+certificate verification must succeed.
+The &%tls_verify_certificates%& option must also be set.
+If both this option and &%tls_try_verify_hosts%& are unset
+operation is as if this option selected all hosts.
+

 
 
 
 
 
 


@@ -25942,6 +25964,12 @@ for OpenSSL only (not GnuTLS), a directory, that contains a collection of
 expected server certificates. The client verifies the server's certificate
 against this collection, taking into account any revoked certificates that are
 in the list defined by &%tls_crl%&.
 expected server certificates. The client verifies the server's certificate
 against this collection, taking into account any revoked certificates that are
 in the list defined by &%tls_crl%&.

+Failure to verify fails the TLS connection unless either of the
+&%tls_verify_hosts%& or &%tls_try_verify_hosts%& options are set.
+
+The &%tls_verify_hosts%& and &%tls_try_verify_hosts%& options restrict
+certificate verification to the listed servers.  Verification either must
+or need not succeed respectively.

 
 If
 &%tls_require_ciphers%& is set on the &(smtp)& transport, it must contain a
 
 If
 &%tls_require_ciphers%& is set on the &(smtp)& transport, it must contain a


@@ -27302,8 +27330,12 @@ from one SMTP connection to another.  If a recipient-verify callout connection i
 requested in the same ACL it is held open and used for the data, otherwise one is made
 after the ACL completes.
 
 requested in the same ACL it is held open and used for the data, otherwise one is made
 after the ACL completes.
 

-Note that routers are used in verify mode.  Note also that headers cannot be
+Note that routers are used in verify mode,
+and cannot depend on content of received headers.
+Note also that headers cannot be

 modified by any of the post-data ACLs (DATA, MIME and DKIM).
 modified by any of the post-data ACLs (DATA, MIME and DKIM).

+Headers may be modified by routers (subject to the above) and transports.
+

 Cutthrough delivery is not supported via transport-filters or when DKIM signing
 of outgoing messages is done, because it sends data to the ultimate destination
 before the entire message has been received from the source.
 Cutthrough delivery is not supported via transport-filters or when DKIM signing
 of outgoing messages is done, because it sends data to the ultimate destination
 before the entire message has been received from the source.


@@ -29007,6 +29039,7 @@ router that does not set up hosts routes to an &(smtp)& transport with a
 &%hosts%& setting, the transport's hosts are used. If an &(smtp)& transport has
 &%hosts_override%& set, its hosts are always used, whether or not the router
 supplies a host list.
 &%hosts%& setting, the transport's hosts are used. If an &(smtp)& transport has
 &%hosts_override%& set, its hosts are always used, whether or not the router
 supplies a host list.

+Callouts are only supported on &(smtp)& transports.

 
 The port that is used is taken from the transport, if it is specified and is a
 remote transport. (For routers that do verification only, no transport need be
 
 The port that is used is taken from the transport, if it is specified and is a
 remote transport. (For routers that do verification only, no transport need be