Taint: When a non-wildcarded localpart affix is matched in a router,
[users/heiko/exim.git] / doc / doc-docbook / spec.xfpt
index c54437181b2bc1bfd83c2109fd4bf07f54b88550..ff6a115c54c10a5e42f5968fcfdcc0bff446cc88 100644 (file)
@@ -52,7 +52,7 @@
 .set I   "    "
 
 .macro copyyear
 .set I   "    "
 
 .macro copyyear
-2019
+2020
 .endmacro
 
 . /////////////////////////////////////////////////////////////////////////////
 .endmacro
 
 . /////////////////////////////////////////////////////////////////////////////
@@ -10285,21 +10285,37 @@ ${readsocket{/socket/name}{request string}{3s}}
 .endd
 
 The third argument is a list of options, of which the first element is the timeout
 .endd
 
 The third argument is a list of options, of which the first element is the timeout
-and must be present if the argument is given.
+and must be present if any options are given.
 Further elements are options of form &'name=value'&.
 Further elements are options of form &'name=value'&.
-Two option types is currently recognised: shutdown and tls.
-The first defines whether (the default)
-or not a shutdown is done on the connection after sending the request.
-Example, to not do so (preferred, eg. by some webservers):
+Example:
 .code
 ${readsocket{/socket/name}{request string}{3s:shutdown=no}}
 .endd
 .code
 ${readsocket{/socket/name}{request string}{3s:shutdown=no}}
 .endd
-The second, tls, controls the use of TLS on the connection.  Example:
-.code
-${readsocket{/socket/name}{request string}{3s:tls=yes}}
-.endd
-The default is to not use TLS.
+
+.new
+The following option names are recognised:
+.ilist
+&*cache*&
+Defines if the result data can be cached for use by a later identical
+request in the same process.
+Values are &"yes"& or &"no"& (the default).
+If not, all cached results for this connection specification
+will be invalidated.
+
+.next
+&*shutdown*&
+Defines whether or not a write-shutdown is done on the connection after
+sending the request. Values are &"yes"& (the default) or &"no"&
+(preferred, eg. by some webservers).
+
+.next
+&*tls*&
+Controls the use of TLS on the connection.
+Values are &"yes"& or &"no"& (the default).
 If it is enabled, a shutdown as descripbed above is never done.
 If it is enabled, a shutdown as descripbed above is never done.
+.endlist
+.wen
+
 
 A fourth argument allows you to change any newlines that are in the data
 that is read, in the same way as for &%readfile%& (see above). This example
 
 A fourth argument allows you to change any newlines that are in the data
 that is read, in the same way as for &%readfile%& (see above). This example
@@ -12325,7 +12341,9 @@ 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$&.
+When un untainted version is needed, one should be obtained from
+looking up the value in a local (therefore trusted) database.
+Often &$domain_data$& is usable in this role.
 .wen
 
 
 .wen
 
 
@@ -12536,6 +12554,7 @@ For traditional full user accounts, use &%check_local_users%& and the
 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.
+Often &$local_part_data$& is usable in this role.
 If needed, use a router &%address_data%& or &%set%& option for
 the retrieved data.
 .wen
 If needed, use a router &%address_data%& or &%set%& option for
 the retrieved data.
 .wen
@@ -12550,9 +12569,14 @@ value of &$local_part$& during routing and subsequent delivery. The values of
 any prefix or suffix are in &$local_part_prefix$& and
 &$local_part_suffix$&, respectively.
 .new
 any prefix or suffix are in &$local_part_prefix$& and
 &$local_part_suffix$&, respectively.
 .new
+.cindex "tainted data"
 If the affix specification included a wildcard then the portion of
 the affix matched by the wildcard is in
 If the affix specification included a wildcard then the portion of
 the affix matched by the wildcard is in
-&$local_part_prefix_v$& or &$local_part_suffix_v$& as appropriate.
+&$local_part_prefix_v$& or &$local_part_suffix_v$& as appropriate,
+and both the whole and variable values are tainted.
+
+If the specification did not include a wildcard then
+the affix variable value is not tainted.
 .wen
 
 When a message is being delivered to a file, pipe, or autoreply transport as a
 .wen
 
 When a message is being delivered to a file, pipe, or autoreply transport as a
