$local_part_verified

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 4d02bdc32e8c339ae29431a5fabfd913fa8a34ac..254ed69cc468f5b9f479dc3342741fa835108f98 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/$local_part
+  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


@@ -9815,6 +9825,12 @@ newline at the very end. For the &%header%& and &%bheader%& expansion, for
 those headers that contain lists of addresses, a comma is also inserted at the
 junctions between headers. This does not happen for the &%rheader%& expansion.
 
 those headers that contain lists of addresses, a comma is also inserted at the
 junctions between headers. This does not happen for the &%rheader%& expansion.
 

+.new
+.cindex "tainted data"
+When the headers are from an incoming message,
+the result of expanding any of these variables is tainted.
+.wen
+

 
 .vitem &*${hmac{*&<&'hashname'&>&*}{*&<&'secret'&>&*}{*&<&'string'&>&*}}*&
 .cindex "expansion" "hmac hashing"
 
 .vitem &*${hmac{*&<&'hashname'&>&*}{*&<&'secret'&>&*}{*&<&'string'&>&*}}*&
 .cindex "expansion" "hmac hashing"


@@ -12192,6 +12208,13 @@ When the &%smtp_etrn_command%& option is being expanded, &$domain$& contains
 the complete argument of the ETRN command (see section &<<SECTETRN>>&).
 .endlist
 
 the complete argument of the ETRN command (see section &<<SECTETRN>>&).
 .endlist
 

+.new
+.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
+

 
 .vitem &$domain_data$&
 .vindex "&$domain_data$&"
 
 .vitem &$domain_data$&
 .vindex "&$domain_data$&"


@@ -12385,6 +12408,25 @@ Global address rewriting happens when a message is received, so the value of
 because a message may have many recipients and the system filter is called just
 once.
 
 because a message may have many recipients and the system filter is called just
 once.
 

+.new
+.cindex "tainted data"
+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.
+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
+&$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.
+If needed, use a router &%address_data%& or &%set%& option for
+the retrieved data.
+.wen
+

 .vindex "&$local_part_prefix$&"
 .vindex "&$local_part_suffix$&"
 .cindex affix variables
 .vindex "&$local_part_prefix$&"
 .vindex "&$local_part_suffix$&"
 .cindex affix variables


@@ -12451,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


@@ -20528,6 +20578,15 @@ is not the case when the file contains syntactically valid items that happen to
 yield empty addresses, for example, items containing only RFC 2822 address
 comments.
 
 yield empty addresses, for example, items containing only RFC 2822 address
 comments.
 

+.new
+&*Warning*&: It is unwise to use &$local_part$& or &$domain$&
+directly for redirection,
+as they are provided by a potential attacker.
+In the examples above, &$local_part$& is used for looking up data held locally
+on the system, and not used directly (the second example derives &$home$& via
+the passsword file or database, using &$local_part$&).
+.wen
+

 
 
 .section "Forward files and address verification" "SECID125"
 
 
 .section "Forward files and address verification" "SECID125"