Docs: warn against using $local_part directly in delivery

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 560b720661244754b0e81035bb8594ff79eb6105..8b15227950c8f9c710b7ddfdfa629d4b15b99064 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
-  file = /var/mail/$local_part
+  file = /var/mail/$home
   delivery_date_add
   envelope_to_add
   return_path_add
@@ -12385,6 +12385,18 @@ 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.
 
+.new
+&*Warning*&: the content of this variable is 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 &$home$&
+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.
+.wen
+
 .vindex "&$local_part_prefix$&"
 .vindex "&$local_part_suffix$&"
 .cindex affix variables
@@ -20528,6 +20540,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.
 
+.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"
@@ -27544,16 +27565,28 @@ This specifies the SASL realm that the server claims to be in.
 Some mechanisms will use this data.
 
 
-.option server_scram_iter gsasl string&!! unset
+.option server_scram_iter gsasl string&!! 4096
 This option provides data for the SCRAM family of mechanisms.
-&$auth1$& is not available at evaluation time.
-(This may change, as we receive feedback on use)
+.new
+The &$auth1$&, &$auth2$& and &$auth3$& variables are available for expansion.
+
+The result of expansion should be a decimal number,
+and represents both a lower-bound on the security, and
+a compute cost factor imposed on the client
+(if it does not cache results, or the server changes
+either the iteration count or the salt).
+A minimum value of 4096 is required by the standards
+for all current CRAM mechanism variants.
+.wen
 
 
 .option server_scram_salt gsasl string&!! unset
 This option provides data for the SCRAM family of mechanisms.
-&$auth1$& is not available at evaluation time.
-(This may change, as we receive feedback on use)
+.new
+The &$auth1$&, &$auth2$& and &$auth3$& variables are available for expansion.
+If unset or empty after expansion the library will provides a value for the
+protocol conversation.
+.wen
 
 
 .option server_service gsasl string &`smtp`&