Taint: internal documentation

diff --git a/src/src/store.c b/src/src/store.c
index a06e1c19afd1035a804d005cf0b9ff7142d0b562..fbfd20d1de64d34fb276e183aad8483b91cc872b 100644 (file)
--- 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 a208070547ea8706d49bcf15632d4a6e719f7621..97d71d3a4d157bbec1cb0d6daf5c10f01e409d2b 100644 (file)
--- 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 *