Docs thinko
[users/heiko/exim.git] / doc / doc-txt / experimental-spec.txt
index d8bd0bf46ed103f0641f603a8231e5c958531f61..4a2a04bb4eb53e721fe24fefaa5063a542e88d54 100644 (file)
@@ -759,11 +759,12 @@ b. Configure, somewhere before the DATA ACL, the control option to
 
 
 
 
 
 
-Transport post-delivery actions
+Event Actions
 --------------------------------------------------------------
 
 --------------------------------------------------------------
 
-An arbitrary per-transport string can be expanded upon various transport events
-and (for SMTP transports) a second string on deferrals caused by a host error.
+(Renamed from TPDA, Transport post-delivery actions)
+
+An arbitrary per-transport string can be expanded upon various transport events.
 Additionally a main-section configuration option can be expanded on some
 per-message events.
 This feature may be used, for example, to write exim internal log information
 Additionally a main-section configuration option can be expanded on some
 per-message events.
 This feature may be used, for example, to write exim internal log information
@@ -771,33 +772,33 @@ This feature may be used, for example, to write exim internal log information
 
 In order to use the feature, you must compile with
 
 
 In order to use the feature, you must compile with
 
-EXPERIMENTAL_TPDA=yes
+EXPERIMENTAL_EVENT=yes
 
 in your Local/Makefile
 
 and define one or both of
 
 in your Local/Makefile
 
 and define one or both of
-- the tpda_event_action option in the transport
-- the delivery_event_action
+- the event_action option in the transport
+- the event_action main option
 to be expanded when the event fires.
 
 to be expanded when the event fires.
 
-A new variable, $tpda_event, is set to the event type when the
+A new variable, $event_name, is set to the event type when the
 expansion is done.  The current list of events is:
 
 expansion is done.  The current list of events is:
 
      msg:complete            main            per message
      msg:delivery            transport       per recipient
      msg:host:defer          transport       per attempt
      msg:fail:delivery       main            per recipient
      msg:fail:internal       main            per recipient
      tcp:connect             transport       per connection
      tcp:close               transport       per connection
      tls:cert                transport       per certificate in verification chain
      smtp:connect            transport       per connection
-
-The expansion is called for all event types, and should use the $tpda_event
msg:complete          after  main       per message
msg:delivery          after  transport  per recipient
msg:host:defer                after  transport  per attempt
msg:fail:delivery     after  main       per recipient
msg:fail:internal     after  main       per recipient
tcp:connect           before transport  per connection
tcp:close             after  transport  per connection
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
 value to decide when to act.  The variable data is a colon-separated
 list, describing an event tree.
 
 value to decide when to act.  The variable data is a colon-separated
 list, describing an event tree.
 
-There is an auxilary variable, $tpda_data, for which the
+There is an auxilary variable, $event_data, for which the
 content is event_dependent:
 
        msg:delivery            smtp confirmation mssage
 content is event_dependent:
 
        msg:delivery            smtp confirmation mssage
@@ -805,7 +806,7 @@ content is event_dependent:
        tls:cert                verification chain depth
        smtp:connect            smtp banner
 
        tls:cert                verification chain depth
        smtp:connect            smtp banner
 
-The msg:host:defer event populates one extra variable, $tpda_defer_errno.
+The msg:host:defer event populates one extra variable, $event_defer_errno.
 
 The following variables are likely to be useful depending on the event type:
 
 
 The following variables are likely to be useful depending on the event type:
 
@@ -815,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
        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:
 
 
 
 An example might look like:
 
-tpda_event_action = ${if = {msg:delivery}{$tpda_event} \
+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}}', \
 {${lookup pgsql {SELECT * FROM record_Delivery( \
     '${quote_pgsql:$sender_address_domain}',\
     '${quote_pgsql:${lc:$sender_address_local_part}}', \
@@ -831,12 +832,12 @@ tpda_event_action = ${if = {msg:delivery}{$tpda_event} \
     '${quote_pgsql:$message_exim_id}')}} \
 } {}}
 
     '${quote_pgsql:$message_exim_id}')}} \
 } {}}
 
-The string is expanded for each of the supported events and any
-side-effects will happen.  The result is then discarded.
+The string is expanded when each of the supported events occur
+and any side-effects of the expansion will happen.
 Note that for complex operations an ACL expansion can be used.
 
 
 Note that for complex operations an ACL expansion can be used.
 
 
-The expansion of the tpda_event_action option should normally
+The expansion of the event_action option should normally
 return an empty string.  Should it return anything else the
 following will be forced:
 
 return an empty string.  Should it return anything else the
 following will be forced:
 
@@ -848,8 +849,13 @@ following will be forced:
        tls:cert        refuse verification
        smtp:connect    close connection
 
        tls:cert        refuse verification
        smtp:connect    close connection
 
+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
 
 
 Redis Lookup
