taint: allow appenfile create_file option to specify a de-tainting safe path

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 37bfeb3f39aa91eda25d53a8b1227c8372a1cb12..4a22b2e5f8037e60190331ec40260018e3e10002 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -22867,6 +22867,11 @@ If &%file%& or &%directory%& is set for a delivery from a redirection, it is
 used to determine the file or directory name for the delivery. Normally, the
 contents of &$address_file$& are used in some way in the string expansion.
 .endlist
+If the &%create_file%& option is set to a path which
+matches (see the option definition below for details)
+a file or directory name
+for the delivery, that name becomes de-tainted.
+
 .cindex "tainted data" "in filenames"
 .cindex appendfile "tainted data"
 Tainted data may not be used for a file or directory name.
@@ -23014,14 +23019,30 @@ directories defined by the &%directory%& option. In the case of maildir
 delivery, it applies to the top level directory, not the maildir directories
 beneath.
 
+.new
 The option must be set to one of the words &"anywhere"&, &"inhome"&, or
-&"belowhome"&. In the second and third cases, a home directory must have been
+&"belowhome"&, or to an absolute path.
+.wen
+
+In the second and third cases, a home directory must have been
 set for the transport. This option is not useful when an explicit filename is
 given for normal mailbox deliveries. It is intended for the case when filenames
 are generated from users' &_.forward_& files. These are usually handled
 by an &(appendfile)& transport called &%address_file%&. See also
 &%file_must_exist%&.
 
+.new
+In the fourth case,
+the value given for this option must be an absolute path for an
+existing directory.
+The expansion of either the &%directory%& or &%file%&
+option is checked for being a strict (possibly potential) descendant,
+in the filesystem, of the value given.
+.cindex "tainted data" "de-tainting"
+If the check passes then the path checked becomes de-tainted.
+If the check fails then the transport returns failure.
+.wen
+
 
 .option directory appendfile string&!! unset
 This option is mutually exclusive with the &%file%& option, but one of &%file%&
@@ -23034,6 +23055,11 @@ appended to a single mailbox file. A number of different formats are provided
 (see &%maildir_format%& and &%mailstore_format%&), and see section
 &<<SECTopdir>>& for further details of this form of delivery.
 
+.new
+The result of expansion must not be tainted, unless the &%create_file%& option
+specifies a path.
+.wen
+
 
 .option directory_file appendfile string&!! "see below"
 .cindex "base62"
@@ -23066,6 +23092,11 @@ specifies a single file, to which the message is appended. One or more of
 &%use_fcntl_lock%&, &%use_flock_lock%&, or &%use_lockfile%& must be set with
 &%file%&.
 
+.new
+The result of expansion must not be tainted, unless the &%create_file%& option
+specifies a path.
+.wen
+
 .cindex "NFS" "lock file"
 .cindex "locking files"
 .cindex "lock files"