redirect router: taint-enforce filenames

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 241540cfd69246e66e10e269ff9753de6fb787f1..1d6fa536b45352f7fdb1fe31acc71a2d5a45b3f4 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -6362,7 +6362,7 @@ All other options are defaulted.
 .code
 local_delivery:
   driver = appendfile
 .code
 local_delivery:
   driver = appendfile

-  file = /var/mail/$home
+  file = /var/mail/$local_part_verified

   delivery_date_add
   envelope_to_add
   return_path_add
   delivery_date_add
   envelope_to_add
   return_path_add


@@ -6370,7 +6370,17 @@ local_delivery:
 # mode = 0660
 .endd
 This &(appendfile)& transport is used for local delivery to user mailboxes in
 # mode = 0660
 .endd
 This &(appendfile)& transport is used for local delivery to user mailboxes in

-traditional BSD mailbox format. By default it runs under the uid and gid of the
+traditional BSD mailbox format.
+
+.new
+We prefer to avoid using &$local_part$& directly to define the mailbox filename,
+as it is provided by a potential bad actor.
+Instead we use &$local_part_verified$&,
+the result of looking up &$local_part$& in the user database
+(done by using &%check_local_user%& in the the router).
+.wen
+
+By default &(appendfile)& runs under the uid and gid of the

 local user, which requires the sticky bit to be set on the &_/var/mail_&
 directory. Some systems use the alternative approach of running mail deliveries
 under a particular group instead of using the sticky bit. The commented options
 local user, which requires the sticky bit to be set on the &_/var/mail_&
 directory. Some systems use the alternative approach of running mail deliveries
 under a particular group instead of using the sticky bit. The commented options


@@ -12202,6 +12212,7 @@ the complete argument of the ETRN command (see section &<<SECTETRN>>&).
 .cindex "tainted data"
 If the origin of the data is an incoming message,
 the result of expanding this variable is tainted.
 .cindex "tainted data"
 If the origin of the data is an incoming message,
 the result of expanding this variable is tainted.

+See also &$domain_verified$&.

 .wen
 
 
 .wen
 
 


@@ -12402,15 +12413,18 @@ once.
 If the origin of the data is an incoming message,
 the result of expanding this variable is tainted.
 
 If the origin of the data is an incoming message,
 the result of expanding this variable is tainted.
 

-&*Warning*&: the content of this variable is usually provided by a potential attacker.
+&*Warning*&: the content of this variable is usually provided by a potential
+attacker.

 Consider carefully the implications of using it unvalidated as a name
 for file access.
 This presents issues for users' &_.forward_& and filter files.
 Consider carefully the implications of using it unvalidated as a name
 for file access.
 This presents issues for users' &_.forward_& and filter files.

-For traditional full user accounts, use &%check_local_users%& and the &$home$&
-variable rather than this one.
+For traditional full user accounts, use &%check_local_users%& and the
+&$local_part_verified$& variable rather than this one.

 For virtual users, store a suitable pathname component in the database
 which is used for account name validation, and use that retrieved value
 rather than this variable.
 For virtual users, store a suitable pathname component in the database
 which is used for account name validation, and use that retrieved value
 rather than this variable.

+If needed, use a router &%address_data%& or &%set%& option for
+the retrieved data.

 .wen
 
 .vindex "&$local_part_prefix$&"
 .wen
 
 .vindex "&$local_part_prefix$&"


@@ -12479,6 +12493,14 @@ When an address is being routed or delivered, and a
 specific suffix for the local part was recognized, it is available in this
 variable, having been removed from &$local_part$&.
 
 specific suffix for the local part was recognized, it is available in this
 variable, having been removed from &$local_part$&.
 

+.new
+.vitem &$local_part_verified$&
+.vindex "&$local_part_verified$&"
+If the router generic option &%check_local_part%& has run successfully,
+this variable has the user database version of &$local_part$&.
+Such values are not tainted and hence usable for building file names.
+.wen
+

 .vitem &$local_scan_data$&
 .vindex "&$local_scan_data$&"
 This variable contains the text returned by the &[local_scan()]& function when
 .vitem &$local_scan_data$&
 .vindex "&$local_scan_data$&"
 This variable contains the text returned by the &[local_scan()]& function when


@@ -20557,6 +20579,10 @@ yield empty addresses, for example, items containing only RFC 2822 address
 comments.
 
 .new
 comments.
 
 .new

+.cindex "tainted data" "in filenames"
+.cindex redirect "tainted data"
+Tainted data may not be used for a filename.
+

 &*Warning*&: It is unwise to use &$local_part$& or &$domain$&
 directly for redirection,
 as they are provided by a potential attacker.
 &*Warning*&: It is unwise to use &$local_part$& or &$domain$&
 directly for redirection,
 as they are provided by a potential attacker.


@@ -20790,6 +20816,11 @@ It must be given as
 .code
 list1:   :include:/opt/lists/list1
 .endd
 .code
 list1:   :include:/opt/lists/list1
 .endd

+.new
+.cindex "tainted data" "in filenames"
+.cindex redirect "tainted data"
+Tainted data may not be used for a filename.
+.wen

 .next
 .cindex "address redirection" "to black hole"
 .cindex "delivery" "discard"
 .next
 .cindex "address redirection" "to black hole"
 .cindex "delivery" "discard"


@@ -22349,6 +22380,14 @@ 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
 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

+.new
+.cindex "tainted data" "in filenames"
+.cindex appendfile "tainted data"
+Tainted data may not be used for a file or directory name.
+This means that, for instance, &$local_part$& cannot be used directly
+as a component of a path.  It can however be used as the key for a lookup
+which returns a path (or component).
+.wen

 
 
 .cindex "Sieve filter" "configuring &(appendfile)&"
 
 
 .cindex "Sieve filter" "configuring &(appendfile)&"


@@ -23786,6 +23825,12 @@ directories are also controllable. See chapter &<<CHAPenvironment>>& for
 details of the local delivery environment and chapter &<<CHAPbatching>>&
 for a discussion of local delivery batching.
 
 details of the local delivery environment and chapter &<<CHAPbatching>>&
 for a discussion of local delivery batching.
 

+.new
+.cindex "tainted data" "in pipe command"
+.cindex pipe "tainted data"
+Tainted data may not be used for the command name.
+.wen
+

 
 .section "Concurrent delivery" "SECID140"
 If two messages arrive at almost the same time, and both are routed to a pipe
 
 .section "Concurrent delivery" "SECID140"
 If two messages arrive at almost the same time, and both are routed to a pipe