X-Git-Url: https://git.exim.org/users/jgh/exim.git/blobdiff_plain/fdc7c95ecb7281cc0b60ffb0b518380f3ff252a4..24c7087f56530d2d81a92d9955afef13b4f1462f:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 560b72066..3bea313c1 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -6362,7 +6362,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 +6370,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 +8300,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 +9732,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 +9838,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 +12221,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 +12421,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 +12506,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 @@ -20528,6 +20591,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 +20829,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 +22393,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 +23838,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 @@ -27471,6 +27566,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. @@ -27544,16 +27652,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`&