Docs: fix validation

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 241540cfd69246e66e10e269ff9753de6fb787f1..d566d942838bf3f10a8333142f0a1267c1050651 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -4185,6 +4185,7 @@ forces queueing.
 .vitem &%-odqs%&
 .oindex "&%-odqs%&"
 .cindex "SMTP" "delaying delivery"
 .vitem &%-odqs%&
 .oindex "&%-odqs%&"
 .cindex "SMTP" "delaying delivery"

+.cindex "first pass routing"

 This option is a hybrid between &%-odb%&/&%-odi%& and &%-odq%&.
 However, like &%-odb%& and &%-odi%&, this option has no effect if
 &%queue_only_override%& is false and one of the queueing options in the
 This option is a hybrid between &%-odb%&/&%-odi%& and &%-odq%&.
 However, like &%-odb%& and &%-odi%&, this option has no effect if
 &%queue_only_override%& is false and one of the queueing options in the


@@ -4503,6 +4504,7 @@ appear in the correct order. Each flag is described in a separate item below.
 .cindex "queue" "double scanning"
 .cindex "queue" "routing"
 .cindex "routing" "whole queue before delivery"
 .cindex "queue" "double scanning"
 .cindex "queue" "routing"
 .cindex "routing" "whole queue before delivery"

+.cindex "first pass routing"

 An option starting with &%-qq%& requests a two-stage queue run. In the first
 stage, the queue is scanned as if the &%queue_smtp_domains%& option matched
 every domain. Addresses are routed, local deliveries happen, but no remote
 An option starting with &%-qq%& requests a two-stage queue run. In the first
 stage, the queue is scanned as if the &%queue_smtp_domains%& option matched
 every domain. Addresses are routed, local deliveries happen, but no remote


@@ -6362,7 +6364,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 +6372,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


@@ -8290,6 +8302,19 @@ domainlist  dom2 = !a.b : *.b
 where &'x.y'& does not match. It's best to avoid negation altogether in
 referenced lists if you can.
 
 where &'x.y'& does not match. It's best to avoid negation altogether in
 referenced lists if you can.
 

+.new
+.cindex "hiding named list values"
+.cindex "named lists" "hiding value of"
+Some named list definitions may contain sensitive data, for example, passwords for
+accessing databases. To stop non-admin users from using the &%-bP%& command
+line option to read these values, you can precede the definition with the
+word &"hide"&. For example:
+.code
+hide domainlist filter_for_domains = ldap;PASS=secret ldap::/// ...
+.endd
+.wen
+
+

 Named lists may have a performance advantage. When Exim is routing an
 address or checking an incoming message, it caches the result of tests on named
 lists. So, if you have a setting such as
 Named lists may have a performance advantage. When Exim is routing an
 address or checking an incoming message, it caches the result of tests on named
 lists. So, if you have a setting such as


@@ -9709,7 +9734,7 @@ letters appear. For example:
        "&*$bheader_*&<&'header&~name'&>&*:*&&~or&~&&&
         &*$bh_*&<&'header&~name'&>&*:*&" &&&
        "&*$lheader_*&<&'header&~name'&>&*:*&&~or&~&&&
        "&*$bheader_*&<&'header&~name'&>&*:*&&~or&~&&&
         &*$bh_*&<&'header&~name'&>&*:*&" &&&
        "&*$lheader_*&<&'header&~name'&>&*:*&&~or&~&&&

-        &*$lh_*&<&'header&~name'&>&*:*&"
+        &*$lh_*&<&'header&~name'&>&*:*&" &&&

        "&*$rheader_*&<&'header&~name'&>&*:*&&~or&~&&&
         &*$rh_*&<&'header&~name'&>&*:*&"
 .cindex "expansion" "header insertion"
        "&*$rheader_*&<&'header&~name'&>&*:*&&~or&~&&&
         &*$rh_*&<&'header&~name'&>&*:*&"
 .cindex "expansion" "header insertion"


@@ -12202,6 +12227,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 +12428,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 +12508,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


@@ -16731,6 +16768,7 @@ an expansion depending on the &$queue_name$& variable.
 .option queue_smtp_domains main "domain list&!!" unset
 .cindex "queueing incoming messages"
 .cindex "message" "queueing remote deliveries"
 .option queue_smtp_domains main "domain list&!!" unset
 .cindex "queueing incoming messages"
 .cindex "message" "queueing remote deliveries"

+.cindex "first pass routing"

 When this option is set, a delivery process is started whenever a message is
 received, routing is performed, and local deliveries take place.
 However, if any SMTP deliveries are required for domains that match
 When this option is set, a delivery process is started whenever a message is
 received, routing is performed, and local deliveries take place.
 However, if any SMTP deliveries are required for domains that match


@@ -20557,6 +20595,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 +20832,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 +22396,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 +23841,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


@@ -27508,6 +27569,19 @@ This option is exapanded before use, and should result in
 the account name to be used.
 .wen
 
 the account name to be used.
 .wen
 

+.new
+.option client_spassword gsasl string&!! unset
+If a SCRAM mechanism is being used and this option is set
+it is used in preference to &%client_password%&.
+The value after expansion should be
+a 40 (for SHA-1) or 64 (for SHA-256) character string
+with the PBKDF2-prepared password, hex-encoded.
+Note that this value will depend on the salt and iteration-count
+supplied by the server.
+.wen
+
+
+

 .option server_channelbinding gsasl boolean false
 Do not set this true and rely on the properties
 without consulting a cryptographic engineer.
 .option server_channelbinding gsasl boolean false
 Do not set this true and rely on the properties
 without consulting a cryptographic engineer.