@@ -14574,6 +14598,7 @@ See also the &'Policy controls'& section above.
 .table2
 .row &%dkim_verify_hashes%&          "DKIM hash methods accepted for signatures"
 .row &%dkim_verify_keytypes%&        "DKIM key types accepted for signatures"
 .table2
 .row &%dkim_verify_hashes%&          "DKIM hash methods accepted for signatures"
 .row &%dkim_verify_keytypes%&        "DKIM key types accepted for signatures"
+.row &%dkim_verify_min_keysizes%&    "DKIM key sizes accepted for signatures"
 .row &%dkim_verify_signers%&         "DKIM domains for which DKIM ACL is run"
 .row &%host_lookup%&                 "host name looked up for these hosts"
 .row &%host_lookup_order%&           "order of DNS and local name lookups"
 .row &%dkim_verify_signers%&         "DKIM domains for which DKIM ACL is run"
 .row &%host_lookup%&                 "host name looked up for these hosts"
 .row &%host_lookup_order%&           "order of DNS and local name lookups"
@@ -14996,12 +15021,18 @@ just the command name, it is not a complete command line. If an argument is
 required, it must come from the &%-oA%& command line option.
 
 
 required, it must come from the &%-oA%& command line option.
 
 
-.option bounce_message_file main string unset
+.option bounce_message_file main string&!! unset
 .cindex "bounce message" "customizing"
 .cindex "customizing" "bounce message"
 This option defines a template file containing paragraphs of text to be used
 for constructing bounce messages.  Details of the file's contents are given in
 .cindex "bounce message" "customizing"
 .cindex "customizing" "bounce message"
 This option defines a template file containing paragraphs of text to be used
 for constructing bounce messages.  Details of the file's contents are given in
-chapter &<<CHAPemsgcust>>&. See also &%warn_message_file%&.
+chapter &<<CHAPemsgcust>>&.
+.new
+.cindex bounce_message_file "tainted data"
+The option is expanded to give the file path, which must be
+absolute and untainted.
+.wen
+See also &%warn_message_file%&.
 
 
 .option bounce_message_text main string unset
 
 
 .option bounce_message_text main string unset
@@ -15348,6 +15379,16 @@ This option gives a list of key types which are acceptable in signatures,
 and an order of processing.
 Signatures with algorithms not in the list will be ignored.
 
 and an order of processing.
 Signatures with algorithms not in the list will be ignored.
 
+
+.new
+.option dkim_verify_min_keysizes main "string list" "rsa=1024 ed25519=250"
+This option gives a list of key sizes which are acceptable in signatures.
+The list is keyed by the algorithm type for the key; the values are in bits.
+Signatures with keys smaller than given by this option will fail verification.
+
+The default enforces the RFC 8301 minimum key size for RSA signatures.
+.wen
+
 .option dkim_verify_minimal main boolean false
 If set to true, verification of signatures will terminate after the
 first success.
 .option dkim_verify_minimal main boolean false
 If set to true, verification of signatures will terminate after the
 first success.
@@ -18337,14 +18378,20 @@ regular expression by a parenthesized subpattern. The default value for
 See &%uucp_from_pattern%& above.
 
 
 See &%uucp_from_pattern%& above.
 
 
-.option warn_message_file main string unset
+.option warn_message_file main string&!! unset
 .cindex "warning of delay" "customizing the message"
 .cindex "customizing" "warning message"
 This option defines a template file containing paragraphs of text to be used
 for constructing the warning message which is sent by Exim when a message has
 been in the queue for a specified amount of time, as specified by
 &%delay_warning%&. Details of the file's contents are given in chapter
 .cindex "warning of delay" "customizing the message"
 .cindex "customizing" "warning message"
 This option defines a template file containing paragraphs of text to be used
 for constructing the warning message which is sent by Exim when a message has
 been in the queue for a specified amount of time, as specified by
 &%delay_warning%&. Details of the file's contents are given in chapter
