Support REQUIRETLS

[exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 52a26591a632f67c65aae02de7000b12aa199d47..d0e3358b8d9d7c040a667cdda06741646a245568 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -3966,8 +3966,17 @@ the messages are active, their status is not altered. This option can be used
 only by an admin user or by the user who originally caused the message to be
 placed on the queue.
 
+. .new
+. .vitem &%-MS%&
+. .oindex "&%-MS%&"
+. .cindex REQUIRETLS
+. This option is used to request REQUIRETLS processing on the message.
+. It is used internally by Exim in conjunction with -E when generating
+. a bounce message.
+. .wen
+
 .vitem &%-Mset%&&~<&'message&~id'&>
-.oindex "&%-Mset%&
+.oindex "&%-Mset%&"
 .cindex "testing" "string expansion"
 .cindex "expansion" "testing"
 This option is useful only in conjunction with &%-be%& (that is, when testing
@@ -28164,22 +28173,29 @@ Support for client-side operation of DANE can be included at compile time by def
 in &_Local/Makefile_&.
 If it has been included, the macro "_HAVE_DANE" will be defined.
 
-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.
+The TLSA record for the server may have "certificate usage" of DANE-TA(2) or DANE-EE(3).
+These are the "Trust Anchor" and "End Entity" variants.
+The latter specifies the End Entity directly, i.e. the certificate involved is that of the server
+(and if only DANE-EE is used then it 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.
+well-known one.
+A private CA at simplest is just a self-signed certificate (with certain
+attributes) which is used to sign cerver certificates, but running one securely
+does require careful arrangement.
+With DANE-TA, as implemented in Exim and commonly in other MTAs,
+the server TLS handshake must transmit the entire certificate chain from CA to server-certificate.
 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.
-
-Another approach which should be seriously considered is to use DANE with a certificate
-from a public CA, because of another technology, "MTA-STS", described below.
+DANE-TA and DANE-EE can both be used together.
 
 .new
+Our recommendation is to use DANE with a certificate from a public CA,
+because this enables a variety of strategies for remote clients to verify
+your certificate.
+You can then publish information both via DANE and another technology,
+"MTA-STS", described below.
+
 When you use DANE-TA to publish trust anchor information, you ask entities
 outside your administrative control to trust the Certificate Authority for
 connections to you.
@@ -28308,8 +28324,8 @@ MTA-STS to let those clients who do use that protocol derive trust
 information.
 
 The MTA-STS design requires a certificate from a public Certificate Authority
-which is recognized by clients sending to you.  That selection is outside your
-control.
+which is recognized by clients sending to you.
+That selection of which CAs are trusted by others is outside your control.
 
 The most interoperable course of action is probably to use
 &url(https://letsencrypt.org/,Let's Encrypt), with automated certificate
@@ -39279,8 +39295,10 @@ hash-method or key-size:
        set dkim_verify_reason = hash too weak or key too short
 .endd
 
-After all the DKIM ACL runs have completed, the value becomes a
+So long as a DKIM ACL is defined (it need do no more than accept),
+after all the DKIM ACL runs have completed, the value becomes a
 colon-separated list of the values after each run.
+This is maintained for the mime, prdr and data ACLs.
 
 .vitem &%$dkim_verify_reason%&
 A string giving a little bit more detail when &%$dkim_verify_status%& is either