@@ -27584,7 +27658,8 @@ Some mechanisms will use this data.
 .option server_scram_iter gsasl string&!! 4096
 This option provides data for the SCRAM family of mechanisms.
 .new
 .option server_scram_iter gsasl string&!! 4096
 This option provides data for the SCRAM family of mechanisms.
 .new

-The &$auth1$&, &$auth2$& and &$auth3$& variables are available for expansion.
+The &$auth1$&, &$auth2$& and &$auth3$& variables are available
+when this option is expanded.

 
 The result of expansion should be a decimal number,
 and represents both a lower-bound on the security, and
 
 The result of expansion should be a decimal number,
 and represents both a lower-bound on the security, and


@@ -27592,19 +27667,50 @@ 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
 (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.
+for all current SCRAM mechanism variants.

 .wen
 
 .wen
 

-

 .option server_scram_salt gsasl string&!! unset
 This option provides data for the SCRAM family of mechanisms.
 .new
 .option server_scram_salt gsasl string&!! unset
 This option provides data for the SCRAM family of mechanisms.
 .new

-The &$auth1$&, &$auth2$& and &$auth3$& variables are available for expansion.
+The &$auth1$&, &$auth2$& and &$auth3$& variables are available
+when this option is expanded.
+The value should be a base64-encoded string,
+of random data typically 4-to-16 bytes long.

 If unset or empty after expansion the library will provides a value for the
 protocol conversation.
 .wen
 
 
 If unset or empty after expansion the library will provides a value for the
 protocol conversation.
 .wen
 
 

+.new
+.option server_key gsasl string&!! unset
+.option server_skey gsasl string&!! unset
+These options can be used for the SCRAM family of mechanisms
+to provide stored information related to a password,
+the storage of which is preferable to plaintext.
+
+&%server_key%& is the value defined in the SCRAM standards as ServerKey;
+&%server_skey%& is StoredKey.
+
+They are only available for version 1.9.0 (or later) of the gsasl library.
+When this is so, the macros
+_OPT_AUTHENTICATOR_GSASL_SERVER_KEY
+and _HAVE_AUTH_GSASL_SCRAM_S_KEY
+will be defined.
+
+The &$authN$& variables are available when these options are expanded.
+
+If set, the results of expansion should for each
+should be a 28 (for SHA-1) or 44 (for SHA-256) character string
+of base64-coded data, and will be used in preference to the
+&%server_password%& option.
+If unset or not of the right length, &%server_password%& will be used.
+
+The libgsasl library release includes a utility &'gsasl'& which can be used
+to generate these values.
+.wen
+
+

 .option server_service gsasl string &`smtp`&
 This is the SASL service that the server claims to implement.
 Some mechanisms will use this data.
 .option server_service gsasl string &`smtp`&
 This is the SASL service that the server claims to implement.
 Some mechanisms will use this data.


@@ -30614,16 +30720,32 @@ response to an EHLO command. Therefore, it should normally appear in an ACL
 controlled by &%acl_smtp_connect%& or &%acl_smtp_helo%&. See also
 &%pipelining_advertise_hosts%&.
 
 controlled by &%acl_smtp_connect%& or &%acl_smtp_helo%&. See also
 &%pipelining_advertise_hosts%&.
 

-.vitem &*control&~=&~queue_only*&
+.new
+.vitem &*control&~=&~queue/*&<&'options'&>* &&&
+       &*control&~=&~queue_only*&
+.oindex "&%queue%&"

 .oindex "&%queue_only%&"
 .cindex "queueing incoming messages"
 .oindex "&%queue_only%&"
 .cindex "queueing incoming messages"

+.cindex queueing "forcing in ACL"
+.cindex "first pass routing"

 This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs, in
 other words, only when a message is being received. If the message is accepted,
 it is placed on Exim's queue and left there for delivery by a subsequent queue
 This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs, in
 other words, only when a message is being received. If the message is accepted,
 it is placed on Exim's queue and left there for delivery by a subsequent queue

-runner. No immediate delivery process is started. In other words, it has the
-effect as the &%queue_only%& global option. However, the control applies only
-to the current message, not to any subsequent ones that may be received in the
-same SMTP connection.
+runner.
+If used with no options set,
+no immediate delivery process is started. In other words, it has the
+effect as the &%queue_only%& global option or &'-odq'& command-line option.
+
+If the &'first_pass_route'& option is given then
+the behaviour is like the command-line &'-oqds'& option;
+a delivery process is started which stops short of making
+any SMTP delivery.  The benefit is that the hints database will be updated for
+the message being waiting for a specific host, and a later queue run will be
+able to send all such messages on a single connection.
+
+The control only applies to the current message, not to any subsequent ones that
+ may be received in the same SMTP connection.
+.wen

 
 .vitem &*control&~=&~submission/*&<&'options'&>
 .cindex "message" "submission"
 
 .vitem &*control&~=&~submission/*&<&'options'&>
 .cindex "message" "submission"


@@ -36756,6 +36878,7 @@ delivered immediately.
 .cindex "SMTP" "passed connection"
 .cindex "SMTP" "multiple deliveries"
 .cindex "multiple SMTP deliveries"
 .cindex "SMTP" "passed connection"
 .cindex "SMTP" "multiple deliveries"
 .cindex "multiple SMTP deliveries"

+.cindex "first pass routing"

 Mail waiting to be sent from an intermittently connected host will probably
 not have been routed, because without a connection DNS lookups are not
 possible. This means that if a normal queue run is done at connection time,
 Mail waiting to be sent from an intermittently connected host will probably
 not have been routed, because without a connection DNS lookups are not
 possible. This means that if a normal queue run is done at connection time,