diff options
Diffstat (limited to 'doc/doc-docbook/spec.xfpt')
| -rw-r--r-- | doc/doc-docbook/spec.xfpt | 158 |
1 files changed, 157 insertions, 1 deletions
diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index e237ce1f2..bb7e2cf97 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -12985,6 +12985,10 @@ and then set to the outgoing cipher suite if one is negotiated. See chapter &<<CHAPTLS>>& for details of TLS support and chapter &<<CHAPsmtptrans>>& for details of the &(smtp)& transport. +.vitem &$tls_out_dane$& +.vindex &$tls_out_dane$& +DANE active status. See section &<<SECDANE>>&. + .vitem &$tls_in_ocsp$& .vindex "&$tls_in_ocsp$&" When a message is received from a remote client connection @@ -13050,6 +13054,10 @@ During outbound SMTP deliveries, this variable reflects the value of the &%tls_sni%& option on the transport. +.vitem &$tls_out_tlsa_usage$& +.vindex &$tls_out_tlsa_usage$& +Bitfield of TLSA record types found. See section &<<SECDANE>>&. + .vitem &$tod_bsdinbox$& .vindex "&$tod_bsdinbox$&" The time of day and the date, in the format required for BSD-style mailbox @@ -24201,6 +24209,17 @@ Exim will request a Certificate Status on a TLS session for any host that matches this list. &%tls_verify_certificates%& should also be set for the transport. +.new +.option hosts_require_dane smtp "host list&!!" unset +.cindex DANE "transport options" +.cindex DANE "requiring for certain servers" +If built with DANE support, Exim will require that a DNSSEC-validated +TLSA record is present for any host matching the list, +and that a DANE-verified TLS connection is made. +There will be no fallback to in-clear communication. +See section &<<SECDANE>>&. +.wen + .option hosts_require_ocsp smtp "host list&!!" unset .cindex "TLS" "requiring for certain servers" Exim will request, and check for a valid Certificate Status being given, on a @@ -24230,6 +24249,18 @@ This option provides a list of servers to which, provided they announce CHUNKING support, Exim will attempt to use BDAT commands rather than DATA. BDAT will not be used in conjunction with a transport filter. +.new +.option hosts_try_dane smtp "host list&!!" unset +.cindex DANE "transport options" +.cindex DANE "attempting for certain servers" +If built with DANE support, Exim will lookup a +TLSA record for any host matching the list. +If found and verified by DNSSEC, +a DANE-verified TLS connection is made to that host; +there will be no fallback to in-clear communication. +See section &<<SECDANE>>&. +.wen + .option hosts_try_fastopen smtp "host list&!!" unset .cindex "fast open, TCP" "enabling, in client" .cindex "TCP Fast Open" "enabling, in client" @@ -27986,6 +28017,124 @@ Open-source PKI book, available online at +.new +.section DANE "SECDANE" +.cindex 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. +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. + +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, &url(https://www.huque.com/bin/gen_tlsa) +is useful for quickly generating TLSA records; and commands like + +.code + openssl x509 -in -pubkey -noout <certificate.pem \ + | openssl rsa -outform der -pubin 2>/dev/null \ + | openssl sha512 \ + | awk '{print $2}' +.endd + +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: + +.code + hosts_request_ocsp = ${if or { {= {0}{$tls_out_tlsa_usage}} \ + {= {4}{$tls_out_tlsa_usage}} } \ + {*}{}} +.endd + +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%&. +The latter variant will result in failure if the target host is not DNSSEC-secured. + +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 succeeded using dnssec. +If a TLSA lookup is done and succeeds, a DANE-verified TLS connection +will be required for the host. If it does not, the host will not +be used; there is no fallback to non-DANE or non-TLS. + +If DANE is requested and useable (see above) the following transport options are ignored: +.code + hosts_require_tls + tls_verify_hosts + tls_try_verify_hosts + tls_verify_certificates + tls_crl + tls_verify_cert_hostnames +.endd + +If DANE is not usable, whether requested or not, and CA-anchored +verification evaluation is wanted, the above variables should be set appropriately. + +Currently the &%dnssec_request_domains%& must be active 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). + +Under GnuTLS, DANE is only supported from version 3.0.0 onwards. +.wen + + + . //////////////////////////////////////////////////////////////////////////// . //////////////////////////////////////////////////////////////////////////// @@ -36627,9 +36776,16 @@ specifies whether characters with values greater than 127 should be logged unchanged, or whether they should be rendered as escape sequences. .next .cindex "log" "certificate verification" +.cindex log DANE +.cindex DANE logging &%tls_certificate_verified%&: An extra item is added to <= and => log lines when TLS is in use. The item is &`CV=yes`& if the peer's certificate was -verified, and &`CV=no`& if not. +verified +.new +using a CA trust anchor, +&`CA=dane`& if using a DNS trust anchor, +.wen +and &`CV=no`& if not. .next .cindex "log" "TLS cipher" .cindex "TLS" "logging cipher" |