X-Git-Url: https://git.exim.org/users/jgh/exim.git/blobdiff_plain/9b230009225d688ca002152c8747c96e83951397..7a66b3afa11a70021297c176acf56831692be89a:/doc/doc-docbook/spec.xfpt?ds=sidebyside diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 8be9b7121..1d6fa536b 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 @@ -9815,6 +9825,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 +12208,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 +12408,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 +12493,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 +20578,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 +20816,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 +22380,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 +23825,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 @@ -27363,7 +27445,7 @@ but it is present in many binary distributions. .scindex IIDdcotauth1 "&(dovecot)& authenticator" .scindex IIDdcotauth2 "authenticators" "&(dovecot)&" This authenticator is an interface to the authentication facility of the -Dovecot POP/IMAP server, which can support a number of authentication methods. +Dovecot 2 POP/IMAP server, which can support a number of authentication methods. Note that Dovecot must be configured to use auth-client not auth-userdb. If you are using Dovecot to authenticate POP/IMAP clients, it might be helpful to use the same mechanisms for SMTP authentication. This is a server @@ -27394,6 +27476,29 @@ option is passed in the Dovecot authentication command. If, for a TLS connection, a client certificate has been verified, the &"valid-client-cert"& option is passed. When authentication succeeds, the identity of the user who authenticated is placed in &$auth1$&. + +.new +The Dovecot configuration to match the above wil look +something like: +.code +conf.d/10-master.conf :- + +service auth { +... +#SASL + unix_listener auth-client { + mode = 0660 + user = mail + } +... +} + +conf.d/10-auth.conf :- + +auth_mechanisms = plain login ntlm +.endd +.wen + .ecindex IIDdcotauth1 .ecindex IIDdcotauth2 @@ -27412,19 +27517,45 @@ who authenticated is placed in &$auth1$&. .cindex "authentication" "DIGEST-MD5" .cindex "authentication" "CRAM-MD5" .cindex "authentication" "SCRAM-SHA-1" -The &(gsasl)& authenticator provides server integration for the GNU SASL +.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 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. -Exim's &(gsasl)& authenticator does not have client-side support at this -time; only the server-side support is implemented. Patches welcome. +.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. +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. + +.option client_password gsasl string&!! unset +This option is exapanded before use, and should result in +the password to be used, in clear. + +.option client_username gsasl string&!! unset +This option is exapanded before use, and should result in +the account name to be used. +.wen .option server_channelbinding gsasl boolean false -Do not set this true without consulting a cryptographic engineer. +Do not set this true and rely on the properties +without consulting a cryptographic engineer. Some authentication mechanisms are able to use external context at both ends of the session to bind the authentication to that context, and fail the @@ -27440,13 +27571,14 @@ 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 this option causes some clients to start failing. Some future release of Exim might have switched the default to be true. -However, Channel Binding in TLS has proven to be broken in current versions. +However, Channel Binding in TLS has proven to be vulnerable in current versions. Do not plan to rely upon this feature for security, ever, without consulting with a subject matter expert (a cryptographic engineer). @@ -27494,16 +27626,28 @@ 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 for expansion. + +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 CRAM 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 for expansion. +If unset or empty after expansion the library will provides a value for the +protocol conversation. +.wen .option server_service gsasl string &`smtp`& @@ -37314,7 +37458,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 @@ -37412,7 +37556,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 @@ -40530,10 +40674,12 @@ 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. -The default for the option is /etc/exim/opendmarc.tlds. +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. +.wen The &%dmarc_history_file%& option, if set @@ -41056,14 +41202,17 @@ Events have names which correspond to the point in process at which they fire. The name is placed in the variable &$event_name$& and the event action expansion must check this, as it will be called for every possible event type. +.new The current list of events is: +.wen .display &`dane:fail after transport `& per connection &`msg:complete after main `& per message +&`msg:defer after transport `& per message per delivery try &`msg:delivery after transport `& per recipient &`msg:rcpt:host:defer after transport `& per recipient per host &`msg:rcpt:defer after transport `& per recipient -&`msg:host:defer after transport `& per attempt +&`msg:host:defer after transport `& per host per delivery try; host errors &`msg:fail:delivery after transport `& per recipient &`msg:fail:internal after main `& per recipient &`tcp:connect before transport `& per connection @@ -41089,12 +41238,13 @@ An additional variable, &$event_data$&, is filled with information varying with the event type: .display &`dane:fail `& failure reason +&`msg:defer `& error string &`msg:delivery `& smtp confirmation message &`msg:fail:internal `& failure reason &`msg:fail:delivery `& smtp error message +&`msg:host:defer `& error string &`msg:rcpt:host:defer `& error string &`msg:rcpt:defer `& error string -&`msg:host:defer `& error string &`tls:cert `& verification chain depth &`smtp:connect `& smtp banner &`smtp:ehlo `& smtp ehlo response