Docs: tweaks

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 8702485703c279d78f21cf6e86aa02bd77dcd4d5..c8099556ecf560c799212482e993c0b132c1bed1 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -52,7 +52,7 @@
 .set I   "    "
 
 .macro copyyear
 .set I   "    "
 
 .macro copyyear

-2019
+2020

 .endmacro
 
 . /////////////////////////////////////////////////////////////////////////////
 .endmacro
 
 . /////////////////////////////////////////////////////////////////////////////


@@ -6381,7 +6381,7 @@ All other options are defaulted.
 .code
 local_delivery:
   driver = appendfile
 .code
 local_delivery:
   driver = appendfile

-  file = /var/mail/$local_part_verified
+  file = /var/mail/$local_part_data

   delivery_date_add
   envelope_to_add
   return_path_add
   delivery_date_add
   envelope_to_add
   return_path_add


@@ -6394,7 +6394,7 @@ 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.
 .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$&,
+Instead we use &$local_part_data$&,

 the result of looking up &$local_part$& in the user database
 (done by using &%check_local_user%& in the the router).
 .wen
 the result of looking up &$local_part$& in the user database
 (done by using &%check_local_user%& in the the router).
 .wen


@@ -6853,7 +6853,7 @@ If a selector is numeric, it must apply to a JSON array; the (zero-based)
 nunbered array element is selected.
 Otherwise it must apply to a JSON object; the named element is selected.
 The final resulting element can be a simple JSON type or a JSON object
 nunbered array element is selected.
 Otherwise it must apply to a JSON object; the named element is selected.
 The final resulting element can be a simple JSON type or a JSON object

-or array; for the latter two a string-representation os the JSON
+or array; for the latter two a string-representation of the JSON

 is returned.
 For elements of type string, the returned value is de-quoted.
 .next
 is returned.
 For elements of type string, the returned value is de-quoted.
 .next


@@ -6977,9 +6977,10 @@ be followed by optional colons.
 lookup types support only literal keys.
 
 .next
 lookup types support only literal keys.
 
 .next

+.cindex "spf lookup type"

 .cindex "lookup" "spf"
 .cindex "lookup" "spf"