@@ -1137,6 +1143,9 @@ in a router. Exim will then send the success DSN himself if requested as if
 the next hop does not support DSN.
 Adding it to a redirect router makes no difference.
 
 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
 Certificate name checking
 --------------------------------------------------------------
 The X509 certificates used for TLS are supposed be verified
@@ -1144,16 +1153,183 @@ 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
 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).
 
 
 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
+------------------------------------------------------------
+DNS-based Authentication of Named Entities, as applied
+to SMTP over TLS, provides assurance to a client that
+it is actually talking to the server it wants to rather
+than some attacker operating a Man In The Middle (MITM)
+operation.  The latter can terminate the TLS connection
+you make, and make another one to the server (so both
+you and the server still think you have an encrypted
+connection) and, if one of the "well known" set of
+Certificate Authorities has been suborned - something
+which *has* been seen already (2014), a verifiable
+certificate (if you're using normal root CAs, eg. the
+Mozilla set, as your trust anchors).
+
+What DANE does is replace the CAs with the DNS as the
+trust anchor.  The assurance is limited to a) the possibility
+that the DNS has been suborned, b) mistakes made by the
+admins of the target server.   The attack surface presented
+by (a) is thought to be smaller than that of the set
+of root CAs.
+
+It also allows the server to declare (implicitly) that
+connections to it should use TLS.  An MITM could simply
+fail to pass on a server's STARTTLS.
+
+DANE scales better than having to maintain (and
+side-channel communicate) copies of server certificates
+for every possible target server.  It also scales
+(slightly) better than having to maintain on an SMTP
+client a copy of the standard CAs bundle.  It also
+means not having to pay a CA for certificates.
+
+DANE requires a server operator to do three things:
+1) run DNSSEC.  This provides assurance to clients
+that DNS lookups they do for the server have not
+been tampered with.  The domain MX record applying
+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
+
+There are no changes to Exim specific to server-side
+operation of DANE.
+
+The TLSA record for the server may have "certificate
+usage" of DANE-TA(2) or DANE-EE(3).  The latter specifies
+the End Entity directly, i.e. the certificate involved
+is that of the server (and should be the sole one transmitted
+during the TLS handshake); this is appropriate for a
+single system, using a self-signed certificate.
+  DANE-TA usage is effectively declaring a specific CA
+to be used; this might be a private CA or a public,
+well-known one.  A private CA at simplest is just
+a self-signed certificate which is used to sign
+cerver certificates, but running one securely does
+require careful arrangement.  If a private CA is used
+then either all clients must be primed with it, or
+(probably simpler) the server TLS handshake must transmit
+the entire certificate chain from CA to server-certificate.
+If a public CA is used then all clients must be primed with it
+(losing one advantage of DANE) - but the attack surface is
+reduced from all public CAs to that single CA.
+DANE-TA is commonly used for several services and/or
+servers, each having a TLSA query-domain CNAME record,
+all of which point to a single TLSA record.
+
+The TLSA record should have a Selector field of SPKI(1)
+and a Matching Type field of SHA2-512(2).
+
+At the time of writing, https://www.huque.com/bin/gen_tlsa
+is useful for quickly generating TLSA records; and commands like
+
+  openssl x509 -in -pubkey -noout <certificate.pem \
+  | openssl rsa -outform der -pubin 2>/dev/null \
+  | openssl sha512 \
+  | awk '{print $2}'
+
+are workable for 4th-field hashes.
+
+For use with the DANE-TA model, server certificates
+must have a correct name (SubjectName or SubjectAltName).
+
+The use of OCSP-stapling should be considered, allowing
+for fast revocation of certificates (which would otherwise
+be limited by the DNS TTL on the TLSA records).  However,
+this is likely to only be usable with DANE-TA.  NOTE: the
+default of requesting OCSP for all hosts is modified iff
+DANE is in use, to:
+
+  hosts_request_ocsp = ${if or { {= {0}{$tls_out_tlsa_usage}} \
+                                {= {4}{$tls_out_tlsa_usage}} } \
+                         {*}{}}
+
+The (new) variable $tls_out_tlsa_usage is a bitfield with
+numbered bits set for TLSA record usage codes.
+The zero above means DANE was not in use,
+the four means that only DANE-TA usage TLSA records were
+found. If the definition of hosts_request_ocsp includes the
+string "tls_out_tlsa_usage", they are re-expanded in time to
+control the OCSP request.
+
+This modification of hosts_request_ocsp is only done if
+it has the default value of "*".  Admins who change it, and
+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.  They do the obvious thing.
+[ should they be domain-based rather than host-based? ]
+
+DANE will only be usable if the target host has DNSSEC-secured
+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 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 requested and useable (see above) the following transport
+options are ignored:
+  hosts_require_tls
+  tls_verify_hosts
+  tls_try_verify_hosts
+  tls_verify_certificates
+  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.
+
+If verification was successful using DANE then the "CV" item
+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_EVENT), and a new variable
+$tls_out_tlsa_usage (detailed above).
 
 
 --------------------------------------------------------------
 
 
 --------------------------------------------------------------