X-Git-Url: https://git.exim.org/users/jgh/exim.git/blobdiff_plain/9214d2e4dfd9d4f29e9cb7a0eea8a0758ed1b34a..9438970c97adda0afb9b825b5beff5276a1d613d:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 0e44b119b..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 @@ -8300,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 @@ -9719,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" @@ -16753,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 @@ -20579,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. @@ -20812,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" @@ -27544,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. @@ -27620,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 @@ -27628,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. @@ -30650,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" @@ -36792,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,