diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/doc-docbook/spec.xfpt | 158 | ||||
-rw-r--r-- | doc/doc-txt/ChangeLog | 3 | ||||
-rw-r--r-- | doc/doc-txt/NewStuff | 4 | ||||
-rw-r--r-- | doc/doc-txt/experimental-spec.txt | 156 |
4 files changed, 162 insertions, 159 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" diff --git a/doc/doc-txt/ChangeLog b/doc/doc-txt/ChangeLog index 370e1b7e7..988c509bb 100644 --- a/doc/doc-txt/ChangeLog +++ b/doc/doc-txt/ChangeLog @@ -103,6 +103,9 @@ JH/19 Speed up macro lookups during configuration file read, by skipping non- macro text after a replacement (previously it was only once per line) and by skipping builtin macros when searching for an uppercase lead character. +JH/20 DANE support moved from Experimental to mainline. The Makefile control + for the build is renamed. + Exim version 4.90 ----------------- diff --git a/doc/doc-txt/NewStuff b/doc/doc-txt/NewStuff index e123910c2..180f4b8a7 100644 --- a/doc/doc-txt/NewStuff +++ b/doc/doc-txt/NewStuff @@ -12,8 +12,8 @@ Version 4.91 1. Dual-certificate stacks on servers now support OCSP stapling, under GnuTLS version 3.5.6 or later. - 2. DANE is now supported under GnuTLS version 3.0.0 or later (adding to the - previous OpenSSL implementation, but still Experimental). + 2. DANE is now supported under GnuTLS version 3.0.0 or later. Both GnuTLS and + OpenSSL versions are moved to mainline support from Experimental. 3. Feature macros for the compiled-in set of malware scanner interfaces. diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt index 855f9899a..d5140d58b 100644 --- a/doc/doc-txt/experimental-spec.txt +++ b/doc/doc-txt/experimental-spec.txt @@ -611,162 +611,6 @@ b. Configure, somewhere before the DATA ACL, the control option to -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. -[ should they be domain-based rather than host-based? ] - -Hosts_require_dane 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: - 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). - -Under GnuTLS, DANE is only supported from versin 3.0.0 onwards - - - DSN extra information --------------------- If compiled with EXPERIMENTAL_DSN_INFO extra information will be added |