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 <name>" form, if no such macro is found
+the exit status will be nonzero.
+.wen
.vitem &%-bp%&
.oindex "&%-bp%&"
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"
separator used for the output list is the same as the one used for the
input, but a separator setting is not included in the output. For example:
.code
-${filter{a:b:c}{!eq{$item}{b}}
+${filter{a:b:c}{!eq{$item}{b}}}
.endd
yields &`a:c`&. At the end of the expansion, the value of &$item$& is restored
to what it was before. See also the &*map*& and &*reduce*& expansion items.
with 256 being the default.
The &%sha3%& expansion item is only supported if Exim has been
-compiled with GnuTLS 3.5.0 or later.
+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
.vitem &*${stat:*&<&'string'&>&*}*&
.vindex "&$config_file$&"
The name of the main configuration file Exim is using.
-.vitem &$dkim_verify_status$& &&&
+.vitem &$dkim_verify_status$&
Results of DKIM verification.
For details see section &<<SECDKIMVFY>>&.
&<<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
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
will need to be aware of the potential different format.
Using any of the ACL conditions noted will negate the reception benefit
-(as a Unix-mbox-format file is contructed for them).
-The transimssion benefit is maintained.
+(as a Unix-mbox-format file is constructed for them).
+The transmission benefit is maintained.
.option sqlite_lock_timeout main time 5s
.cindex "sqlite lookup type" "lock timeout"
separator in the usual way to avoid confusion under IPv6.
&*Note*&: Under current versions of OpenSSL, when a list of more than one
-file is used, the &$tls_in_ourcert$& veriable is unreliable.
+file is used, the &$tls_in_ourcert$& variable is unreliable.
&*Note*&: OCSP stapling is not usable under OpenSSL
when a list of more than one file is used.
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
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"
On (at least some) current Linux distributions the facility must be enabled
in the kernel by the sysadmin before the support is usable.
There is no option for control of the server side; if the system supports
-it it is always enebled. Note that legthy operations in the connect ACL,
+it it is always enabled. Note that lengthy operations in the connect ACL,
such as DNSBL lookups, will still delay the emission of the SMTP banner.
.option hosts_try_prdr smtp "host list&!!" *
When Exim has been built with TLS support, it advertises the availability of
the STARTTLS command to client hosts that match &%tls_advertise_hosts%&,
but not to any others. The default value of this option is *, which means
-that STARTTLS is alway advertised. Set it to blank to never advertise;
-this is reasonble for systems that want to use TLS only as a client.
+that STARTTLS is always advertised. Set it to blank to never advertise;
+this is reasonable for systems that want to use TLS only as a client.
If STARTTLS is to be used you
need to set some other options in order to make TLS available.
An older mode of operation can be enabled on a per-host basis by the
&%hosts_noproxy_tls%& option on the &(smtp)& transport. If the host matches
-this list the proxy process descibed above is not used; instead Exim
+this list the proxy process described above is not used; instead Exim
shuts down an existing TLS session being run by the delivery process
before passing the socket to a new process. The new process may then
try to start a new TLS session, and if successful, may try to re-authenticate
+.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
+
+
+
. ////////////////////////////////////////////////////////////////////////////
. ////////////////////////////////////////////////////////////////////////////
.code
require verify = recipient/callout=use_sender,hold
.endd
-It causes the connection to be helod open and used for any further recipients
+It causes the connection to be held open and used for any further recipients
and for eventual delivery (should that be done quickly).
Doing this saves on TCP and SMTP startup costs, and TLS costs also
when that is used for the connections.
As an example, the following will ban &"HTML mail"& (including that sent with
alternative plain text), while allowing HTML files to be attached. HTML
-coverletter mail attached to non-HMTL coverletter mail will also be allowed:
+coverletter mail attached to non-HTML coverletter mail will also be allowed:
.code
deny message = HTML mail is not accepted here
!condition = $mime_is_rfc822
.new
.cindex log "DKIM verification"
.cindex DKIM "verification logging"
-&%dkim%&: For message acceptance log lines, when an DKIM signture in the header
+&%dkim%&: For message acceptance log lines, when an DKIM signature in the header
verifies successfully a tag of DKIM is added, with one of the verified domains.
.next
.cindex log "DKIM verification"
.next
.cindex "log" "millisecond timestamps"
.cindex millisecond logging
-.cindex timstamps "millisecond, in logs"
+.cindex timestamps "millisecond, in logs"
&%millisec%&: Timestamps have a period and three decimal places of finer granularity
appended to the seconds value.
.next
off the &%outgoing_interface%& option.
.next
.cindex "log" "outgoing remote port"
-.cindex "port" "logging outgoint remote"
+.cindex "port" "logging outgoing remote"
.cindex "TCP/IP" "logging outgoing remote port"
&%outgoing_port%&: The remote port number is added to delivery log lines (those
containing => tags) following the IP address.
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"
DKIM is a mechanism by which messages sent by some entity can be provably
linked to a domain which that entity controls. It permits reputation to
be tracked on a per-domain basis, rather than merely upon source IP address.
-DKIM is documented in RFC 4871.
+DKIM is documented in RFC 6376.
.new
As DKIM relies on the message being unchanged in transit, messages handled
Signers MUST use RSA keys of at least 1024 bits for all keys.
Signers SHOULD use RSA keys of at least 2048 bits.
.endd
-.wen
+
+Note also that the key content (the 'p=' field)
+in the DNS record is different between RSA and EC keys;
+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
Signing is enabled by setting private options on the SMTP transport.
&%$dkim_selector%& expansion variables to determine the private key to use.
The result can either
.ilist
-be a valid RSA private key in ASCII armor, including line breaks.
+be a valid RSA private key in ASCII armor (.pem file), including line breaks
+.new
+.next
+with GnuTLS 3.6.0 or later, be a valid Ed25519 private key (same format as above)
+.wen
.next
start with a slash, in which case it is treated as a file that contains
-the private key.
+the private key
.next
be "0", "false" or the empty string, in which case the message will not
be signed. This case will not result in an error, even if &%dkim_strict%&
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/).
+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.
+The "_CRYPTO_SIGN_ED25519" macro will be defined if support is present
+for EC keys.
.wen
.option dkim_hash smtp string&!! sha256
The default list is available for the expansion in the macro
"_DKIM_SIGN_HEADERS".
-If a name is repeated, multiple headers by that name (or the absence therof)
+If a name is repeated, multiple headers by that name (or the absence thereof)
will be signed. The textually later headers in the headers part of the
message are signed first, if there are multiples.
If an '=' prefix is used, all headers that are present with this name
will be signed.
If a '+' prefix if used, all headers that are present with this name
-will be signed, and one signtature added for a missing header with the
+will be signed, and one signature added for a missing header with the
name will be appended.
.vitem &%$dkim_algo%&
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
Note that RFC 8301 says:
.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.
.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.
${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/<value>
or &%headers_charset%& main configuration option (otherwise),
to the
modified UTF-7 encoding specified by RFC 2060,
-with the following exception: All occurences of <sep>
+with the following exception: All occurrences of <sep>
(which has to be a single character)
are replaced with periods ("."), and all periods and slashes that are not
<sep> and are not in the <specials> string are BASE64 encoded.
before or after the action is associates with. Those which fire before
can be used to affect that action (more on this below).
-The third column in the table above says what section of the configumration
+The third column in the table above says what section of the configuration
should define the event action.
An additional variable, &$event_data$&, is filled with information varying
git://git.exim.org / exim.git / blobdiff