Docs: warn against using $local_part directly in delivery
[users/jgh/exim.git] / doc / doc-docbook / spec.xfpt
index 42a393558ef404c7b562de64a960be99a36f53f2..8b15227950c8f9c710b7ddfdfa629d4b15b99064 100644 (file)
@@ -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"
@@ -27435,19 +27456,45 @@ auth_mechanisms = plain login ntlm
 .cindex "authentication" "DIGEST-MD5"
 .cindex "authentication" "CRAM-MD5"
 .cindex "authentication" "SCRAM-SHA-1"
-The &(gsasl)& authenticator provides server integration for the GNU SASL
+.cindex "authentication" "SCRAM-SHA-1-PLUS"
+.cindex "authentication" "SCRAM-SHA-256"
+.cindex "authentication" "SCRAM-SHA-256-PLUS"
+The &(gsasl)& authenticator provides integration for the GNU SASL
 library and the mechanisms it provides.  This is new as of the 4.80 release
 and there are a few areas where the library does not let Exim smoothly
 scale to handle future authentication mechanisms, so no guarantee can be
 made that any particular new authentication mechanism will be supported
 without code changes in Exim.
 
-Exim's &(gsasl)& authenticator does not have client-side support at this
-time; only the server-side support is implemented.  Patches welcome.
+.new
+The library is expected to add support in an upcoming
+realease for the SCRAM-SHA-256 method.
+The macro _HAVE_AUTH_GSASL_SCRAM_SHA_256 will be defined
+when this happens.
+
 
+.option client_authz gsasl string&!! unset
+This option can be used to supply an &'authorization id'&
+which is different to the &'authentication_id'& provided
+by &%client_username%& option.
+If unset or (after expansion) empty it is not used,
+which is the common case.
+
+.option client_channelbinding gsasl boolean false
+See &%server_channelbinding%& below.
+
+.option client_password gsasl string&!! unset
+This option is exapanded before use, and should result in
+the password to be used, in clear.
+
+.option client_username gsasl string&!! unset
+This option is exapanded before use, and should result in
+the account name to be used.
+.wen
 
 .option server_channelbinding gsasl boolean false
-Do not set this true without consulting a cryptographic engineer.
+Do not set this true and rely on the properties
+without consulting a cryptographic engineer.
 
 Some authentication mechanisms are able to use external context at both ends
 of the session to bind the authentication to that context, and fail the
@@ -27463,13 +27510,14 @@ server to see different identifiers and authentication will fail.
 This is
 only usable by mechanisms which support "channel binding"; at time of
 writing, that's the SCRAM family.
+When using this feature the "-PLUS" variants of the method names need to be used.
 .wen
 
 This defaults off to ensure smooth upgrade across Exim releases, in case
 this option causes some clients to start failing.  Some future release
 of Exim might have switched the default to be true.
 
-However, Channel Binding in TLS has proven to be broken in current versions.
+However, Channel Binding in TLS has proven to be vulnerable in current versions.
 Do not plan to rely upon this feature for security, ever, without consulting
 with a subject matter expert (a cryptographic engineer).
 
@@ -27517,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`&
@@ -37337,7 +37397,7 @@ the following table:
 &`DKIM`&        domain verified in incoming message
 &`DN  `&        distinguished name from peer certificate
 &`DS  `&        DNSSEC secured lookups
-&`DT  `&        on &`=>`& lines: time taken for a delivery
+&`DT  `&        on &`=>`&, &'=='& and &'**'& lines: time taken for, or to attempt, a delivery
 &`F   `&        sender address (on delivery lines)
 &`H   `&        host name and IP address
 &`I   `&        local interface used
@@ -37435,7 +37495,7 @@ selection marked by asterisks:
 &` arguments                  `&  command line arguments
 &`*connection_reject          `&  connection rejections
 &`*delay_delivery             `&  immediate delivery delayed
-&` deliver_time               `&  time taken to perform delivery
+&` deliver_time               `&  time taken to attempt delivery
 &` delivery_size              `&  add &`S=`&&'nnn'& to => lines
 &`*dkim                       `&  DKIM verified domain on <= lines
 &` dkim_verbose               `&  separate full DKIM verification result line, per signature
@@ -40553,9 +40613,8 @@ defines the location of a text file of valid
 top level domains the opendmarc library uses
 during domain parsing. Maintained by Mozilla,
 the most current version can be downloaded
-from a link at &url(https://publicsuffix.org/list/, currently pointing
-at https://publicsuffix.org/list/public_suffix_list.dat)
-See also util/renew-opendmarc-tlds.sh script.
+from a link at &url(https://publicsuffix.org/list/public_suffix_list.dat).
+See also the util/renew-opendmarc-tlds.sh script.
 .new
 The default for the option is unset.
 If not set, DMARC processing is disabled.