X-Git-Url: https://git.exim.org/users/heiko/exim.git/blobdiff_plain/286b9d5fa4344de72fe6575fa089237fd7dbb56f..dec766a1977250758eb7a3e127e079a9271afd89:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index b5865e966..c1e451d4d 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -3162,6 +3162,10 @@ If invoked by an admin user, then &%macro%&, &%macro_list%& and &%macros%& are available, similarly to the drivers. Because macros are sometimes used for storing passwords, this option is restricted. The output format is one item per line. +.new +For the "-bP macro " form, if no such macro is found +the exit status will be nonzero. +.wen .vitem &%-bp%& .oindex "&%-bp%&" @@ -9133,6 +9137,31 @@ the expansion result is an empty string. If the ACL returns defer the result is a forced-fail. Otherwise the expansion fails. +.new +.vitem "&*${authresults{*&<&'authserv-id'&>&*}}*&" +.cindex authentication "results header" +.cindex headers "authentication-results:" +This item returns a string suitable for insertion as an +&'Authentication-Results"'& +header line. +The given <&'authserv-id'&> is included in the result; typically this +will ba a domain name identifying the system performing the authentications. +Methods that may be present in the result include: +.code +none +iprev +auth +spf +dkim +.endd + +Example use (as an ACL modifier): +.code + add_header = :at_start:${authresults {$primary_hostname}} +.endd +.wen + + .vitem "&*${certextract{*&<&'field'&>&*}{*&<&'certificate'&>&*}&&& {*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&" .cindex "expansion" "extracting certificate fields" @@ -10648,6 +10677,7 @@ The &%sha3%& expansion item is only supported if Exim has been compiled with GnuTLS 3.5.0 or later, .new or OpenSSL 1.1.1 or later. +The macro "_CRYPTO_HASH_SHA3" will be defined if it is supported. .wen @@ -12980,6 +13010,10 @@ and then set to the outgoing cipher suite if one is negotiated. See chapter &<>& for details of TLS support and chapter &<>& for details of the &(smtp)& transport. +.vitem &$tls_out_dane$& +.vindex &$tls_out_dane$& +DANE active status. See section &<>&. + .vitem &$tls_in_ocsp$& .vindex "&$tls_in_ocsp$&" When a message is received from a remote client connection @@ -13045,6 +13079,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 &<>&. + .vitem &$tod_bsdinbox$& .vindex "&$tod_bsdinbox$&" The time of day and the date, in the format required for BSD-style mailbox @@ -24196,6 +24234,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 &<>&. +.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 @@ -24225,6 +24274,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 &<>&. +.wen + .option hosts_try_fastopen smtp "host list&!!" unset .cindex "fast open, TCP" "enabling, in client" .cindex "TCP Fast Open" "enabling, in client" @@ -27981,6 +28042,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 /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 + + + . //////////////////////////////////////////////////////////////////////////// . //////////////////////////////////////////////////////////////////////////// @@ -36622,9 +36801,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" @@ -38663,7 +38849,6 @@ for the former it is the base64 of the ASN.1 for the RSA public key (equivalent to the private-key .pem with the header/trailer stripped) but for EC keys it is the base64 of the pure key; no ASN.1 wrapping. .wen -.wen Signing is enabled by setting private options on the SMTP transport. These options take (expandable) strings as arguments. @@ -38710,6 +38895,7 @@ Note that RFC 8301 says: .code Signers MUST use RSA keys of at least 1024 bits for all keys. Signers SHOULD use RSA keys of at least 2048 bits. +.endd Support for EC keys is being developed under &url(https://datatracker.ietf.org/doc/draft-ietf-dcrup-dkim-crypto/). @@ -38717,7 +38903,8 @@ They are considerably smaller than RSA keys for equivalent protection. As they are a recent development, users should consider dual-signing (by setting a list of selectors, and an expansion for this option) for some transition period. -.endd +The "_CRYPTO_SIGN_ED25519" macro will be defined if support is present +for EC keys. .wen .option dkim_hash smtp string&!! sha256 @@ -38902,6 +39089,8 @@ The key record selector string. The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'. .new If running under GnuTLS 3.6.0 or later, may also be 'ed25519-sha256'. +The "_CRYPTO_SIGN_ED25519" macro will be defined if support is present +for EC keys. .wen .new @@ -39351,7 +39540,7 @@ This will add a component tagged with &"PRX="& to the line. .cindex internationalisation "email address" .cindex EAI .cindex i18n -.cindex UTF-8 "mail name handling" +.cindex utf8 "mail name handling" Exim has support for Internationalised mail names. To include this it must be built with SUPPORT_I18N and the libidn library. @@ -39389,6 +39578,7 @@ form of the name. .cindex log protocol .cindex SMTPUTF8 logging +.cindex i18n logging Log lines and Received-by: header lines will acquire a "utf8" prefix on the protocol element, eg. utf8esmtp. @@ -39400,7 +39590,12 @@ ${utf8_localpart_to_alabel:str} ${utf8_localpart_from_alabel:str} .endd -ACLs may use the following modifier: +.cindex utf8 "address downconversion" +.cindex i18n "utf8 address downconversion" +.new +The RCPT ACL +.wen +may use the following modifier: .display control = utf8_downconvert control = utf8_downconvert/