X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/774ef2d7d0f7fffbfd114271b8567e36485898dc..ad4c5ff9c1656eb9691fb1687ce7e0c59291ebda:/doc/doc-txt/experimental-spec.txt

diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt
index 2d34de0f7..4a2a04bb4 100644
--- a/doc/doc-txt/experimental-spec.txt
+++ b/doc/doc-txt/experimental-spec.txt
@@ -791,7 +791,7 @@ expansion is done.  The current list of events is:
  msg:fail:internal	after  main	  per recipient
  tcp:connect		before transport  per connection
  tcp:close		after  transport  per connection
- tls:cert		before transport  per certificate in verification chain
+ tls:cert		before both	  per certificate in verification chain
  smtp:connect		after  transport  per connection
 
 The expansion is called for all event types, and should use the $event_name
@@ -816,12 +816,12 @@ The following variables are likely to be useful depending on the event type:
 	tls_out_peercert
 	lookup_dnssec_authenticated, tls_out_dane
 	sending_ip_address, sending_port
-	message_exim_id
+	message_exim_id, verify_mode
 
 
 An example might look like:
 
-event_action = ${if = {msg:delivery}{$event_name} \
+event_action = ${if eq {msg:delivery}{$event_name} \
 {${lookup pgsql {SELECT * FROM record_Delivery( \
     '${quote_pgsql:$sender_address_domain}',\
     '${quote_pgsql:${lc:$sender_address_local_part}}', \
@@ -852,6 +852,10 @@ following will be forced:
 No other use is made of the result string.
 
 
+Known issues:
+- the tls:cert event is only called for the cert chain elements
+  received over the wire, with GnuTLS.  OpenSSL gives the entire
+  chain including thse loaded locally.
 
 
 Redis Lookup
@@ -1140,6 +1144,8 @@ the next hop does not support DSN.
 Adding it to a redirect router makes no difference.
 
 
+
+
 Certificate name checking
 --------------------------------------------------------------
 The X509 certificates used for TLS are supposed be verified
@@ -1147,16 +1153,33 @@ that they are owned by the expected host.  The coding of TLS
 support to date has not made these checks.
 
 If built with EXPERIMENTAL_CERTNAMES defined, code is
-included to do so, and a new smtp transport option
-"tls_verify_cert_hostname" supported which takes a list of
-names for which the checks must be made.  The host must
-also be in "tls_verify_hosts".
+included to do so for server certificates, and a new smtp transport option
+"tls_verify_cert_hostnames" supported which takes a hostlist
+which must match the target host for the additional checks must be made.
+The option currently defaults to empty, but this may change in
+the future.  "*" is probably a suitable value.
+Whether certificate verification is done at all, and the result of
+it failing, is stll under the control of "tls_verify_hosts" nad
+"tls_try_verify_hosts".
+
+The name being checked is that for the host, generally
+the result of an MX lookup.
 
 Both Subject and Subject-Alternate-Name certificate fields
 are supported, as are wildcard certificates (limited to
 a single wildcard being the initial component of a 3-or-more
 component FQDN).
 
+The equivalent check on the server for client certificates is not
+implemented.  At least one major email provider is using a client
+certificate which fails this check.  They do not retry either without
+the client certificate or in clear.
+
+It is possible to duplicate the effect of this checking by
+creative use of Events.
+
+
+
 
 DANE
 ------------------------------------------------------------
@@ -1279,12 +1302,13 @@ MX, A and TLSA records.
 
 A TLSA lookup will be done if either of the above options match
 and the host-lookup succeded using dnssec.
-If the TLSA lookup succeeds, a TLS connection will be required
-for the host.
+If a TLSA lookup is done and succeeds, a DANE-verified TLS connection
+will be required for the host.
 
 (TODO: specify when fallback happens vs. when the host is not used)
 
-If dane is in use the following transport options are ignored:
+If DANE is requested and useable (see above) the following transport
+options are ignored:
   hosts_require_tls
   tls_verify_hosts
   tls_try_verify_hosts
@@ -1292,6 +1316,10 @@ If dane is in use the following transport options are ignored:
   tls_crl
   tls_verify_cert_hostnames
 
+If DANE is not usable, whether requested or not, and CA-anchored
+verification evaluation is wanted, the above variables should be set
+appropriately.
+
 Currently dnssec_request_domains must be active (need to think about that)
 and dnssec_require_domains is ignored.
 
@@ -1300,7 +1328,7 @@ in the delivery log line will show as "CV=dane".
 
 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_TPDA), and a new variable
+in combination with EXPERIMENTAL_EVENT), and a new variable
 $tls_out_tlsa_usage (detailed above).