X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/5bb786d5ad568a88d50d15452aacc8404047e5ca..48d6f3b6c68a33a4ff11650f9f0de858cb5fc256:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index ae3cc1748..6ee615145 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -2886,6 +2886,11 @@ available to admin users. The word &"set"& at the start of a line, followed by a single space, is recognised specially as defining a value for a variable. +.new +.cindex "tainted data" "expansion testing" +If the sequence &",t"& is inserted before the space, +the value is marked as tainted. +.wen The syntax is otherwise the same as the ACL modifier &"set ="&. .cmdopt -bem <&'filename'&> @@ -6841,7 +6846,10 @@ by default, but has an option to omit them (see section &<>&). .cindex "dsearch lookup type" The given file must be an absolute directory path; this is searched for an entry whose name is the key by calling the &[lstat()]& function. -The key may not contain any forward slash characters. +.new +Unless the options (below) permit a path, +.wen +the key may not contain any forward slash characters. If &[lstat()]& succeeds then so does the lookup. .cindex "tainted data" "dsearch result" The result is regarded as untainted. @@ -6850,7 +6858,7 @@ Options for the lookup can be given by appending them after the word "dsearch", separated by a comma. Options, if present, are a comma-separated list having each element starting with a tag name and an equals. -Two options are supported, for the return value and for filtering match +Three options are supported, for the return value and for filtering match candidates. The "ret" option requests an alternate result value of the entire path for the entry. Example: @@ -6858,6 +6866,7 @@ the entire path for the entry. Example: ${lookup {passwd} dsearch,ret=full {/etc}} .endd The default result is just the requested entry. + The "filter" option requests that only directory entries of a given type are matched. The match value is one of "file", "dir" or "subdir" (the latter not matching "." or ".."). Example: @@ -6867,6 +6876,14 @@ ${lookup {passwd} dsearch,filter=file {/etc}} The default matching is for any entry type, including directories and symlinks. +The "key" option relaxes the restriction that only a simple path component can +be searched for, to permit a sequence of path components. Example: +.code +${lookup {foo/bar} dsearch,key=path {/etc}} +.endd +If this option is used, a ".." component in the key is specifically disallowed. +The default operation is that the key may only be a single path component. + An example of how this lookup can be used to support virtual domains is given in section &<>&. @@ -6896,8 +6913,8 @@ key is found. The first key that matches is used; there is no attempt to find a lookup types support only literal keys. &*Warning 2*&: In a host list, you must always use &(net-iplsearch)& so that -the implicit key is the host's IP address rather than its name (see section -&<>&). +the implicit key is the host's IP address rather than its name +(see section &<>&). &*Warning 3*&: Do not use an IPv4-mapped IPv6 address for a key; use the IPv4, in dotted-quad form. (Exim converts IPv4-mapped IPv6 addresses to this @@ -8156,13 +8173,20 @@ option, you can still update it by a query of this form: ${lookup pgsql,servers=master/db/name/pw {UPDATE ...} } .endd -An older syntax places the servers specification before the query, +.new +A now-deprecated syntax places the servers specification before the query, semicolon separated: .code ${lookup mysql{servers=master; UPDATE ...} } .endd -The new version avoids potential issues with tainted -arguments in the query, for explicit expansion. +The new version avoids issues with tainted +arguments explicitly expanded as part of the query. +The entire string within the braces becomes tainted, +including the server sepcification - which is not permissible. +If the older sytax is used, a warning message will be logged. +This syntax will be removed in a future release. +.wen + &*Note*&: server specifications in list-style lookups are still problematic. @@ -8190,6 +8214,11 @@ or delete command), the result of the lookup is the number of rows affected. anything (for example, setting a field to the value it already has), the result is zero because no rows are affected. +.new +To get an encryted connection, use a Mysql option file with the required +parameters for the connection. +.wen + .subsection "Special PostgreSQL features" SECID74 PostgreSQL lookups can also use Unix domain socket connections to the database. @@ -8339,6 +8368,9 @@ type of match and is given below as the &*value*& information. .section "Expansion of lists" "SECTlistexpand" .cindex "expansion" "of lists" Each list is expanded as a single string before it is used. +.cindex "tainted data" tracking +&*Note*&: As a result, if any componend was tainted then the +entire result string becomes tainted. &'Exception: the router headers_remove option, where list-item splitting is done before string-expansion.'& @@ -9220,8 +9252,9 @@ is not used. &*Reminder*&: With this kind of pattern, you must have host &'names'& as keys in the file, not IP addresses. If you want to do lookups based on IP -addresses, you must precede the search type with &"net-"& (see section -&<>&). There is, however, no reason why you could not use +addresses, you must precede the search type with &"net-"& +(see section &<>&). +There is, however, no reason why you could not use two items in the same list, one doing an address lookup and one doing a name lookup, both using the same file. @@ -9534,6 +9567,9 @@ start of a portion of the string that is interpreted and replaced as described below in section &<>& onwards. Backslash is used as an escape character, as described in the following section. +.cindex "tainted data" tracking +If any porttion of the result string is tainted, the entire result is. + Whether a string is expanded depends upon the context. Usually this is solely dependent upon the option for which a value is sought; in this documentation, options for which string expansion is performed are marked with † after @@ -12038,7 +12074,8 @@ where the first item in the list is the empty string. .next The item @[] matches any of the local host's interface addresses. .next -Single-key lookups are assumed to be like &"net-"& style lookups in host lists, +Single-key lookups are assumed to be like &"net-"& style lookups in host lists +(see section &<>&), even if &`net-`& is not specified. There is never any attempt to turn the IP address into a host name. The most common type of linear search for &*match_ip*& is likely to be &*iplsearch*&, in which the file can contain CIDR @@ -14959,6 +14996,7 @@ See also the &'Policy controls'& section above. .row &%dsn_advertise_hosts%& "advertise DSN extensions to these hosts" .row &%ignore_fromline_hosts%& "allow &""From ""& from these hosts" .row &%ignore_fromline_local%& "allow &""From ""& from local SMTP" +.row &%limits_advertise_hosts%& "advertise LIMITS to these hosts" .row &%pipelining_advertise_hosts%& "advertise pipelining to these hosts" .row &%pipelining_connect_advertise_hosts%& "advertise pipelining to these hosts" .row &%prdr_enable%& "advertise PRDR to all hosts" @@ -15706,9 +15744,9 @@ the ACL once for each signature in the message. See section &<>&. -.option dmarc_forensic_sender main string&!! unset -.option dmarc_history_file main string unset -.option dmarc_tld_file main string unset +.option dmarc_forensic_sender main string&!! unset &&& + dmarc_history_file main string unset &&& + dmarc_tld_file main string unset .cindex DMARC "main section options" These options control DMARC processing. See section &<>& for details. @@ -16175,11 +16213,13 @@ set. .cindex "EHLO" "underscores in" .cindex "underscore in EHLO/HELO" This option can be set to a string of rogue characters that are permitted in -all EHLO and HELO names in addition to the standard letters, digits, -hyphens, and dots. If you really must allow underscores, you can set +non-ip-literal EHLO and HELO names in addition to the standard letters, digits, +hyphens, and dots. For examplem if you really must allow underscores, +you can set .code helo_allow_chars = _ .endd +This option does not apply to names that look like ip-literals. Note that the value is one string, not a list. @@ -16543,6 +16583,18 @@ has been built with LDAP support. +.new +.option limits_advertise_hosts main "host list&!!" * +.cindex LIMITS "suppressing advertising" +.cindex "ESMTP extensions" LIMITS +This option can be used to suppress the advertisement of the SMTP +LIMITS extension (RFC 9422) to specific hosts. +If permitted, Exim as a servier will advertise in the EHLO response +the limit for RCPT commands set by the &%recipients_max%& option (if it is set) +and the limit for MAIL commands set by the &%smtp_accept_max_per_connection%& +option. +,wen + .option local_from_check main boolean true .cindex "&'Sender:'& header line" "disabling addition of" .cindex "&'From:'& header line" "disabling checking of" @@ -17446,16 +17498,26 @@ or if the message was submitted locally (not using TCP/IP), and the &%-bnq%& option was not set. -.option recipients_max main integer 50000 +.option recipients_max main integer&!! 50000 .cindex "limit" "number of recipients" .cindex "recipient" "maximum number" -If this option is set greater than zero, it specifies the maximum number of +If the value resulting from expanding this option +is set greater than zero, it specifies the maximum number of original recipients for any message. Additional recipients that are generated by aliasing or forwarding do not count. SMTP messages get a 452 response for all recipients over the limit; earlier recipients are delivered as normal. Non-SMTP messages with too many recipients are failed, and no deliveries are done. +.new +For SMTP message the expansion is done after the connection is +accepted (but before any SMTP conversation) and may depend on +the IP addresses and port numbers of the connection. +&*Note*&: If an expansion is used for the option, +care should be taken that a resonable value results for +non-SMTP messages. +.wen + .cindex "RCPT" "maximum number of incoming" &*Note*&: The RFCs specify that an SMTP server should accept at least 100 RCPT commands in a single message. @@ -25343,6 +25405,13 @@ over a single TCP/IP connection. If the value is zero, there is no limit. For testing purposes, this value can be overridden by the &%-oB%& command line option. +.new +.cindex "ESMTP extensions" LIMITS +If the peer advertises a LIMITS extension with a MAILMAX value, +and either TLSS is in use or was not advertised, +that value also constrains the result of this option. +.wen + .option dane_require_tls_ciphers smtp string&!! unset .cindex "TLS" "requiring specific ciphers for DANE" @@ -25919,6 +25988,14 @@ each set of addresses is treated independently, and so can cause parallel connections to the same host if &%remote_max_parallel%& permits this. +.new +.cindex "ESMTP extensions" LIMITS +If the peer advertises a LIMITS extension with a RCPTMAX value, +and either TLSS is in use or was not advertised, +that value also constrains the result of this option +and no parallel connections will be caused on meeting the RCPTMAX limit. +.wen + .option message_linelength_limit smtp integer 998 .cindex "line length" limit @@ -25950,6 +26027,14 @@ If the connection is DANE-enabled then this option is ignored; only messages having the domain used for the DANE TLSA lookup are sent on the connection. +.new +.cindex "ESMTP extensions" LIMITS +If the peer advertises a LIMITS extension with a RCPTDOMAINMAX value, +and either TLSS is in use or was not advertised, +this option is regarded as being false. +.wen + + .option port smtp string&!! "see below" .cindex "port" "sending TCP/IP" .cindex "TCP/IP" "setting outgoing port" @@ -30476,12 +30561,17 @@ Section 4.3 of that document. .subsection General Under GnuTLS, DANE is only supported from version 3.0.0 onwards. -DANE is specified in published RFCs and decouples certificate authority trust +DANE is specified in RFC 6698. It decouples certificate authority trust selection from a "race to the bottom" of "you must trust everything for mail to get through". -There is an alternative technology called MTA-STS, which -instead publishes MX trust anchor information on an HTTPS website. At the -time this text was last updated, MTA-STS was still a draft, not yet an RFC. +It does retain the need to trust the assurances provided by the DNSSEC tree. + +There is an alternative technology called MTA-STS (RFC 8461), which +instead publishes MX trust anchor information on an HTTPS website. +The discovery of the address for that website does not (per standard) +require DNSSEC, and could be regarded as being less secure than DANE +as a result. + Exim has no support for MTA-STS as a client, but Exim mail server operators can choose to publish information describing their TLS configuration using MTA-STS to let those clients who do use that protocol derive trust @@ -30706,6 +30796,10 @@ and the &%acl_smtp_mime%& ACLs. The &%acl_smtp_dkim%& ACL is available only when Exim is compiled with DKIM support enabled (which is the default). +If, for a specific message, an ACL control +&*dkim_disable_verify*& +has been set, this &%acl_smtp_dkim%& ACL is not called. + The ACL test specified by &%acl_smtp_dkim%& happens after a message has been received, and is executed for each DKIM signature found in a message. If not otherwise specified, the default action is to accept. @@ -31003,7 +31097,8 @@ option to do this.) .section "Format of an ACL" "SECID199" .cindex "&ACL;" "format of" .cindex "&ACL;" "verbs, definition of" -An individual ACL consists of a number of statements. Each statement starts +An individual ACL definition consists of a number of statements. +Each statement starts with a verb, optionally followed by a number of conditions and &"modifiers"&. Modifiers can change the way the verb operates, define error and log messages, set variables, insert delays, and vary the processing of accepted messages. @@ -31022,6 +31117,9 @@ happens then depends on the verb (and in one case, on a special modifier). Not all the conditions make sense at every testing point. For example, you cannot test a sender address in the ACL that is run for a VRFY command. +The definition of an ACL ends where another starts, +or a different configuration section starts. + .section "ACL verbs" "SECID200" The ACL verbs are as follows: @@ -39061,7 +39159,7 @@ selection marked by asterisks: .irow &`deliver_time`&   "time taken to attempt delivery" .irow &`delivery_size`&   "add &`S=`&&'nnn'& to => lines" .irow &`dkim`& * "DKIM verified domain on <= lines" -.irow &`dkim_verbose`&   "separate full DKIM verification result line, per signature" +.irow &`dkim_verbose`&   "separate full DKIM verification result line, per signature; DKIM signing" .irow &`dnslist_defer`& * "defers of DNS list (aka RBL) lookups" .irow &`dnssec`&   "DNSSEC secured lookups" .irow &`etrn`& * "ETRN commands" @@ -39187,6 +39285,10 @@ verifies successfully a tag of DKIM is added, with one of the verified domains. .cindex log "DKIM verification" .cindex DKIM "verification logging" &%dkim_verbose%&: A log entry is written for each attempted DKIM verification. +.new +Also, on message delivery lines signing information (domain and selector) +is added, tagged with DKIM=. +.wen .next .cindex "log" "dnslist defer" .cindex "DNS list" "logging defer" @@ -41533,8 +41635,11 @@ Exim's DKIM implementation allows for .olist Signing outgoing messages: This function is implemented in the SMTP transport. It can co-exist with all other Exim features -(including transport filters) -except cutthrough delivery. +(including transport filters) except cutthrough delivery. +.new +However, signing options may not depend on headers modified by +routers, the transport or a transport filter. +.wen .next Verifying signatures in incoming messages: This is implemented by an additional ACL (acl_smtp_dkim), which can be called several times per message, with @@ -41742,10 +41847,11 @@ name will be appended. .option dkim_timestamps smtp integer&!! unset This option controls the inclusion of timestamp information in the signature. If not set, no such information will be included. -Otherwise, must be an unsigned number giving an offset in seconds from the current time -for the expiry tag -(eg. 1209600 for two weeks); -both creation (t=) and expiry (x=) tags will be included. +.new +Otherwise, must be an unsigned number giving an offset in seconds from the +current time for the expiry tag (e.g. 1209600 for two weeks); both creation +(t=) and expiry (x=) tags will be included unless the offset is 0 (no expiry). +.wen RFC 6376 lists these tags as RECOMMENDED. @@ -42243,10 +42349,16 @@ The lookup will return the same result strings as can appear in .subsection "SRS (Sender Rewriting Scheme)" SECTSRS .cindex SRS "sender rewriting scheme" +.cindex VERP "variable envelope return path" SRS can be used to modify sender addresses when forwarding so that SPF verification does not object to them. -It operates by encoding the original envelope sender in a new +It can also be used to identify a received bounce message as +likely (or not) having been trigged by a message from the +local system, and for identifying dead addresses in mailing lists. +It is one implementation of a VERP (Variable Envelope Return Path) method. + +SRS operates by encoding the original envelope sender in a new sender local part and using a domain run by the forwarding site as the new domain for the sender. Any DSN message should be returned to this new sender at the forwarding site, which can extract the @@ -42336,7 +42448,8 @@ Example usage: allow_fail data = :fail: Invalid SRS recipient address - #... further routers here + #... further routers here get inbound_srs-redirected recipients + # and any that were not SRS'd # transport; should look like the non-forward outbound @@ -42922,10 +43035,13 @@ 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 .itable all 0 0 4 25* left 10* center 15* center 50* left .row auth:fail after both "per driver per authentication attempt" .row dane:fail after transport "per connection" +.row dns:fail after both "per lookup" .row msg:complete after main "per message" .row msg:defer after transport "per message per delivery try" .row msg:delivery after transport "per recipient" @@ -42959,6 +43075,7 @@ with the event type: .itable all 0 0 2 20* left 80* left .row auth:fail "smtp response" .row dane:fail "failure reason" +.row dns:fail "failure reason, key and lookup-type" .row msg:defer "error string" .row msg:delivery "smtp confirmation message" .row msg:fail:internal "failure reason" @@ -43008,6 +43125,11 @@ chain element received on the connection. For OpenSSL it will trigger for every chain element including those loaded locally. +.new +For dns:fail events from dnsdb lookups, a &"defer_never"& option does not +affect the reporting of DNS_AGAIN. +.wen + . //////////////////////////////////////////////////////////////////////////// . ////////////////////////////////////////////////////////////////////////////