From: Phil Pennock <pdp@exim.org>
Date: Sun, 25 Sep 2011 03:13:27 +0000 (-0400)
Subject: Document match_*/inlist changes (before coding starts)
X-Git-Tag: list_safety_merge_proposal~3
X-Git-Url: https://vcs.fsf.org/?p=exim.git;a=commitdiff_plain;h=39257585581294b49385b3d10b08d3c92b670c09;ds=sidebyside

Document match_*/inlist changes (before coding starts)
---

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index d18b09dfe..128329ef2 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -10079,6 +10079,25 @@ string is lexically greater than the second string. For &%gt%& the comparison
 includes the case of letters, whereas for &%gti%& the comparison is
 case-independent.
 
+.new
+.vitem &*inlist&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&&
+       &*inlisti&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
+.cindex "string" "comparison"
+.cindex "list" "iterative conditions"
+Both strings are expanded; the second string is treated as a list of simple
+strings; if the first string is a member of the second, then the condition
+is true.
+
+These are simpler to use versions of the more powerful &*forany*& condition.
+Examples, and the &*forany*& equivalents:
+.code
+${if inlist{needle}{foo:needle:bar}}
+  ${if forany{foo:needle:bar}{eq{$item}{needle}}}
+${if inlisti{Needle}{fOo:NeeDLE:bAr}}
+  ${if forany{fOo:NeeDLE:bAr}{eqi{$item}{Needle}}}
+.endd
+.wen
+
 .vitem &*isip&~{*&<&'string'&>&*}*&  &&&
        &*isip4&~{*&<&'string'&>&*}*& &&&
        &*isip6&~{*&<&'string'&>&*}*&
@@ -10265,6 +10284,11 @@ item can be used, as in all address lists, to cause subsequent items to
 have their local parts matched casefully. Domains are always matched
 caselessly.
 
+.new
+Note that <&'string2'&> is not itself subject to string expansion, unless
+Exim was built with the EXPAND_LISTMATCH_RHS option.
+.wen
+
 &*Note*&: Host lists are &'not'& supported in this way. This is because
 hosts have two identities: a name and an IP address, and it is not clear
 how to specify cleanly how such a test would work. However, IP addresses can be
diff --git a/doc/doc-txt/ChangeLog b/doc/doc-txt/ChangeLog
index b0d6b06af..e2e95c548 100644
--- a/doc/doc-txt/ChangeLog
+++ b/doc/doc-txt/ChangeLog
@@ -112,6 +112,10 @@ PP/08 Handle ${run} returning more data than OS pipe buffer size.
 PP/09 Handle IPv6 addresses with SPF.
       Bugzilla 860.  Patch from Wolfgang Breyha.
 
+PP/10 match_* no longer expand right-hand-side by default.
+      New compile-time build option, EXPAND_LISTMATCH_RHS.
+      New expansion conditions, "inlist", "inlisti".
+
 
 Exim version 4.76
 -----------------
diff --git a/doc/doc-txt/NewStuff b/doc/doc-txt/NewStuff
index bf247e67e..d22d4e582 100644
--- a/doc/doc-txt/NewStuff
+++ b/doc/doc-txt/NewStuff
@@ -18,6 +18,15 @@ Version 4.77
  3. New variable $av_failed, set true if the AV scanner deferred; ie, when
     there is a problem talking to the AV scanner, or the AV scanner running.
 
+ 4. New expansion conditions, "inlist" and "inlisti", which take simple lists
+    and check if the search item is a member of the list.  This does not
+    support named lists, but does subject the list part to string expansion.
+
+ 5. Unless the new EXPAND_LISTMATCH_RHS build option is set when Exim was
+    built, Exim no longer performs string expansion on the second string of
+    the match_* expansion conditions: "match_address", "match_domain",
+    "match_ip" & "match_local_part".  Named lists can still be used.
+
 
 Version 4.76
 ------------
diff --git a/doc/doc-txt/OptionLists.txt b/doc/doc-txt/OptionLists.txt
index 21fd0fa26..6c820fbea 100644
--- a/doc/doc-txt/OptionLists.txt
+++ b/doc/doc-txt/OptionLists.txt
@@ -825,6 +825,7 @@ EXIWHAT_MULTIKILL_CMD        system**
 EXIWHAT_MULTIKILL_ARG        system**
 EXIWHAT_PS_ARG               system**     to list all processes
 EXIWHAT_PS_CMD               system**     path to ps command
+EXPAND_LISTMATCH_RHS         optional*    restore pre-4.77 match_*{}{} behaviour
 EXTRALIBS                    system       additional libraries
 EXTRALIBS_EXIM               system       additional libraries for Exim only
 EXTRALIBS_EXIMON             system       additional libraries for the monitor
diff --git a/src/README.UPDATING b/src/README.UPDATING
index 2f6e57629..20313b2cb 100644
--- a/src/README.UPDATING
+++ b/src/README.UPDATING
@@ -26,6 +26,17 @@ The rest of this document contains information about changes in 4.xx releases
 that might affect a running system.
 
 
+Exim version 4.77
+-----------------
+
+ * The match_<type>{string1}{string2} expansion conditions no longer subject
+   string2 to string expansion, unless Exim was built with the new
+   "EXPAND_LISTMATCH_RHS" option.  Too many people have inadvertently created
+   insecure configurations that way.  If you need the functionality and turn on
+   that build option, please let the developers know, and know why, so we can
+   try to provide a safer mechanism for you.
+
+
 Exim version 4.74
 -----------------