X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/2be324ee17454ae5c5a32a3533aced861d103074..c679ee08b006c8fe4c62b353d909c992a725fc11:/doc/doc-docbook/spec.xfpt?ds=sidebyside diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 2c783d700..585f5e310 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -7839,6 +7839,17 @@ ${lookup redis{set keyname ${quote_redis:objvalue plus}}} ${lookup redis{get keyname}} .endd +As of release 4.91, "lightweight" support for Redis Cluster is available. +Requires &%redis_servers%& list to contain all the servers in the cluster, all +of which must be reachable from the running exim instance. If the cluster has +master/slave replication, the list must contain all the master and slave +servers. + +When the Redis Cluster returns a "MOVED" response to a query, exim does not +immediately follow the redirection but treats the response as a DEFER, moving on +to the next server in the &%redis_servers%& list until the correct server is +reached. + .ecindex IIDfidalo1 .ecindex IIDfidalo2 @@ -9137,6 +9148,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" @@ -12985,6 +13021,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 @@ -13050,6 +13090,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 @@ -24201,6 +24245,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 @@ -24230,6 +24285,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" @@ -27986,6 +28053,133 @@ 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 events; see &<>&), +and a new variable &$tls_out_tlsa_usage$& (detailed above). + +.cindex DANE reporting +An event (see &<>&) of type "dane:fail" will be raised on failures +to achieve DANE-verified connection, if one was either requested and offered, or +required. This is intended to support TLS-reporting as defined in +&url(https://tools.ietf.org/html/draft-ietf-uta-smtp-tlsrpt-17). +The &$event_data$& will be one of the Result Types defined in +Section 4.3 of that document. + +Under GnuTLS, DANE is only supported from version 3.0.0 onwards. +.wen + + + . //////////////////////////////////////////////////////////////////////////// . //////////////////////////////////////////////////////////////////////////// @@ -31623,9 +31817,9 @@ though individual ones can be included or not at build time: .vitem &%avast%& .cindex "virus scanners" "avast" This is the scanner daemon of Avast. It has been tested with Avast Core -Security (currently at version 1.1.7). -You can get a trial version at &url(http://www.avast.com) or for Linux -at &url(http://www.avast.com/linux-server-antivirus). +Security (currently at version 2.2.0). +You can get a trial version at &url(https://www.avast.com) or for Linux +at &url(https://www.avast.com/linux-server-antivirus). This scanner type takes one option, which can be either a full path to a UNIX socket, or host and port specifiers separated by white space. @@ -31652,6 +31846,8 @@ $ socat UNIX:/var/run/avast/scan.sock STDIO: PACK .endd +Only the first virus detected will be reported. + .vitem &%aveserver%& .cindex "virus scanners" "Kaspersky" @@ -36627,9 +36823,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" @@ -38859,11 +39062,13 @@ This variable can be overwritten using an ACL 'set' modifier. This might, for instance, be done to enforce a policy restriction on hash-method or key-size: .code - warn condition = ${if eq {$dkim_algo}{rsa-sha1}} - condition = ${if eq {$dkim_verify_status}{pass}} + warn condition = ${if eq {$dkim_verify_status}{pass}} + condition = ${if eq {$len_3:$dkim_algo}{rsa}} + condition = ${if or {eq {$dkim_algo}{rsa-sha1}} \ + {< {$dkim_key_length}{1024}} } logwrite = NOTE: forcing dkim verify fail (was pass) set dkim_verify_status = fail - set dkim_verify_reason = hash too weak + set dkim_verify_reason = hash too weak or key too short .endd After all the DKIM ACL runs have completed, the value becomes a @@ -38952,6 +39157,9 @@ UNIX timestamp reflecting the date and time when the signer wants the signature to be treated as "expired". When this was not specified by the signer, "9999999999999" is returned. This makes it possible to do useful integer size comparisons against this value. +.new +Note that Exim does not check this value. +.wen .vitem &%$dkim_headernames%& A colon-separated list of names of headers included in the signature. @@ -38985,6 +39193,7 @@ less than 1024 bits as valid signatures. To enforce this you must have a DKIM ACL which checks this variable and overwrites the &$dkim_verify_status$& variable as discussed above. +As EC keys are much smaller, the check should only do this for RSA keys. .wen .endlist @@ -39359,7 +39568,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. @@ -39397,6 +39606,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. @@ -39408,7 +39618,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/ @@ -39516,6 +39731,7 @@ expansion must check this, as it will be called for every possible event type. The current list of events is: .display +&`dane:fail after transport `& per connection &`msg:complete after main `& per message &`msg:delivery after transport `& per recipient &`msg:rcpt:host:defer after transport `& per recipient per host @@ -39544,6 +39760,7 @@ should define the event action. An additional variable, &$event_data$&, is filled with information varying with the event type: .display +&`dane:fail `& failure reason &`msg:delivery `& smtp confirmation message &`msg:rcpt:host:defer `& error string &`msg:rcpt:defer `& error string @@ -39571,15 +39788,12 @@ The expansion of the event_action option should normally return an empty string. Should it return anything else the following will be forced: .display -&`msg:delivery `& (ignored) -&`msg:host:defer `& (ignored) -&`msg:fail:delivery`& (ignored) &`tcp:connect `& do not connect -&`tcp:close `& (ignored) &`tls:cert `& refuse verification &`smtp:connect `& close connection .endd -No other use is made of the result string. +All other message types ignore the result string, and +no other use is made of it. For a tcp:connect event, if the connection is being made to a proxy then the address and port variables will be that of the proxy and not