X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/20f0f78891ed20b57218dbf416ab584900a60b54..40fe3ea73eb7524a6143755854633ed8392d39b4:/doc/doc-docbook/spec.xfpt?ds=sidebyside diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 50c110f3d..0bce6fe86 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -6257,6 +6257,9 @@ remote_smtp: dnssec_request_domains = * hosts_try_dane = * .endif +.ifdef _HAVE_PRDR + hosts_try_prdr = * +.endif .endd This transport is used for delivering messages over SMTP connections. The list of remote hosts comes from the router. @@ -6265,6 +6268,11 @@ with over-long lines. The built-in macro _HAVE_DANE guards configuration to try to use DNSSEC for all queries and to use DANE for delivery; see section &<>& for more details. +The &%hosts_try_prdr%& option enables an efficiency SMTP option. It is +negotiated between client and server and not expected to cause problems +but can be disabled if needed. The built-in macro _HAVE_PRDR guards the +use of the &%hosts_try_prdr%& configuration option. + The other remote transport is used when delivering to a specific smarthost with whom there must be some kind of existing relationship, instead of the usual federated system. @@ -6299,6 +6307,9 @@ smarthost_smtp: tls_require_ciphers = SECURE192:-VERS-SSL3.0:-VERS-TLS1.0:-VERS-TLS1.1 .endif .endif +.ifdef _HAVE_PRDR + hosts_try_prdr = * +.endif .endd After the same &%message_size_limit%& hack, we then specify that this Transport can handle messages to multiple domains in one run. The assumption here is @@ -6318,6 +6329,9 @@ ROUTER_SMARTHOST macro, because that is unaffected by CNAMEs present in DNS. You want to specify the hostname which you'll expect to validate for, and that should not be subject to insecure tampering via DNS results. +For the &%hosts_try_prdr%& option see the previous transport. + +All other options are defaulted. .code local_delivery: driver = appendfile @@ -6731,6 +6745,11 @@ 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 &<>&). + +.new +&*Warning 3*&: Do not use an IPv4-mapped IPv6 address for a key; use the +IPv4. Such addresses being searched for are converted to IPv4. +.wen .next .cindex "linear search" .cindex "lookup" "lsearch" @@ -8649,8 +8668,12 @@ to quote keys was made available in &(lsearch)& files. However, the more recently implemented &(iplsearch)& files do require colons in IPv6 keys (notated using the quoting facility) so as to distinguish them from IPv4 keys. For this reason, when the lookup type is &(iplsearch)&, IPv6 addresses are -converted using colons and not dots. In all cases, full, unabbreviated IPv6 +converted using colons and not dots. +.new +In all cases except IPv4-mapped IPv6, full, unabbreviated IPv6 addresses are always used. +The latter are converted to IPv4 addresses, in dotted-quad form. +.wen Ideally, it would be nice to tidy up this anomalous situation by changing to colons in all cases, given that quoting is now available for &(lsearch)&. @@ -9523,6 +9546,8 @@ The expanded <&'string1'&> must be of the form: The braces, commas and colons, and the quoting of the member name are required; the spaces are optional. Matching of the key against the member names is done case-sensitively. +If a returned value is a JSON string, it retains its leading and +trailing quotes. . XXX should be a UTF-8 compare The results of matching are handled as above. @@ -9570,6 +9595,8 @@ apart from leading and trailing white space, which is ignored. Field selection and result handling is as above; there is no choice of field separator. +If a returned value is a JSON string, it retains its leading and +trailing quotes. .wen @@ -9578,7 +9605,8 @@ there is no choice of field separator. .cindex "expansion" "selecting from list by condition" .vindex "&$item$&" After expansion, <&'string'&> is interpreted as a list, colon-separated by -default, but the separator can be changed in the usual way. For each item +default, but the separator can be changed in the usual way (&<>&). +For each item in this list, its value is place in &$item$&, and then the condition is evaluated. If the condition is true, &$item$& is added to the output as an item in a new list; if the condition is false, the item is discarded. The @@ -9835,7 +9863,7 @@ apart from an optional leading minus, and leading and trailing white space (which is ignored). After expansion, <&'string1'&> is interpreted as a list, colon-separated by -default, but the separator can be changed in the usual way. +default, but the separator can be changed in the usual way (&<>&). The first field of the list is numbered one. If the number is negative, the fields are @@ -9929,7 +9957,8 @@ ${lookup nisplus {[name=$local_part],passwd.org_dir:gcos} \ .cindex "expansion" "list creation" .vindex "&$item$&" After expansion, <&'string1'&> is interpreted as a list, colon-separated by -default, but the separator can be changed in the usual way. For each item +default, but the separator can be changed in the usual way (&<>&). +For each item in this list, its value is place in &$item$&, and then <&'string2'&> is expanded and added to the output as an item in a new list. The separator used for the output list is the same as the one used for the input, but a separator @@ -10134,7 +10163,8 @@ locks out the use of this expansion item in filter files. .vindex "&$item$&" This operation reduces a list to a single, scalar string. After expansion, <&'string1'&> is interpreted as a list, colon-separated by default, but the -separator can be changed in the usual way. Then <&'string2'&> is expanded and +separator can be changed in the usual way (&<>&). +Then <&'string2'&> is expanded and assigned to the &$value$& variable. After this, each item in the <&'string1'&> list is assigned to &$item$&, in turn, and <&'string3'&> is expanded for each of them. The result of that expansion is assigned to &$value$& before the next @@ -10263,7 +10293,7 @@ rather than any Unicode-aware character handling. .cindex list sorting .cindex expansion "list sorting" After expansion, <&'string'&> is interpreted as a list, colon-separated by -default, but the separator can be changed in the usual way. +default, but the separator can be changed in the usual way (&<>&). The <&'comparator'&> argument is interpreted as the operator of a two-argument expansion condition. The numeric operators plus ge, gt, le, lt (and ~i variants) are supported. @@ -11274,7 +11304,8 @@ attempt. It is false during any subsequent delivery attempts. .vindex "&$item$&" These conditions iterate over a list. The first argument is expanded to form the list. By default, the list separator is a colon, but it can be changed by -the normal method. The second argument is interpreted as a condition that is to +the normal method (&<>&). +The second argument is interpreted as a condition that is to be applied to each item in the list in turn. During the interpretation of the condition, the current list item is placed in a variable called &$item$&. .ilist @@ -13654,7 +13685,7 @@ listen. Each item may optionally also specify a port. .endlist The default list separator in both cases is a colon, but this can be changed as -described in section &<>&. When IPv6 addresses are involved, +described in section &<>&. When IPv6 addresses are involved, it is usually best to change the separator to avoid having to double all the colons. For example: .code @@ -13721,7 +13752,8 @@ the runtime configuration by &%-D%& is allowed only when the caller is root or exim. The value of &%-oX%& is a list of items. The default colon separator can be -changed in the usual way if required. If there are any items that do not +changed in the usual way (&<>&) if required. +If there are any items that do not contain dots or colons (that is, are not IP addresses), the value of &%daemon_smtp_ports%& is replaced by the list of those items. If there are any items that do contain dots or colons, the value of &%local_interfaces%& is @@ -17477,7 +17509,7 @@ use when sending messages as a client, you must set the &%tls_certificate%& option in the relevant &(smtp)& transport. &*Note*&: If you use filenames based on IP addresses, change the list -separator in the usual way to avoid confusion under IPv6. +separator in the usual way (&<>&) >to avoid confusion under IPv6. &*Note*&: Under versions of OpenSSL preceding 1.1.1, when a list of more than one @@ -18282,7 +18314,7 @@ verifying a sender, verification fails. .cindex "fallback" "hosts specified on router" String expansion is not applied to this option. The argument must be a colon-separated list of host names or IP addresses. The list separator can be -changed (see section &<>&), and a port can be specified with +changed (see section &<>&), and a port can be specified with each name or address. In fact, the format of each item is exactly the same as defined for the list of hosts in a &(manualroute)& router (see section &<>&). @@ -18314,7 +18346,7 @@ and the discussion in chapter &<>&. .cindex "header lines" "adding" .cindex "router" "adding header lines" This option specifies a list of text headers, -newline-separated (by default, changeable in the usual way), +newline-separated (by default, changeable in the usual way &<>&), that is associated with any addresses that are accepted by the router. Each item is separately expanded, at routing time. However, this option has no effect when an address is just being verified. The way in which @@ -18352,7 +18384,7 @@ avoided. The &%repeat_use%& option of the &%redirect%& router may be of help. .cindex "header lines" "removing" .cindex "router" "removing header lines" This option specifies a list of text headers, -colon-separated (by default, changeable in the usual way), +colon-separated (by default, changeable in the usual way &<>&), that is associated with any addresses that are accepted by the router. Each item is separately expanded, at routing time. However, this option has no effect when an address is just being verified. The way in which @@ -18635,7 +18667,8 @@ Before running a router, as one of its precondition tests, Exim works its way through the &%require_files%& list, expanding each item separately. Because the list is split before expansion, any colons in expansion items must -be doubled, or the facility for using a different list separator must be used. +be doubled, or the facility for using a different list separator must be used +(&<>&). If any expansion is forced to fail, the item is ignored. Other expansion failures cause routing of the address to be deferred. @@ -19737,7 +19770,7 @@ and/or IP addresses, optionally also including ports. If the list is written with spaces, it must be protected with quotes. The format of each item in the list is described in the next section. The list separator can be changed -as described in section &<>&. +as described in section &<>&. If the list of hosts was obtained from a &%route_list%& item, the following variables are set during its expansion: @@ -21462,7 +21495,7 @@ value that the router supplies, and also overriding any value associated with .cindex "header lines" "adding in transport" .cindex "transport" "header lines; adding" This option specifies a list of text headers, -newline-separated (by default, changeable in the usual way), +newline-separated (by default, changeable in the usual way &<>&), which are (separately) expanded and added to the header portion of a message as it is transported, as described in section &<>&. Additional header lines can also be specified by @@ -21488,7 +21521,7 @@ checked, since this option does not automatically suppress them. .cindex "header lines" "removing" .cindex "transport" "header lines; removing" This option specifies a list of header names, -colon-separated (by default, changeable in the usual way); +colon-separated (by default, changeable in the usual way &<>&); these headers are omitted from the message as it is transported, as described in section &<>&. Header removal can also be specified by routers. @@ -23561,7 +23594,8 @@ command = /bin/sh -c ${lookup{$local_part}lsearch{/some/file}} .cindex "filter" "transport filter" .vindex "&$pipe_addresses$&" Special handling takes place when an argument consists of precisely the text -&`$pipe_addresses`&. This is not a general expansion variable; the only +&`$pipe_addresses`& (no quotes). +This is not a general expansion variable; the only place this string is recognized is when it appears as an argument for a pipe or transport filter command. It causes each address that is being handled to be inserted in the argument list at that point &'as a separate argument'&. This @@ -24636,7 +24670,8 @@ During the expansion of the &%interface%& option the variables &$host$& and during the expansion of the string. Forced expansion failure, or an empty string result causes the option to be ignored. Otherwise, after expansion, the string must be a list of IP addresses, colon-separated by default, but the -separator can be changed in the usual way. For example: +separator can be changed in the usual way (&<>&). +For example: .code interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061 .endd @@ -26607,7 +26642,7 @@ to be returned. If the result of a successful expansion is an empty string, expansion is &"1"&, &"yes"&, or &"true"&, authentication succeeds and the generic &%server_set_id%& option is expanded and saved in &$authenticated_id$&. For any other result, a temporary error code is returned, with the expanded -string as the error text +string as the error text. &*Warning*&: If you use a lookup in the expansion to find the user's password, be sure to make the authentication fail if the user is unknown. @@ -27435,20 +27470,25 @@ tls: driver = tls server_param1 = ${certextract {subj_altname,mail,>:} \ {$tls_in_peercert}} - server_condition = ${if forany {$auth1} \ + server_condition = ${if and { {eq{$tls_in_certificate_verified}{1}} \ + {forany {$auth1} \ {!= {0} \ {${lookup ldap{ldap:///\ mailname=${quote_ldap_dn:${lc:$item}},\ ou=users,LDAP_DC?mailid} {$value}{0} \ - } } } } + } } } }}} server_set_id = ${if = {1}{${listcount:$auth1}} {$auth1}{}} .endd This accepts a client certificate that is verifiable against any of your configured trust-anchors (which usually means the full set of public CAs) and which has a SAN with a good account name. -Note that the client cert is on the wire in-clear, including the SAN, -whereas a plaintext SMTP AUTH done inside TLS is not. + +Note that, up to TLS1.2, the client cert is on the wire in-clear, including the SAN, +The account name is therefore guessable by an opponent. +TLS 1.3 protects both server and client certificates, and is not vulnerable +in this way. +Likewise, a traditional plaintext SMTP AUTH done inside TLS is not. . An alternative might use . .code @@ -32547,7 +32587,7 @@ A regular expression, in which case the message is scanned for viruses. The condition succeeds if a virus is found and its name matches the regular expression. This allows you to take special actions on certain types of virus. Note that &"/"& characters in the RE must be doubled due to the list-processing, -unless the separator is changed (in the usual way). +unless the separator is changed (in the usual way &<>&). .endlist You can append a &`defer_ok`& element to the &%malware%& argument list to accept @@ -32630,7 +32670,7 @@ intend to use an instance running on the local host you do not need to set you must set the &%spamd_address%& option in the global part of the Exim configuration as follows (example): .code -spamd_address = 192.168.99.45 387 +spamd_address = 192.168.99.45 783 .endd The SpamAssassin protocol relies on a TCP half-close from the client. If your SpamAssassin client side is running a Linux system with an @@ -32658,7 +32698,7 @@ spamd_address = /var/run/spamd_socket You can have multiple &%spamd%& servers to improve scalability. These can reside on other hardware reachable over the network. To specify multiple &%spamd%& servers, put multiple address/port pairs in the &%spamd_address%& -option, separated with colons (the separator can be changed in the usual way): +option, separated with colons (the separator can be changed in the usual way &<>&): .code spamd_address = 192.168.2.10 783 : \ 192.168.2.11 783 : \ @@ -32671,7 +32711,8 @@ condition defers. Unix and TCP socket specifications may be mixed in any order. Each element of the list is a list itself, space-separated by default -and changeable in the usual way; take care to not double the separator. +and changeable in the usual way (&<>&); +take care to not double the separator. For TCP socket specifications a host name or IP (v4 or v6, but subject to list-separator quoting rules) address can be used, @@ -33167,6 +33208,7 @@ in &_Local/Makefile_& (see section &<>& below). .section "API for local_scan()" "SECTapiforloc" .cindex "&[local_scan()]& function" "API description" +.cindex &%dlfunc%& "API description" You must include this line near the start of your code: .code #include "local_scan.h" @@ -39402,8 +39444,9 @@ Signers MUST use RSA keys of at least 1024 bits for all keys. Signers SHOULD use RSA keys of at least 2048 bits. .endd -Support for EC keys is being developed under -&url(https://datatracker.ietf.org/doc/draft-ietf-dcrup-dkim-crypto/). +.new +EC keys for DKIM are defined by RFC 8463. +.wen They are considerably smaller than RSA keys for equivalent protection. As they are a recent development, users should consider dual-signing (by setting a list of selectors, and an expansion for this option) @@ -39423,10 +39466,12 @@ openssl pkey -outform DER -pubout -in dkim_ed25519.private | tail -c +13 | base6 certtool --load_privkey=dkim_ed25519.private --pubkey_info --outder | tail -c +13 | base64 .endd -Note that the format -of Ed25519 keys in DNS has not yet been decided; this release supports -both of the leading candidates at this time, a future release will -probably drop support for whichever proposal loses. +.new +Exim also supports an alternate format +of Ed25519 keys in DNS which was a candidate during development +of the standard, but not adopted. +A future release will probably drop that support. +.wen .option dkim_hash smtp string&!! sha256 Can be set to any one of the supported hash methods, which are: @@ -40376,6 +40421,9 @@ Edit &_Makefile_& in the appropriate sub-directory (&_src/routers_&, &_src/transports_&, &_src/auths_&, or &_src/lookups_&); add a line for the new driver or lookup type and add it to the definition of OBJ. .next +Edit &_OS/Makefile-Base_& adding a &_.o_& file for the predefined-macros, to the +definition of OBJ_MACRO. Add a set of line to do the compile also. +.next Create &_newdriver.h_& and &_newdriver.c_& in the appropriate sub-directory of &_src_&. .next