Docs: tidy DANE info

1 files changed, 15 insertions, 4 deletions

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index ec1e080bd..5ecee5057 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -30119,18 +30119,24 @@ DANE scales better than having to maintain (and communicate via side-channel) co
 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
+DANE requires a server operator to do three things:
+.olist
+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 is anchored by one of the TLSA records.
+.next
+Add TLSA DNS records.  These say what the server certificate for a TLS connection should be.
+.next
+Offer a server certificate, or certificate chain, in TLS connections which is is anchored by one of the TLSA records.
+.endlist
 
 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
 in &_Local/Makefile_&.
 If it has been included, the macro "_HAVE_DANE" will be defined.
 
+.subsection "DNS records"
 A TLSA record consist of 4 fields, the "Certificate Usage", the
 "Selector", the "Matching type", and the "Certificate Association Data".
 For a detailed description of the TLSA record see
@@ -30211,6 +30217,7 @@ libraries.
 This means no MD5 and no SHA-1.  SHA2-256 is the minimum for reliable
 interoperability (and probably the maximum too, in 2018).
 
+.subsection "Interaction with OCSP"
 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:
@@ -30231,6 +30238,7 @@ 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.
 
 
+.subsection "Client configuration"
 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
@@ -30269,6 +30277,7 @@ verification evaluation is wanted, the above variables should be set appropriate
 The router and transport option &%dnssec_request_domains%& must not be
 set to &"never"&, and &%dnssec_require_domains%& is ignored.
 
+.subsection Observability
 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
@@ -30284,11 +30293,13 @@ required.  This is intended to support TLS-reporting as defined in
 The &$event_data$& will be one of the Result Types defined in
 Section 4.3 of that document.
 
+.subsection General
 Under GnuTLS, DANE is only supported from version 3.0.0 onwards.
 
 DANE is specified in published RFCs and decouples certificate authority trust
 selection from a "race to the bottom" of "you must trust everything for mail
-to get through".  There is an alternative technology called MTA-STS, which
+to get through".
+There is an alternative technology called MTA-STS, which
 instead publishes MX trust anchor information on an HTTPS website.  At the
 time this text was last updated, MTA-STS was still a draft, not yet an RFC.
 Exim has no support for MTA-STS as a client, but Exim mail server operators