From 1dcdf90a3f6df9436f1873a036a985671ef8815d Mon Sep 17 00:00:00 2001 From: "Heiko Schlittermann (HS12-RIPE)" Date: Tue, 17 Sep 2019 22:35:00 +0200 Subject: [PATCH] Docs: Adjust on TLSA, dnssec_request_domains --- doc/doc-docbook/spec.xfpt | 63 ++++++++++++++++++++++++++------------- src/src/configure.default | 6 +++- 2 files changed, 47 insertions(+), 22 deletions(-) diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 624381018..ac7bf4dd2 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -6109,6 +6109,9 @@ dnslookup: domains = ! +local_domains transport = remote_smtp ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8 +.ifdef _HAVE_DNSSEC + dnssec_request_domains = * +.endif no_more .endd The &%domains%& option behaves as per smarthost, above. @@ -6260,7 +6263,6 @@ remote_smtp: driver = smtp message_size_limit = ${if > {$max_received_linelength}{998} {1}{0}} .ifdef _HAVE_DANE - dnssec_request_domains = * hosts_try_dane = * .endif .ifdef _HAVE_PRDR @@ -6271,7 +6273,7 @@ This transport is used for delivering messages over SMTP connections. The list of remote hosts comes from the router. The &%message_size_limit%& usage is a hack to avoid sending on messages with over-long lines. The built-in macro _HAVE_DANE guards configuration -to try to use DNSSEC for all queries and to use DANE for delivery; +to use DANE for delivery; see section &<>& for more details. The &%hosts_try_prdr%& option enables an efficiency SMTP option. It is @@ -24526,8 +24528,9 @@ details. .cindex "security" "MX lookup" .cindex "DNS" "DNSSEC" DNS lookups for domains matching &%dnssec_request_domains%& will be done with -the dnssec request bit set. -This applies to all of the SRV, MX, AAAA, A lookup sequence. +the dnssec request bit set. Setting this transport option is only useful if the +transport overrides or sets the host names. See the &%dnssec_request_domains%& +router option. @@ -24537,9 +24540,9 @@ This applies to all of the SRV, MX, AAAA, A lookup sequence. .cindex "security" "MX lookup" .cindex "DNS" "DNSSEC" DNS lookups for domains matching &%dnssec_require_domains%& will be done with -the dnssec request bit set. Any returns not having the Authenticated Data bit -(AD bit) set will be ignored and logged as a host-lookup failure. -This applies to all of the SRV, MX, AAAA, A lookup sequence. +the dnssec request bit set. Setting this transport option is only +useful if the transport overrides or sets the host names. See the +&%dnssec_require_domains%& router option. @@ -24818,7 +24821,8 @@ TLS session for any host that matches this list. .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. +and that a DANE-verified TLS connection is made. See +the &%dnssec_request_domains%& router and transport options. There will be no fallback to in-clear communication. See section &<>&. @@ -24854,11 +24858,11 @@ BDAT will not be used in conjunction with a transport filter. .option hosts_try_dane smtp "host list&!!" * .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. +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. See +the &%dnssec_request_domains%& router and transport options. +There will be no fallback to in-clear communication. See section &<>&. .option hosts_try_fastopen smtp "host list&!!" * @@ -28866,7 +28870,12 @@ 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). +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 +&url(https://tools.ietf.org/html/rfc7671#page-5,RFC 7671). + +The TLSA record for the server may have "Certificate Usage" (1st) field 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); @@ -28907,19 +28916,29 @@ If you're not already using a private CA, or it doesn't meet these requirements, then we encourage you to avoid all these issues and use a public CA such as &url(https://letsencrypt.org/,Let's Encrypt) instead. -The TLSA record should have a Selector field of SPKI(1) and a Matching Type field of SHA2-512(2). +The TLSA record should have a "Selector" (2nd) field of SPKI(1) and +a "Matching Type" (3rd) 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 +For the "Certificate Authority Data" (4th) field, commands like .code - openssl x509 -in -pubkey -noout /dev/null \ | openssl sha512 \ | awk '{print $2}' .endd -are workable for 4th-field hashes. +are workable to create a hash of the certificate's public key. + +An example TLSA record for DANE-EE(3), SPKI(1), and SHA-512 (2) looks like + +.code + _25._tcp.mail.example.com. TLSA 3 1 2 8BA8A336E... +.endd + +At the time of writing, &url(https://www.huque.com/bin/gen_tlsa) +is useful for quickly generating TLSA records. + For use with the DANE-TA model, server certificates must have a correct name (SubjectName or SubjectAltName). @@ -28953,7 +28972,9 @@ those who use &%hosts_require_ocsp%&, should consider the interaction with DANE 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 DNSSEC-secured. +The require variant will result in failure if the target host is not +DNSSEC-secured. To get DNSSEC-secured hostname resolution, use +the &%dnssec_request_domains%& router or transport option. DANE will only be usable if the target host has DNSSEC-secured MX, A and TLSA records. @@ -28983,7 +29004,7 @@ If DANE is requested and useable (see above) the following transport options are 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. +Currently the (router or transport options) &%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". diff --git a/src/src/configure.default b/src/src/configure.default index 555dec3ec..95e7d49d7 100644 --- a/src/src/configure.default +++ b/src/src/configure.default @@ -658,6 +658,9 @@ smarthost: transport = smarthost_smtp route_data = ROUTER_SMARTHOST ignore_target_hosts = <; 0.0.0.0 ; 127.0.0.0/8 ; ::1 +.ifdef _HAVE_DNSSEC + dnssec_request_domains = * +.endif no_more .else @@ -682,7 +685,9 @@ dnslookup: ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8 # if ipv6-enabled then instead use: # ignore_target_hosts = <; 0.0.0.0 ; 127.0.0.0/8 ; ::1 +.ifdef _HAVE_DNSSEC dnssec_request_domains = * +.endif no_more # This closes the ROUTER_SMARTHOST ifdef around the choice of routing for @@ -805,7 +810,6 @@ remote_smtp: driver = smtp message_size_limit = ${if > {$max_received_linelength}{998} {1}{0}} .ifdef _HAVE_DANE - dnssec_request_domains = * hosts_try_dane = * .endif .ifdef _HAVE_PRDR -- 2.30.2