Taint: generate detainted $domain_data & $local_part_data from Rverify callout

[exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index e216a65a9b56a0e1f79c939169ffe6eeb781d806..b6fd9e10f474dba3c366002e043b5bb704318aa3 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -1429,6 +1429,7 @@ check an address given in the SMTP EXPN command (see the &%expn%& option).
 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.
@@ -6787,6 +6788,7 @@ file that is searched could contain lines like this:
 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
@@ -6843,12 +6845,12 @@ lookup to succeed. The lookup type determines how the file is searched.
 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
@@ -8848,6 +8850,7 @@ or a &%domains%& condition in an ACL statement, the value is preserved in the
 &$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)
@@ -8889,6 +8892,7 @@ whether or not the query succeeds. However, when a lookup is used for the
 &%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
@@ -10695,6 +10699,10 @@ executions from Exim, a shell is not used by default. If the command requires
 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
@@ -11936,6 +11944,7 @@ ${if inlisti{Needle}{fOo:NeeDLE:bAr}}
 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}}
@@ -12145,6 +12154,7 @@ caselessly.
 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}}
@@ -13279,6 +13289,11 @@ This is not an expansion variable, but is mentioned here because the string
 (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$&"
@@ -19024,6 +19039,7 @@ than trying to read &_/etc/passwd_& directly. This means that other methods of
 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
@@ -23296,6 +23312,7 @@ The value is used for checking instead of a home directory;
 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.
 
@@ -24731,6 +24748,11 @@ This list is a compromise for maximum compatibility with other MTAs. Note that
 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
@@ -33598,6 +33620,15 @@ output before performing a callout in an ACL, to avoid unexpected timeouts in
 clients when the SMTP PIPELINING extension is in use. The flushing can be
 disabled by using a &%control%& modifier to set &%no_callout_flush%&.
 
+.new
+.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using receipient verify"
+A recipient callout which gets a 2&'xx'& code
+will assign untainted values to the
+&$domain_data$& and &$local_part_data$& variables,
+corresponding to the domain and local parts of the recipient address.
+.wen
+