.set drivernamemax "64"
.macro copyyear
-2021
+2022
.endmacro
. /////////////////////////////////////////////////////////////////////////////
.itable none 0 0 2 $1 left $2 left
.endmacro
+
+. --- A macro for a "tainted" marker, done as a one-element table
+.macro tmark
+.itable none 0 0 1 10pt left
+.row &'Tainted'&
+.endtable
+.endmacro
+. --- A macro for a tainted variable, adding a taint-marker
+. --- and including the .vitem and .vindex
+.macro tvar
+.vitem $1
+.vindex $1
+.tmark
+.endmacro
+
. --- A macro that generates .row, but puts &I; at the start of the first
. --- argument, thus indenting it. Assume a minimum of two arguments, and
. --- allow up to four arguments, which is as many as we'll ever need.
If the &%domains%& option is set, the domain of the address must be in the set
of domains that it defines.
.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using router domains option"
A match verifies the variable &$domain$& (which carries tainted data)
and assigns an untainted value to the &$domain_data$& variable.
Such an untainted value is often needed in the transport.
When the lookup succeeds, the result of the expansion is a list of domains (and
possibly other types of item that are allowed in domain lists).
.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using a lookup expansion""
The result of the expansion is not tainted.
In the second example, the lookup is a single item in a domain list. It causes
The file string may not be tainted.
.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using a single-key lookup"
All single-key lookups support the option &"ret=key"&.
If this is given and the lookup
(either underlying implementation or cached value)
returns data, the result is replaced with a non-tainted
version of the lookup key.
-.cindex "tainted data" "de-tainting"
.next
.cindex "query-style lookup" "definition of"
The &'query-style'& type accepts a generalized database query. No particular
&$domain_data$& variable and can be referred to in other router options or
other statements in the same ACL.
.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using ACL domains condition"
The value will be untainted.
&*Note*&: If the data result of the lookup (as opposed to the key)
&%domains%& option on a router, the value is preserved in the &$domain_data$&
variable and can be referred to in other options.
.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using router domains option"
The value will be untainted.
.next
a shell, you must explicitly code it.
The command name may not be tainted, but the remaining arguments can be.
+&*Note*&: if tainted arguments are used, they are supplied by a
+potential attacker;
+a careful assessment for security vulnerabilities should be done.
+
If the option &'preexpand'& is used,
.wen
the command and its arguments are first expanded as one string. The result is
-.vitem &*${substr{*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&
+.vitem &*${substr{*&<&'start'&>&*}{*&<&'len'&>&*}{*&<&'subject'&>&*}}*&
.cindex "&%substr%& expansion item"
.cindex "substring extraction"
.cindex "expansion" "substring extraction"
The three strings are expanded; the first two must yield numbers. Call them
<&'n'&> and <&'m'&>. If you are using fixed values for these numbers, that is,
-if <&'string1'&> and <&'string2'&> do not change when they are expanded, you
+if <&'start'&> and <&'len'&> do not change when they are expanded, you
can use the simpler operator notation that avoids some of the braces:
.code
-${substr_<n>_<m>:<string>}
+${substr_<n>_<m>:<subject>}
.endd
The second number is optional (in both notations).
If it is absent in the simpler format, the preceding underscore must also be
The variable &$value$& will be set for a successful match and can be
used in the success clause of an &%if%& expansion item using the condition.
.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using an inlist expansion condition"
It will have the same taint status as the list; expansions such as
.code
${if inlist {$h_mycode:} {0 : 1 : 42} {$value}}
The variable &$value$& will be set for a successful match and can be
used in the success clause of an &%if%& expansion item using the condition.
.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using a match_local_part expansion condition"
It will have the same taint status as the list; expansions such as
.code
${if match_local_part {$local_part} {alice : bill : charlotte : dave} {$value}}
This section contains an alphabetical list of all the expansion variables. Some
of them are available only when Exim is compiled with specific options such as
support for TLS or the content scanning extension.
+.new
+.cindex "tainted data"
+Variables marked as &'tainted'& are likely to carry data supplied by
+a potential attacker.
+Variables without such marking may also, depending on how their
+values are created.
+Such variables should not be further expanded,
+used as filenames
+or used as command-line arguments for external commands.
+.wen
.vlist
.vitem "&$0$&, &$1$&, etc"
precedes the expansion of the string. For example, the commands available in
Exim filter files include an &%if%& command with its own regular expression
matching condition.
+.new
+If the subject string was tainted then any captured substring will also be.
+.wen
.vitem "&$acl_arg1$&, &$acl_arg2$&, etc"
Within an acl condition, expansion condition or expansion item
the ACL's as well.
-.vitem &$authenticated_sender$&
+.tvar &$authenticated_sender$&
.cindex "sender" "authenticated"
.cindex "authentication" "sender"
.cindex "AUTH" "on MAIL command"
-.vindex "&$authenticated_sender$&"
When acting as a server, Exim takes note of the AUTH= parameter on an incoming
SMTP MAIL command if it believes the sender is sufficiently trusted, as
described in section &<<SECTauthparamail>>&. Unless the data is the string
looked up, the contents of any associated TXT record, and the value from the
main A record. See section &<<SECID204>>& for more details.
-.vitem &$domain$&
-.vindex "&$domain$&"
+.tvar &$domain$&
When an address is being routed, or delivered on its own, this variable
contains the domain. Uppercase letters in the domain are converted into lower
case for &$domain$&.
This value may be overridden by the &%exim_version%& main config option.
.vitem &$header_$&<&'name'&>
+.tmark
This is not strictly an expansion variable. It is expansion syntax for
inserting the message header line with the given name. Note that the name must
be terminated by colon or white space, because it may contain a wide variety of
deny hosts = net-lsearch;/some/file
message = $host_data
.endd
+
.vitem &$host_lookup_deferred$&
.cindex "host name" "lookup, failure of"
.vindex "&$host_lookup_deferred$&"
is an integer. For example, if the load average is 0.21, the value of the
variable is 210. The value is recomputed every time the variable is referenced.
-.vitem &$local_part$&
-.vindex "&$local_part$&"
+.tvar &$local_part$&
When an address is being routed, or delivered on its own, this
variable contains the local part. When a number of addresses are being
delivered together (for example, multiple RCPT commands in an SMTP
of seconds since the message was received. It does not change during a single
delivery attempt.
-.vitem &$message_body$&
+.tvar &$message_body$&
.cindex "body of message" "expansion variable"
.cindex "message body" "in expansion"
.cindex "binary zero" "in message body"
-.vindex "&$message_body$&"
.oindex "&%message_body_visible%&"
This variable contains the initial portion of a message's body while it is
being delivered, and is intended mainly for use in filter files. The maximum
this can be disabled by setting &%message_body_newlines%& to be true. Binary
zeros are always converted into spaces.
-.vitem &$message_body_end$&
+.tvar &$message_body_end$&
.cindex "body of message" "expansion variable"
.cindex "message body" "in expansion"
-.vindex "&$message_body_end$&"
This variable contains the final portion of a message's
body while it is being delivered. The format and maximum size are as for
&$message_body$&.
line; it is the local id that Exim assigns to the message, for example:
&`1BXTIK-0001yO-VA`&.
-.vitem &$message_headers$&
-.vindex &$message_headers$&
+.tvar &$message_headers$&
This variable contains a concatenation of all the header lines when a message
is being processed, except for lines added by routers or transports. The header
lines are separated by newline characters. Their contents are decoded in the
same way as a header line that is inserted by &%bheader%&.
-.vitem &$message_headers_raw$&
-.vindex &$message_headers_raw$&
+.tvar &$message_headers_raw$&
This variable is like &$message_headers$& except that no processing of the
contents of header lines is done.
These variables are counters that can be incremented by means
of the &%add%& command in filter files.
-.vitem &$original_domain$&
+.tvar &$original_domain$&
.vindex "&$domain$&"
-.vindex "&$original_domain$&"
When a top-level address is being processed for delivery, this contains the
same value as &$domain$&. However, if a &"child"& address (for example,
generated by an alias, forward, or filter file) is being processed, this
filter, it is set up with an artificial &"parent"& address. This has the local
part &'system-filter'& and the default qualify domain.
-.vitem &$original_local_part$&
+.tvar &$original_local_part$&
.vindex "&$local_part$&"
-.vindex "&$original_local_part$&"
When a top-level address is being processed for delivery, this contains the
same value as &$local_part$&, unless a prefix or suffix was removed from the
local part, because &$original_local_part$& always contains the full local
For messages received by SMTP over TCP/IP, this is normally the uid of the Exim
user.
-.vitem &$parent_domain$&
-.vindex "&$parent_domain$&"
+.tvar &$parent_domain$&
This variable is similar to &$original_domain$& (see
above), except that it refers to the immediately preceding parent address.
-.vitem &$parent_local_part$&
-.vindex "&$parent_local_part$&"
+.tvar &$parent_local_part$&
This variable is similar to &$original_local_part$&
(see above), except that it refers to the immediately preceding parent address.
(described under &%transport_filter%& in chapter &<<CHAPtransportgeneric>>&).
It cannot be used in general expansion strings, and provokes an &"unknown
variable"& error if encountered.
+.new
+&*Note*&: This value permits data supplied by a potential attacker to
+be used in the command for a &(pipe)& transport.
+Such configurations should be carefully assessed for security vulnerbilities.
+.wen
.vitem &$primary_hostname$&
.vindex "&$primary_hostname$&"
is available in the DATA ACL, the non-SMTP ACL, and while routing and
delivering.
-.vitem &$received_for$&
-.vindex "&$received_for$&"
+.tvar &$received_for$&
If there is only a single recipient address in an incoming message, this
variable contains that address when the &'Received:'& header line is being
built. The value is copied after recipient rewriting has happened, but before
The main use of this variable is expected to be to distinguish between
rejections of MAIL and rejections of RCPT.
-.vitem &$recipients$&
-.vindex "&$recipients$&"
+.tvar &$recipients$&
This variable contains a list of envelope recipients for a message. A comma and
a space separate the addresses in the replacement text. However, the variable
is not generally available, to prevent exposure of Bcc recipients in
When a &%regex%& or &%mime_regex%& ACL condition succeeds,
these variables contain the
captured substrings identified by the regular expression.
+.new
+If the subject string was tainted then so will any captured substring.
+.wen
-.vitem &$reply_address$&
-.vindex "&$reply_address$&"
+.tvar &$reply_address$&
When a message is being processed, this variable contains the contents of the
&'Reply-To:'& header line if one exists and it is not empty, or otherwise the
contents of the &'From:'& header line. Apart from the removal of leading
happens, &$self_hostname$& is set to the name of the local host that the
original router encountered. In other circumstances its contents are null.
-.vitem &$sender_address$&
-.vindex "&$sender_address$&"
+.tvar &$sender_address$&
When a message is being processed, this variable contains the sender's address
that was received in the message's envelope. The case of letters in the address
is retained, in both the local part and the domain. For bounce messages, the
after the end of the current ACL statement. If you want to preserve it for
longer, you can save it in an ACL variable.
-.vitem &$sender_address_domain$&
-.vindex "&$sender_address_domain$&"
+.tvar &$sender_address_domain$&
The domain portion of &$sender_address$&.
-.vitem &$sender_address_local_part$&
-.vindex "&$sender_address_local_part$&"
+.tvar &$sender_address_local_part$&
The local part portion of &$sender_address$&.
.vitem &$sender_data$&
.cindex "DNS" "DNSSEC"
done using DNS information the resolver library stated was authenticated data.
-.vitem &$sender_helo_name$&
-.vindex "&$sender_helo_name$&"
+.tvar &$sender_helo_name$&
When a message is received from a remote host that has issued a HELO or EHLO
command, the argument of that command is placed in this variable. It is also
set if HELO or EHLO is used when a message is received using SMTP locally via
is known to currently ignore EDNS0, documented in CAVEATS of asr_run(3).
-.vitem &$sender_host_name$&
-.vindex "&$sender_host_name$&"
+.tvar &$sender_host_name$&
When a message is received from a remote host, this variable contains the
host's name as obtained by looking up its IP address. For messages received by
other means, this variable is empty.
&$smtp_active_hostname$& is saved with any message that is received, so its
value can be consulted during routing and delivery.
-.vitem &$smtp_command$&
-.vindex "&$smtp_command$&"
+.tvar &$smtp_command$&
During the processing of an incoming SMTP command, this variable contains the
entire command. This makes it possible to distinguish between HELO and EHLO in
the HELO ACL, and also to distinguish between commands such as these:
rewriting, whereas the values in &$local_part$& and &$domain$& are taken from
the address after SMTP-time rewriting.
-.vitem &$smtp_command_argument$&
+.tvar &$smtp_command_argument$&
.cindex "SMTP" "command, argument for"
-.vindex "&$smtp_command_argument$&"
While an ACL is running to check an SMTP command, this variable contains the
argument, that is, the text that follows the command name, with leading white
space removed. Following the introduction of &$smtp_command$&, this variable is
Observability for TLS session resumption. See &<<SECTresumption>>& for details.
-.vitem &$tls_in_sni$&
-.vindex "&$tls_in_sni$&"
+.tvar &$tls_in_sni$&
.vindex "&$tls_sni$&"
.cindex "TLS" "Server Name Indication"
.cindex "TLS" SNI
holding password data (such as NIS) are supported. If the local part is a local
user,
.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using router check_local_user option"
&$local_part_data$& is set to an untainted version of the local part and
&$home$& is set from the password data. The latter can be tested in other
preconditions that are evaluated after this one (the order of evaluation is
The expansion variables &$host$& and &$host_address$& are available when the
transport is a remote one. They contain the name and IP address of the host to
which the message is being sent. For example:
+. used to have $sender_address in this cmdline, but it's tainted
.code
transport_filter = /some/directory/transport-filter.pl \
- $host $host_address $sender_address $pipe_addresses
+ $host $host_address $pipe_addresses
.endd
Two problems arise if you want to use more complicated expansion items to
checking is done in "belowhome" mode.
.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using appendfile create_file option"
If "belowhome" checking is used, the file or directory path
becomes de-tainted.
the &%environment%& option can be used to add additional variables to this
environment. The environment for the &(pipe)& transport is not subject
to the &%add_environment%& and &%keep_environment%& main config options.
+.new
+&*Note*&: Using enviroment variables loses track of tainted data.
+Writers of &(pipe)& transport commands should be wary of data supplied
+by potential attackers.
+.wen
.display
&`DOMAIN `& the domain of the address
&`HOME `& the home directory, if set
Exim, and each argument is separately expanded, as described in section
&<<SECThowcommandrun>>& above.
+.new
+.cindex "tainted data"
+No part of the resulting command may be tainted.
+.wen
+
.option environment pipe string&!! unset
.cindex "&(pipe)& transport" "environment for command"
.cindex "Cyrus"
The next example shows a transport and a router for a system where local
deliveries are handled by the Cyrus IMAP server.
+. Used to have R: local_part_suffix = .* + T: -m $local_part_suffix_v
+. but that suffix is tainted so cannot be used in a command arg
+. Really, you'd want to use a lookup for acceptable suffixes to do real detainting
.code
# transport
local_delivery_cyrus:
driver = pipe
command = /usr/cyrus/bin/deliver \
- -m ${substr_1:$local_part_suffix} -- $local_part
+ -- $local_part_data
user = cyrus
group = mail
return_output
local_user_cyrus:
driver = accept
check_local_user
- local_part_suffix = .*
transport = local_delivery_cyrus
.endd
Note the unsetting of &%message_prefix%& and &%message_suffix%&, and the use of
It uses a hints database to record a timestamp against a key.
host. The syntax of the condition is:
.display
-&`seen =`& <&'time interval'&> &`/`& <&'options'&>
+&`seen =`& <&'optional flag'&><&'time interval'&> &`/`& <&'options'&>
.endd
For example,
.endd
in a RCPT ACL will implement simple greylisting.
-The parameters for the condition
-are an interval followed, slash-separated, by a list of options.
+The parameters for the condition are
+a possible minus sign,
+then an interval,
+then, slash-separated, a list of options.
The interval is taken as an offset before the current time,
and used for the test.
If the interval is preceded by a minus sign then the condition returns
If a &%write%& option is given then
a record create or update is always done.
An update is done if the test is for &"since"&.
+If none of those hold and there was no existing record,
+a record is created.
Creates and updates are marked with the current time.