Add observability variables and provision for avoiding OCSP conflicts

[users/heiko/exim.git] / doc / doc-txt / experimental-spec.txt

diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt
index 333307b74e9f1a7d78c5368ef2c572b1af19d340..c060a6c5a99856e2b7c77b9ccbbc767eaaced660 100644 (file)
--- a/doc/doc-txt/experimental-spec.txt
+++ b/doc/doc-txt/experimental-spec.txt
@@ -1181,7 +1181,10 @@ 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.
+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,
@@ -1214,20 +1217,48 @@ 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 fiels of SHA2-512(2).
+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).
-
-
-For client-side DANE there is a new smtp transport option,
-hosts_try_dane.  It does the obvious thing.
-[ may add a hosts_require_dane, too? ]
-[ should it be domain-based rather than host-based? ]
+be limited by the DNS TTL on the TLSA records).  However,
+this is likely to only be usable with DANE_TA.  NOTE: the
+default is to request OCSP for all hosts; the certificate
+chain in DANE_EE usage will be insufficient to validate
+the OCSP proof and verification will fail.  Either disable
+OCSP completely or use the (new) variable $tls_out_tlsa_usage
+like so:
+
+  hosts_request_ocsp = ${if or { {= {4}{$tls_out_tlsa_usage}} \
+                                {= {0}{$tls_out_tlsa_usage}} } \
+                         {*}{}}
+The variable 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_require_ocsp or
+hosts_request_ocsp includes the string "tls_out_tlsa_usage",
+they are re-expanded in time to control the OCSP request.
+
+[ All a bit complicated.  Should we make that definition
+the default?  Should we override the user's definition? ]
+
+
+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.
@@ -1240,12 +1271,18 @@ If dane is in use the following transport options are ignored:
   tls_verify_certificates
   tls_crl
   tls_verify_cert_hostnames
-  hosts_require_ocsp           (might rethink those two)
-  hosts_request_ocsp
 
 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_TPDA), and a new variable
+$tls_out_tlsa_usage (detailed above).
+
 
 --------------------------------------------------------------
 End of file