-&<<CHAPemsgcust>>&. See also &%bounce_message_file%&.
+&<<CHAPemsgcust>>&.
+.new
+.cindex warn_message_file "tainted data"
+The option is expanded to give the file path, which must be
+absolute and untainted.
+.wen
+See also &%bounce_message_file%&.
 
 
 .option write_rejectlog main boolean true
 
 
 .option write_rejectlog main boolean true
@@ -19155,7 +19202,7 @@ but the user is specified symbolically, the gid associated with the uid is
 used. For example:
 .code
 require_files = mail:/some/file
 used. For example:
 .code
 require_files = mail:/some/file
-require_files = $local_part:$home/.procmailrc
+require_files = $local_part_verified:$home/.procmailrc
 .endd
 If a user or group name in a &%require_files%& list does not exist, the
 &%require_files%& condition fails.
 .endd
 If a user or group name in a &%require_files%& list does not exist, the
 &%require_files%& condition fails.
@@ -21786,7 +21833,7 @@ local_users:
 # This transport overrides the group
 group_delivery:
   driver = appendfile
 # This transport overrides the group
 group_delivery:
   driver = appendfile
-  file = /var/spool/mail/$local_part
+  file = /var/spool/mail/$local_part_verified
   group = mail
 .endd
 If &%user%& is set for a transport, its value overrides what is set in the
   group = mail
 .endd
 If &%user%& is set for a transport, its value overrides what is set in the
