X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/4191cb150300d310ab5fa22ce2cfb02b6f6051b0..9bed290e97e67e12c2f56ef06c8f920c0945e432:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index bfadeb10a..cf658a46d 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -54,7 +54,7 @@ .set drivernamemax "64" .macro copyyear -2021 +2022 .endmacro . ///////////////////////////////////////////////////////////////////////////// @@ -97,6 +97,21 @@ .itable none 0 0 2 $1 left $2 left .endmacro + +. --- A macro for a "tainted" marker, done as a one-element table +.macro tmark +.itable none 0 0 1 10pt left +.row &'Tainted'& +.endtable +.endmacro +. --- A macro for a tainted variable, adding a taint-marker +. --- and including the .vitem and .vindex +.macro tvar +.vitem $1 +.vindex $1 +.tmark +.endmacro + . --- A macro that generates .row, but puts &I; at the start of the first . --- argument, thus indenting it. Assume a minimum of two arguments, and . --- allow up to four arguments, which is as many as we'll ever need. @@ -6998,7 +7013,7 @@ IPv4, in dotted-quad form. (Exim converts IPv4-mapped IPv6 addresses to this notation before executing the lookup.) One option is supported, "ret=full", to request the return of the entire line -rather than omitting the key porttion. +rather than omitting the key portion. Note however that the key portion will have been de-quoted. .next @@ -10663,16 +10678,32 @@ expansion items. This item inserts &"raw"& header lines. It is described with the &%header%& expansion item in section &<>& above. -.vitem "&*${run{*&<&'command'&>&*&~*&<&'args'&>&*}{*&<&'string1'&>&*}&&& +.vitem "&*${run <&'options'&> {*&<&'command&~arg&~list'&>&*}{*&<&'string1'&>&*}&&& {*&<&'string2'&>&*}}*&" .cindex "expansion" "running a command" .cindex "&%run%& expansion item" -The command and its arguments are first expanded as one string. The string is -split apart into individual arguments by spaces, and then the command is run +This item runs an external command, as a subprocess. +.new +One option is supported after the word &'run'&, comma-separated. + +If the option &'preexpand'& is not used, +the command string is split into individual arguments by spaces +and then each argument is expanded. +Then the command is run in a separate process, but under the same uid and gid. As in other command executions from Exim, a shell is not used by default. If the command requires a shell, you must explicitly code it. +The command name may not be tainted, but the remaining arguments can be. +&*Note*&: if tainted arguments are used, they are supplied by a +potential attacker; +a careful assessment for security vulnerabilities should be done. + +If the option &'preexpand'& is used, +.wen +the command and its arguments are first expanded as one string. The result is +split apart into individual arguments by spaces, and then the command is run +as above. Since the arguments are split by spaces, when there is a variable expansion which has an empty result, it will cause the situation that the argument will simply be omitted when the program is actually executed by Exim. If the @@ -10683,6 +10714,9 @@ in a string containing quotes, because it would interfere with the quotes around the command arguments. A possible guard against this is to wrap the variable in the &%sg%& operator to change any quote marks to some other character. +.new +Neither the command nor any argument may be tainted. +.wen The standard input for the command exists, but is empty. The standard output and standard error are set to the same file descriptor. @@ -10800,16 +10834,16 @@ SRS encoding. See SECT &<>& for details. -.vitem &*${substr{*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*& +.vitem &*${substr{*&<&'start'&>&*}{*&<&'len'&>&*}{*&<&'subject'&>&*}}*& .cindex "&%substr%& expansion item" .cindex "substring extraction" .cindex "expansion" "substring extraction" The three strings are expanded; the first two must yield numbers. Call them <&'n'&> and <&'m'&>. If you are using fixed values for these numbers, that is, -if <&'string1'&> and <&'string2'&> do not change when they are expanded, you +if <&'start'&> and <&'len'&> do not change when they are expanded, you can use the simpler operator notation that avoids some of the braces: .code -${substr__:} +${substr__:} .endd The second number is optional (in both notations). If it is absent in the simpler format, the preceding underscore must also be @@ -11902,6 +11936,19 @@ ${if inlisti{Needle}{fOo:NeeDLE:bAr}} ${if forany{fOo:NeeDLE:bAr}{eqi{$item}{Needle}}} .endd +.new +The variable &$value$& will be set for a successful match and can be +used in the success clause of an &%if%& expansion item using the condition. +.cindex "tainted data" "de-tainting" +It will have the same taint status as the list; expansions such as +.code +${if inlist {$h_mycode:} {0 : 1 : 42} {$value}} +.endd +can be used for de-tainting. +Any previous &$value$& is restored after the if. +.wen + + .vitem &*isip&~{*&<&'string'&>&*}*& &&& &*isip4&~{*&<&'string'&>&*}*& &&& &*isip6&~{*&<&'string'&>&*}*& @@ -12098,6 +12145,18 @@ item can be used, as in all address lists, to cause subsequent items to have their local parts matched casefully. Domains are always matched caselessly. +.new +The variable &$value$& will be set for a successful match and can be +used in the success clause of an &%if%& expansion item using the condition. +.cindex "tainted data" "de-tainting" +It will have the same taint status as the list; expansions such as +.code +${if match_local_part {$local_part} {alice : bill : charlotte : dave} {$value}} +.endd +can be used for de-tainting. +Any previous &$value$& is restored after the if. +.wen + Note that <&'string2'&> is not itself subject to string expansion, unless Exim was built with the EXPAND_LISTMATCH_RHS option. @@ -12293,6 +12352,16 @@ parsed but not evaluated. This section contains an alphabetical list of all the expansion variables. Some of them are available only when Exim is compiled with specific options such as support for TLS or the content scanning extension. +.new +.cindex "tainted data" +Variables marked as &'tainted'& are likely to carry data supplied by +a potential attacker. +Variables without such marking may also, depending on how their +values are created. +Such variables should not be further expanded, +used as filenames +or used as command-line arguments for external commands. +.wen .vlist .vitem "&$0$&, &$1$&, etc" @@ -12307,6 +12376,9 @@ variables may also be set externally by some other matching process which precedes the expansion of the string. For example, the commands available in Exim filter files include an &%if%& command with its own regular expression matching condition. +.new +If the subject string was tainted then any captured substring will also be. +.wen .vitem "&$acl_arg1$&, &$acl_arg2$&, etc" Within an acl condition, expansion condition or expansion item @@ -12432,11 +12504,10 @@ authentication, which means this variable could also be visible in all of the ACL's as well. -.vitem &$authenticated_sender$& +.tvar &$authenticated_sender$& .cindex "sender" "authenticated" .cindex "authentication" "sender" .cindex "AUTH" "on MAIL command" -.vindex "&$authenticated_sender$&" When acting as a server, Exim takes note of the AUTH= parameter on an incoming SMTP MAIL command if it believes the sender is sufficiently trusted, as described in section &<>&. Unless the data is the string @@ -12588,8 +12659,7 @@ the following data from the lookup: the list's domain name, the key that was looked up, the contents of any associated TXT record, and the value from the main A record. See section &<>& for more details. -.vitem &$domain$& -.vindex "&$domain$&" +.tvar &$domain$& When an address is being routed, or delivered on its own, this variable contains the domain. Uppercase letters in the domain are converted into lower case for &$domain$&. @@ -12690,6 +12760,7 @@ There may be other characters following the minor version. This value may be overridden by the &%exim_version%& main config option. .vitem &$header_$&<&'name'&> +.tmark This is not strictly an expansion variable. It is expansion syntax for inserting the message header line with the given name. Note that the name must be terminated by colon or white space, because it may contain a wide variety of @@ -12750,6 +12821,7 @@ allows you, for example, to do things like this: deny hosts = net-lsearch;/some/file message = $host_data .endd + .vitem &$host_lookup_deferred$& .cindex "host name" "lookup, failure of" .vindex "&$host_lookup_deferred$&" @@ -12832,8 +12904,7 @@ This variable contains the system load average, multiplied by 1000 so that it is an integer. For example, if the load average is 0.21, the value of the variable is 210. The value is recomputed every time the variable is referenced. -.vitem &$local_part$& -.vindex "&$local_part$&" +.tvar &$local_part$& When an address is being routed, or delivered on its own, this variable contains the local part. When a number of addresses are being delivered together (for example, multiple RCPT commands in an SMTP @@ -13008,11 +13079,10 @@ This variable is set at the start of a delivery attempt to contain the number of seconds since the message was received. It does not change during a single delivery attempt. -.vitem &$message_body$& +.tvar &$message_body$& .cindex "body of message" "expansion variable" .cindex "message body" "in expansion" .cindex "binary zero" "in message body" -.vindex "&$message_body$&" .oindex "&%message_body_visible%&" This variable contains the initial portion of a message's body while it is being delivered, and is intended mainly for use in filter files. The maximum @@ -13025,10 +13095,9 @@ easier to search for phrases that might be split over a line break. However, this can be disabled by setting &%message_body_newlines%& to be true. Binary zeros are always converted into spaces. -.vitem &$message_body_end$& +.tvar &$message_body_end$& .cindex "body of message" "expansion variable" .cindex "message body" "in expansion" -.vindex "&$message_body_end$&" This variable contains the final portion of a message's body while it is being delivered. The format and maximum size are as for &$message_body$&. @@ -13055,15 +13124,13 @@ received. &*Note*&: This is &'not'& the contents of the &'Message-ID:'& header line; it is the local id that Exim assigns to the message, for example: &`1BXTIK-0001yO-VA`&. -.vitem &$message_headers$& -.vindex &$message_headers$& +.tvar &$message_headers$& This variable contains a concatenation of all the header lines when a message is being processed, except for lines added by routers or transports. The header lines are separated by newline characters. Their contents are decoded in the same way as a header line that is inserted by &%bheader%&. -.vitem &$message_headers_raw$& -.vindex &$message_headers_raw$& +.tvar &$message_headers_raw$& This variable is like &$message_headers$& except that no processing of the contents of header lines is done. @@ -13140,9 +13207,8 @@ details, see section &<>&. These variables are counters that can be incremented by means of the &%add%& command in filter files. -.vitem &$original_domain$& +.tvar &$original_domain$& .vindex "&$domain$&" -.vindex "&$original_domain$&" When a top-level address is being processed for delivery, this contains the same value as &$domain$&. However, if a &"child"& address (for example, generated by an alias, forward, or filter file) is being processed, this @@ -13155,9 +13221,8 @@ If a new address is created by means of a &%deliver%& command in a system filter, it is set up with an artificial &"parent"& address. This has the local part &'system-filter'& and the default qualify domain. -.vitem &$original_local_part$& +.tvar &$original_local_part$& .vindex "&$local_part$&" -.vindex "&$original_local_part$&" When a top-level address is being processed for delivery, this contains the same value as &$local_part$&, unless a prefix or suffix was removed from the local part, because &$original_local_part$& always contains the full local @@ -13195,13 +13260,11 @@ messages received via the command line, this is the uid of the sending user. For messages received by SMTP over TCP/IP, this is normally the uid of the Exim user. -.vitem &$parent_domain$& -.vindex "&$parent_domain$&" +.tvar &$parent_domain$& This variable is similar to &$original_domain$& (see above), except that it refers to the immediately preceding parent address. -.vitem &$parent_local_part$& -.vindex "&$parent_local_part$&" +.tvar &$parent_local_part$& This variable is similar to &$original_local_part$& (see above), except that it refers to the immediately preceding parent address. @@ -13220,6 +13283,11 @@ This is not an expansion variable, but is mentioned here because the string (described under &%transport_filter%& in chapter &<>&). It cannot be used in general expansion strings, and provokes an &"unknown variable"& error if encountered. +.new +&*Note*&: This value permits data supplied by a potential attacker to +be used in the command for a &(pipe)& transport. +Such configurations should be carefully assessed for security vulnerbilities. +.wen .vitem &$primary_hostname$& .vindex "&$primary_hostname$&" @@ -13309,8 +13377,7 @@ including the one added by Exim (so its value is always greater than zero). It is available in the DATA ACL, the non-SMTP ACL, and while routing and delivering. -.vitem &$received_for$& -.vindex "&$received_for$&" +.tvar &$received_for$& If there is only a single recipient address in an incoming message, this variable contains that address when the &'Received:'& header line is being built. The value is copied after recipient rewriting has happened, but before @@ -13402,8 +13469,7 @@ MAIL). The main use of this variable is expected to be to distinguish between rejections of MAIL and rejections of RCPT. -.vitem &$recipients$& -.vindex "&$recipients$&" +.tvar &$recipients$& This variable contains a list of envelope recipients for a message. A comma and a space separate the addresses in the replacement text. However, the variable is not generally available, to prevent exposure of Bcc recipients in @@ -13440,10 +13506,12 @@ This variable is set to contain the matching regular expression after a When a &%regex%& or &%mime_regex%& ACL condition succeeds, these variables contain the captured substrings identified by the regular expression. +.new +If the subject string was tainted then so will any captured substring. +.wen -.vitem &$reply_address$& -.vindex "&$reply_address$&" +.tvar &$reply_address$& When a message is being processed, this variable contains the contents of the &'Reply-To:'& header line if one exists and it is not empty, or otherwise the contents of the &'From:'& header line. Apart from the removal of leading @@ -13492,8 +13560,7 @@ One of its values causes the address to be passed to another router. When this happens, &$self_hostname$& is set to the name of the local host that the original router encountered. In other circumstances its contents are null. -.vitem &$sender_address$& -.vindex "&$sender_address$&" +.tvar &$sender_address$& When a message is being processed, this variable contains the sender's address that was received in the message's envelope. The case of letters in the address is retained, in both the local part and the domain. For bounce messages, the @@ -13508,12 +13575,10 @@ distinguish it from data from a recipient address. The value does not persist after the end of the current ACL statement. If you want to preserve it for longer, you can save it in an ACL variable. -.vitem &$sender_address_domain$& -.vindex "&$sender_address_domain$&" +.tvar &$sender_address_domain$& The domain portion of &$sender_address$&. -.vitem &$sender_address_local_part$& -.vindex "&$sender_address_local_part$&" +.tvar &$sender_address_local_part$& The local part portion of &$sender_address$&. .vitem &$sender_data$& @@ -13551,8 +13616,7 @@ This boolean variable is true if a successful HELO verification was .cindex "DNS" "DNSSEC" done using DNS information the resolver library stated was authenticated data. -.vitem &$sender_helo_name$& -.vindex "&$sender_helo_name$&" +.tvar &$sender_helo_name$& When a message is received from a remote host that has issued a HELO or EHLO command, the argument of that command is placed in this variable. It is also set if HELO or EHLO is used when a message is received using SMTP locally via @@ -13609,8 +13673,7 @@ all EDNS0 options, then this will have no effect. OpenBSD's asr resolver is known to currently ignore EDNS0, documented in CAVEATS of asr_run(3). -.vitem &$sender_host_name$& -.vindex "&$sender_host_name$&" +.tvar &$sender_host_name$& When a message is received from a remote host, this variable contains the host's name as obtained by looking up its IP address. For messages received by other means, this variable is empty. @@ -13728,8 +13791,7 @@ host name, as specified by the &%smtp_active_hostname%& option. The value of &$smtp_active_hostname$& is saved with any message that is received, so its value can be consulted during routing and delivery. -.vitem &$smtp_command$& -.vindex "&$smtp_command$&" +.tvar &$smtp_command$& During the processing of an incoming SMTP command, this variable contains the entire command. This makes it possible to distinguish between HELO and EHLO in the HELO ACL, and also to distinguish between commands such as these: @@ -13742,9 +13804,8 @@ command, the address in &$smtp_command$& is the original address before any rewriting, whereas the values in &$local_part$& and &$domain$& are taken from the address after SMTP-time rewriting. -.vitem &$smtp_command_argument$& +.tvar &$smtp_command_argument$& .cindex "SMTP" "command, argument for" -.vindex "&$smtp_command_argument$&" While an ACL is running to check an SMTP command, this variable contains the argument, that is, the text that follows the command name, with leading white space removed. Following the introduction of &$smtp_command$&, this variable is @@ -13985,8 +14046,7 @@ which is not the leaf. Observability for TLS session resumption. See &<>& for details. -.vitem &$tls_in_sni$& -.vindex "&$tls_in_sni$&" +.tvar &$tls_in_sni$& .vindex "&$tls_sni$&" .cindex "TLS" "Server Name Indication" .cindex "TLS" SNI @@ -22806,9 +22866,10 @@ an ideal name for this feature here, but as it was already implemented for the The expansion variables &$host$& and &$host_address$& are available when the transport is a remote one. They contain the name and IP address of the host to which the message is being sent. For example: +. used to have $sender_address in this cmdline, but it's tainted .code transport_filter = /some/directory/transport-filter.pl \ - $host $host_address $sender_address $pipe_addresses + $host $host_address $pipe_addresses .endd Two problems arise if you want to use more complicated expansion items to @@ -24679,6 +24740,11 @@ This list is a compromise for maximum compatibility with other MTAs. Note that the &%environment%& option can be used to add additional variables to this environment. The environment for the &(pipe)& transport is not subject to the &%add_environment%& and &%keep_environment%& main config options. +.new +&*Note*&: Using enviroment variables loses track of tainted data. +Writers of &(pipe)& transport commands should be wary of data supplied +by potential attackers. +.wen .display &`DOMAIN `& the domain of the address &`HOME `& the home directory, if set @@ -24770,6 +24836,11 @@ the &%path%& option below). The command is split up into separate arguments by Exim, and each argument is separately expanded, as described in section &<>& above. +.new +.cindex "tainted data" +No part of the resulting command may be tainted. +.wen + .option environment pipe string&!! unset .cindex "&(pipe)& transport" "environment for command" @@ -25085,12 +25156,15 @@ use a shell to run pipe commands. .cindex "Cyrus" The next example shows a transport and a router for a system where local deliveries are handled by the Cyrus IMAP server. +. Used to have R: local_part_suffix = .* + T: -m $local_part_suffix_v +. but that suffix is tainted so cannot be used in a command arg +. Really, you'd want to use a lookup for acceptable suffixes to do real detainting .code # transport local_delivery_cyrus: driver = pipe command = /usr/cyrus/bin/deliver \ - -m ${substr_1:$local_part_suffix} -- $local_part + -- $local_part_data user = cyrus group = mail return_output @@ -25102,7 +25176,6 @@ local_delivery_cyrus: local_user_cyrus: driver = accept check_local_user - local_part_suffix = .* transport = local_delivery_cyrus .endd Note the unsetting of &%message_prefix%& and &%message_suffix%&, and the use of @@ -25468,12 +25541,45 @@ servers or different local IP addresses. For example, if you want the string that is used for &%helo_data%& to be obtained by a DNS lookup of the outgoing interface address, you could use this: .code -helo_data = ${lookup dnsdb{ptr=$sending_ip_address}{$value}\ +helo_data = ${lookup dnsdb{ptr=$sending_ip_address} \ + {${listextract{1}{<\n $value}}} \ {$primary_hostname}} .endd The use of &%helo_data%& applies both to sending messages and when doing callouts. +.new +.option host_name_extract smtp "string list&!!" "see below" +.cindex "load balancer" "hosts behind" +.cindex TLS resumption +Some mail-accepting sites +(notably Microsoft) +operate many servers behind a network load-balancer. When this is done, +with separated TLS session caches, TLS session resuption becomes problematic. +It will only succeed when the same server happens to be selected by the +load-balancer, matching the session stored in the client's cache. + +Exim can pull out a server name, if there is one, from the response to the +client's SMTP EHLO command. +The default value of this option: +.code + ${if and { {match {$host} {.outlook.com\$}} \ + {match {$item} {\N^250-([\w.]+)\s\N}} \ + } {$1}} +.endd +suffices for one known case. +During the expansion of this option the &$item$& variable will have the +server's EHLO response. +The result of the option expansion is included in the key used to store and +retrieve the TLS session, for session resumption. + +Operators of high-load sites may wish to evaluate their logs for indications +of other destination sites operating load-balancers, and develop a suitable +expression for this option. +The smtp:ehlo event and the &$tls_out_resumption$& variable +will be useful for such work. +.wen + .option hosts smtp "string list&!!" unset Hosts are associated with an address by a router such as &(dnslookup)&, which finds the hosts by looking up the address domain in the DNS, or by @@ -25541,7 +25647,10 @@ so combines well with TCP Fast Open. See also the &%pipelining_connect_advertise_hosts%& main option. Note: -When the facility is used, the transport &%helo_data%& option +.new +When the facility is used, if the transport &%interface%& option is unset +the &%helo_data%& option +.wen will be expanded before the &$sending_ip_address$& variable is filled in. A check is made for the use of that variable, without the @@ -29817,8 +29926,10 @@ nothing more to it. Choosing a sensible value not derived insecurely is the only point of caution. The &$tls_out_sni$& variable will be set to this string for the lifetime of the client connection (including during authentication). +.new If DANE validated the connection attempt then the value of the &%tls_sni%& option -is forced to the domain part of the recipient address. +is forced to the name of the destination host, after any MX- or CNAME-following. +.wen Except during SMTP client sessions, if &$tls_in_sni$& is set then it is a string received from a client. @@ -33012,7 +33123,7 @@ situation has been previously met. It uses a hints database to record a timestamp against a key. host. The syntax of the condition is: .display -&`seen =`& <&'time interval'&> &`/`& <&'options'&> +&`seen =`& <&'optional flag'&><&'time interval'&> &`/`& <&'options'&> .endd For example, @@ -33021,8 +33132,10 @@ defer seen = -5m / key=${sender_host_address}_$local_part@$domain .endd in a RCPT ACL will implement simple greylisting. -The parameters for the condition -are an interval followed, slash-separated, by a list of options. +The parameters for the condition are +a possible minus sign, +then an interval, +then, slash-separated, a list of options. The interval is taken as an offset before the current time, and used for the test. If the interval is preceded by a minus sign then the condition returns @@ -33040,6 +33153,8 @@ no record create or update is done. If a &%write%& option is given then a record create or update is always done. An update is done if the test is for &"since"&. +If none of those hold and there was no existing record, +a record is created. Creates and updates are marked with the current time. @@ -39422,9 +39537,6 @@ or (in case &*-a*& switch is specified) .code exim -bp .endd -The &*-C*& option is used to specify an alternate &_exim.conf_& which might -contain alternate exim configuration the queue management might be using. - to obtain a queue listing, and then greps the output to select messages that match given criteria. The following selection options are available: @@ -39481,7 +39593,22 @@ Display messages in reverse order. Include delivered recipients in queue listing. .endlist +The following options give alternates for configuration: + +.vlist +.vitem &*-C*&&~<&'config&~file'&> +is used to specify an alternate &_exim.conf_& which might +contain alternate exim configuration the queue management might be using. + +.vitem &*-E*&&~<&'path'&> +can be used to specify a path for the exim binary, +overriding the built-in one. +.endlist + There is one more option, &%-h%&, which outputs a list of options. +.new +At least one selection option, or either the &*-c*& or &*-h*& option, must be given. +.wen @@ -39866,8 +39993,9 @@ The entire contents of a database are written to the standard output by the &'exim_dumpdb'& program, .new taking as arguments the spool and database names. -An option &'-z'& may be given to regest times in UTC; +An option &'-z'& may be given to request times in UTC; otherwise times are in the local timezone. +An option &'-k'& may be given to dump only the record keys. .wen For example, to dump the retry database: .code