From: Jeremy Harris <jgh146exb@wizmail.org>
Date: Tue, 10 Dec 2019 13:11:27 +0000 (+0000)
Subject: Taint: internal documentation
X-Git-Url: https://git.exim.org/users/jgh/exim.git/commitdiff_plain/adc4ecf9c7fc0a78c471c6794f5b2e62a396c301

Taint: internal documentation
---

diff --git a/src/src/store.c b/src/src/store.c
index a06e1c19a..fbfd20d1d 100644
--- a/src/src/store.c
+++ b/src/src/store.c
@@ -41,8 +41,26 @@ The following different types of store are recognized:
   and tainted.  The latter is used for values derived from untrusted input, and
   the string-expansion mechanism refuses to operate on such values (obviously,
   it can expand an untainted value to return a tainted result).  The classes
-  are implemented by duplicating the three pool types. Pool resets are requested
+  are implemented by duplicating the three pool types.  Pool resets are requested
   against the nontainted sibling and apply to both siblings.
+
+  Only memory blocks requested for tainted use are regarded as tainted; anything
+  else (including stack auto variables) is untainted.  Care is needed when coding
+  to not copy untrusted data into untainted memory, as downstream taint-checks
+  would be avoided.
+
+  Intermediate layers (eg. the string functions) can test for taint, and use this
+  for ensuringn that results have proper state.  For example the
+  string_vformat_trc() routing supporting the string_sprintf() interface will
+  recopy a string being built into a tainted allocation if it meets a %s for a
+  tainted argument.
+
+  Internally we currently use malloc for nontainted pools, and mmap for tainted
+  pools.  The disparity is for speed of testing the taintedness of pointers;
+  because Linux appears to use distinct non-overlapping address allocations for
+  mmap vs. everything else, which means only two pointer-compares suffice for the
+  test.  Other OS' cannot use that optimisation, and a more lengthy test against
+  the limits of tainted-pool allcations has to be done.
 */
 
 
@@ -209,7 +227,8 @@ block, getting a new one if necessary. The address is saved in
 store_last_was_get.
 
 Arguments:
-  size        amount wanted
+  size        amount wanted, bytes
+  tainted     class: set to true for untrusted data (eg. from smtp input)
   func        function from which called
   linenumber  line number in source file
 
diff --git a/src/src/string.c b/src/src/string.c
index a20807054..97d71d3a4 100644
--- a/src/src/string.c
+++ b/src/src/string.c
@@ -1252,8 +1252,8 @@ If the "extend" flag is false, the string passed in may not be NULL,
 will not be grown, and is usable in the original place after return.
 The return value can be NULL to signify overflow.
 
-Returns the possibly-new (if copy for growth was needed) string,
-not nul-terminated.
+Returns the possibly-new (if copy for growth or taint-handling was needed)
+string, not nul-terminated.
 */
 
 gstring *