X-Git-Url: https://git.exim.org/users/jgh/exim.git/blobdiff_plain/14a806d6c13afdfb2f44dce64e50bffa6cb6869c..d22c942c4ba0a4e5ace2dfb856a43a19f8ed8b6d:/doc/doc-docbook/spec.xfpt?ds=inline diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index eea304d64..d566d9428 100644 --- 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" +.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 @@ -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 "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 @@ -6362,7 +6364,7 @@ All other options are defaulted. .code local_delivery: driver = appendfile - file = /var/mail/$local_part + file = /var/mail/$local_part_verified 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 -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 @@ -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. +.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 @@ -9709,7 +9734,7 @@ letters appear. For example: "&*$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" @@ -9815,6 +9840,12 @@ newline at the very end. For the &%header%& and &%bheader%& expansion, for those headers that contain lists of addresses, a comma is also inserted at the junctions between headers. This does not happen for the &%rheader%& expansion. +.new +.cindex "tainted data" +When the headers are from an incoming message, +the result of expanding any of these variables is tainted. +.wen + .vitem &*${hmac{*&<&'hashname'&>&*}{*&<&'secret'&>&*}{*&<&'string'&>&*}}*& .cindex "expansion" "hmac hashing" @@ -12192,6 +12223,13 @@ When the &%smtp_etrn_command%& option is being expanded, &$domain$& contains the complete argument of the ETRN command (see section &<>&). .endlist +.new +.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 + .vitem &$domain_data$& .vindex "&$domain_data$&" @@ -12385,6 +12423,25 @@ 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 +.cindex "tainted data" +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. +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 +&$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. +If needed, use a router &%address_data%& or &%set%& option for +the retrieved data. +.wen + .vindex "&$local_part_prefix$&" .vindex "&$local_part_suffix$&" .cindex affix variables @@ -12451,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$&. +.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 @@ -16703,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" +.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 @@ -20528,6 +20594,19 @@ 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 +.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. +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" @@ -20753,6 +20832,11 @@ It must be given as .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" @@ -22312,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 +.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)&" @@ -23749,6 +23841,12 @@ directories are also controllable. See chapter &<>& for details of the local delivery environment and chapter &<>& 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 @@ -27435,6 +27533,9 @@ auth_mechanisms = plain login ntlm .cindex "authentication" "DIGEST-MD5" .cindex "authentication" "CRAM-MD5" .cindex "authentication" "SCRAM-SHA-1" +.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 @@ -27442,17 +27543,22 @@ 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. - .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. +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. +See &%server_channelbinding%& below. .option client_password gsasl string&!! unset This option is exapanded before use, and should result in @@ -27463,6 +27569,19 @@ This option is exapanded before use, and should result in 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. @@ -27481,6 +27600,7 @@ 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 @@ -27535,16 +27655,60 @@ 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 +when this option is expanded. + +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 SCRAM 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 +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 + + +.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`& @@ -30556,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%&. -.vitem &*control&~=&~queue_only*& +.new +.vitem &*control&~=&~queue/*&<&'options'&>* &&& + &*control&~=&~queue_only*& +.oindex "&%queue%&" .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 -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" @@ -36698,6 +36878,7 @@ delivered immediately. .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, @@ -37355,7 +37536,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 @@ -37453,7 +37634,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 @@ -40571,9 +40752,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.