@@ -22621,7 +22668,7 @@ is used as a result of a &"keep"& action in the filter. This example shows one
 way of handling this requirement:
 .code
 file = ${if eq{$address_file}{inbox} \
 way of handling this requirement:
 .code
 file = ${if eq{$address_file}{inbox} \
-            {/var/mail/$local_part} \
+            {/var/mail/$local_part_verified} \
             {${if eq{${substr_0_1:$address_file}}{/} \
                   {$address_file} \
                   {$home/mail/$address_file} \
             {${if eq{${substr_0_1:$address_file}}{/} \
                   {$address_file} \
                   {$home/mail/$address_file} \
@@ -22802,8 +22849,8 @@ The string value is expanded for each delivery, and must yield an absolute
 path. The most common settings of this option are variations on one of these
 examples:
 .code
 path. The most common settings of this option are variations on one of these
 examples:
 .code
-file = /var/spool/mail/$local_part
-file = /home/$local_part/inbox
+file = /var/spool/mail/$local_part_verified
+file = /home/$local_part_verified/inbox
 file = $home/inbox
 .endd
 .cindex "&""sticky""& bit"
 file = $home/inbox
 .endd
 .cindex "&""sticky""& bit"
@@ -23559,7 +23606,7 @@ and directories in a maildir mailbox, including subdirectories for maildir++
 folders. Consider this example:
 .code
 maildir_format = true
 folders. Consider this example:
 .code
 maildir_format = true
-directory = /var/mail/$local_part\
+directory = /var/mail/$local_part_verified\
            ${if eq{$local_part_suffix}{}{}\
            {/.${substr_1:$local_part_suffix}}}
 maildirfolder_create_regex = /\.[^/]+$
            ${if eq{$local_part_suffix}{}{}\
            {/.${substr_1:$local_part_suffix}}}
 maildirfolder_create_regex = /\.[^/]+$
@@ -35111,7 +35158,7 @@ central_filter:
   check_local_user
   driver = redirect
   domains = +local_domains
   check_local_user
   driver = redirect
   domains = +local_domains
-  file = /central/filters/$local_part
+  file = /central/filters/$local_part_verified
   no_verify
   allow_filter
   allow_freeze
   no_verify
   allow_filter
   allow_freeze
@@ -36626,10 +36673,10 @@ lists in a separate domain from normal mail. For example:
 lists:
   driver = redirect
   domains = lists.example
 lists:
   driver = redirect
   domains = lists.example
-  file = /usr/lists/$local_part
+  file = ${lookup {$local_part} dsearch,ret=full {/usr/lists}}
   forbid_pipe
   forbid_file
   forbid_pipe
   forbid_file
-  errors_to = $local_part-request@lists.example
+  errors_to = ${quote_local_part:$local_part-request}@lists.example
   no_more
 .endd
 This router is skipped for domains other than &'lists.example'&. For addresses
   no_more
 .endd
 This router is skipped for domains other than &'lists.example'&. For addresses
@@ -36717,7 +36764,8 @@ lists_request:
   driver = redirect
   domains = lists.example
   local_part_suffix = -request
   driver = redirect
   domains = lists.example
   local_part_suffix = -request
-  file = /usr/lists/$local_part$local_part_suffix
+  local_parts = ${lookup {$local_part} dsearch,filter=file {/usr/lists}}
+  file = /usr/lists/${local_part_data}-request
   no_more
 
 lists_post:
   no_more
 
 lists_post:
@@ -36725,10 +36773,10 @@ lists_post:
   domains = lists.example
   senders = ${if exists {/usr/lists/$local_part}\
              {lsearch;/usr/lists/$local_part}{*}}
   domains = lists.example
   senders = ${if exists {/usr/lists/$local_part}\
              {lsearch;/usr/lists/$local_part}{*}}
-  file = /usr/lists/$local_part
+  file = ${lookup {$local_part} dsearch,ret=full {/usr/lists}}
   forbid_pipe
   forbid_file
   forbid_pipe
   forbid_file
-  errors_to = $local_part-request@lists.example
+  errors_to = ${quote_local_part:$local_part-request}@lists.example
   no_more
 
 lists_closed:
   no_more
 
 lists_closed:
@@ -36786,7 +36834,7 @@ verp_smtp:
   max_rcpt = 1
   return_path = \
     ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\
   max_rcpt = 1
   return_path = \
     ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\
-      {$1-request+$local_part=$domain@your.dom.example}fail}
+      {${quote_local_part:$1-request+$local_part=$domain}@your.dom.example}fail}
 .endd
 This has the effect of rewriting the return path (envelope sender) on outgoing
 SMTP messages, if the local part of the original return path ends in
 .endd
 This has the effect of rewriting the return path (envelope sender) on outgoing
 SMTP messages, if the local part of the original return path ends in
@@ -36837,7 +36885,7 @@ verp_dnslookup:
   transport = remote_smtp
   errors_to = \
     ${if match {$return_path}{^(.+?)-request@your.dom.example\$}}
   transport = remote_smtp
   errors_to = \
     ${if match {$return_path}{^(.+?)-request@your.dom.example\$}}
-     {$1-request+$local_part=$domain@your.dom.example}fail}
+     {${quote_local_part:$1-request+$local_part=$domain}@your.dom.example}fail}
   no_more
 .endd
 Before you start sending out messages with VERPed return paths, you must also
   no_more
 .endd
 Before you start sending out messages with VERPed return paths, you must also
@@ -36925,7 +36973,7 @@ follows:
 .code
 my_mailboxes:
   driver = appendfile
 .code
 my_mailboxes:
   driver = appendfile
-  file = /var/mail/$domain/$local_part
+  file = /var/mail/$domain/$local_part_data
   user = mail
 .endd
 This uses a directory of mailboxes for each domain. The &%user%& setting is
   user = mail
 .endd
 This uses a directory of mailboxes for each domain. The &%user%& setting is
@@ -40717,6 +40765,10 @@ Notes from the key record (tag n=).
 
 .vitem &%$dkim_key_length%&
 Number of bits in the key.
 
 .vitem &%$dkim_key_length%&
 Number of bits in the key.
+.new
+Valid only once the key is loaded, which is at the time the header signature
+is verified, which is after the body hash is.
+.wen
 
 Note that RFC 8301 says:
 .code
 
 Note that RFC 8301 says:
 .code
@@ -40724,9 +40776,8 @@ Verifiers MUST NOT consider signatures using RSA keys of
 less than 1024 bits as valid signatures.
 .endd
 
 less than 1024 bits as valid signatures.
 .endd
 
-To enforce this you must have a DKIM ACL which checks this variable
-and overwrites the &$dkim_verify_status$& variable as discussed above.
-As EC keys are much smaller, the check should only do this for RSA keys.
+This is enforced by the default setting for the &%dkim_verify_min_keysizes%&
+option.
 
 .endlist
 
 
 .endlist