-If Exim is built with SPF support, manual lookups can be done
-(as opposed to the standard ACL condition method.
+&(spf)&: If Exim is built with SPF support, manual lookups can be done
+(as opposed to the standard ACL condition method).

 For details see section &<<SECSPF>>&.
 .endlist ilist
 
 For details see section &<<SECSPF>>&.
 .endlist ilist
 


@@ -12341,7 +12342,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
 
 


@@ -12548,29 +12551,15 @@ 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
 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.
+&$local_part_data$& 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.

+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
 

-.vindex "&$local_part_prefix$&"
-.vindex "&$local_part_prefix_v$&"
-.vindex "&$local_part_suffix$&"
-.vindex "&$local_part_suffix_v$&"
-.cindex affix variables
-If a local part prefix or suffix has been recognized, it is not included in the
-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
-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.
-.wen
-

 When a message is being delivered to a file, pipe, or autoreply transport as a
 result of aliasing or forwarding, &$local_part$& is set to the local part of
 the parent address, not to the filename or command (see &$address_file$& and
 When a message is being delivered to a file, pipe, or autoreply transport as a
 result of aliasing or forwarding, &$local_part$& is set to the local part of
 the parent address, not to the filename or command (see &$address_file$& and


@@ -12611,44 +12600,33 @@ router as &$local_part_data$&. In addition, if the driver routes the address
 to a transport, the value is available in that transport. If the transport is
 handling multiple addresses, the value from the first address is used.
 
 to a transport, the value is available in that transport. If the transport is
 handling multiple addresses, the value from the first address is used.
 

+.new
+The &%check_local_user%& router option also sets this variable.
+.wen
+

 &$local_part_data$& is also set when the &%local_parts%& condition in an ACL
 matches a local part by means of a lookup. The data read by the lookup is
 available during the rest of the ACL statement. In all other situations, this
 variable expands to nothing.
 
 &$local_part_data$& is also set when the &%local_parts%& condition in an ACL
 matches a local part by means of a lookup. The data read by the lookup is
 available during the rest of the ACL statement. In all other situations, this
 variable expands to nothing.
 

-.vitem &$local_part_prefix$&
-.vindex "&$local_part_prefix$&"
+.vindex &$local_part_prefix$& &&&
+       &$local_part_prefix_v$& &&&
+       &$local_part_suffix$& &&&
+       &$local_part_suffix_v$&

 .cindex affix variables
 .cindex affix variables

-When an address is being routed or delivered, and a
-specific prefix for the local part was recognized, it is available in this
-variable, having been removed from &$local_part$&.
-
-.new
-.vitem &$local_part_prefix_v$&
-.vindex "&$local_part_prefix_v$&"
-When &$local_part_prefix$& is valid and the prefix match used a wildcard,
-the portion matching the wildcard is available in this variable.
-.wen
-
-.vitem &$local_part_suffix$&
-.vindex "&$local_part_suffix$&"
-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$&.
-
+If a local part prefix or suffix has been recognized, it is not included in the
+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
 .new

-.vitem &$local_part_suffix_v$&
-.vindex "&$local_part_suffix_v$&"
-When &$local_part_suffix$& is valid and the suffix match used a wildcard,
-the portion matching the wildcard is available in this variable.
-.wen
+.cindex "tainted data"
+If the specification did not include a wildcard then
+the affix variable value is not tainted.

 
 

-.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.
+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,
+and both the whole and varying values are tainted.

 .wen
 
 .vitem &$local_scan_data$&
 .wen
 
 .vitem &$local_scan_data$&


@@ -14590,6 +14568,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"


@@ -15012,12 +14991,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


@@ -15364,6 +15349,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.


@@ -18353,14 +18348,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


@@ -19171,7 +19172,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_data:$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.


@@ -21802,7 +21803,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_data

   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


@@ -22637,7 +22638,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_data} \

             {${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} \


@@ -22818,8 +22819,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_data
+file = /home/$local_part_data/inbox

 file = $home/inbox
 .endd
 .cindex "&""sticky""& bit"
 file = $home/inbox
 .endd
 .cindex "&""sticky""& bit"


@@ -23575,7 +23576,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_data\

            ${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 = /\.[^/]+$


@@ -24565,14 +24566,14 @@ configuration for &%procmail%&:
 # transport
 procmail_pipe:
   driver = pipe
 # transport
 procmail_pipe:
   driver = pipe

-  command = /usr/local/bin/procmail -d $local_part
+  command = /usr/local/bin/procmail -d $local_part_data

   return_path_add
   delivery_date_add
   envelope_to_add
   check_string = "From "
   escape_string = ">From "
   umask = 077
   return_path_add
   delivery_date_add
   envelope_to_add
   check_string = "From "
   escape_string = ">From "
   umask = 077

-  user = $local_part
+  user = $local_part_data

   group = mail
 
 # router
   group = mail
 
 # router


@@ -35127,7 +35128,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_data

   no_verify
   allow_filter
   allow_freeze
   no_verify
   allow_filter
   allow_freeze


@@ -36642,10 +36643,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


@@ -36733,7 +36734,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:


@@ -36741,10 +36743,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:


@@ -36802,7 +36804,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


@@ -36853,7 +36855,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


@@ -36941,7 +36943,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


@@ -36996,9 +36998,9 @@ another MTA:
 userforward:
   driver = redirect
   check_local_user
 userforward:
   driver = redirect
   check_local_user

-  file = $home/.forward$local_part_suffix

   local_part_suffix = -*
   local_part_suffix_optional
   local_part_suffix = -*
   local_part_suffix_optional

+  file = ${lookup {.forward$local_part_suffix} dsearch,ret=full {$home} {$value}fail}

   allow_filter
 .endd
 If there is no suffix, &_.forward_& is used; if the suffix is &'-special'&, for
   allow_filter
 .endd
 If there is no suffix, &_.forward_& is used; if the suffix is &'-special'&, for


@@ -40733,6 +40735,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


@@ -40740,9 +40746,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