X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/cf8b2c5789b6b6cfc2bb0dd84753ed7ec746d444..9438970c97adda0afb9b825b5beff5276a1d613d:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 8b1522795..68ad1691e 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/$home + 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$&" @@ -12386,15 +12424,22 @@ 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. +.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 &$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. +If needed, use a router &%address_data%& or &%set%& option for +the retrieved data. .wen .vindex "&$local_part_prefix$&" @@ -12463,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 @@ -16715,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 @@ -20541,6 +20595,10 @@ 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. @@ -20774,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" @@ -22333,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)&" @@ -23770,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 @@ -27492,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. @@ -27568,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 -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 @@ -27576,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 -for all current CRAM mechanism variants. +for all current SCRAM mechanism variants. .wen - .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 +.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. @@ -30598,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%&. +.new +.vitem &*control&~=&~queue/*&<&'options'&>* .vitem &*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" @@ -36740,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,