Docs: update DKIM standards info

[users/heiko/exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 628a44ddfb7bc259c2216a5e44d91040ed5416d6..112c1efa20beeb8f2674bdfc1da9956a5b7cd9f1 100644 (file)
--- 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
   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.
 .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 &<<SECDANE>>& for more details.
 
 to try to use DNSSEC for all queries and to use DANE for delivery;
 see section &<<SECDANE>>& 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.
 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
   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
 .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.
 
 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
 .code
 local_delivery:
   driver = appendfile


@@ -9523,6 +9537,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.
 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.
 . XXX should be a UTF-8 compare
 
 The results of matching are handled as above.


@@ -9570,6 +9586,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.
 
 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
 
 
 .wen
 
 


@@ -9578,7 +9596,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
 .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 (&<<SECTlistsepchange>>&).
+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
 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 +9854,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
 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 (&<<SECTlistsepchange>>&).

 
 The first field of the list is numbered one.
 If the number is negative, the fields are
 
 The first field of the list is numbered one.
 If the number is negative, the fields are


@@ -9929,7 +9948,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
 .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 (&<<SECTlistsepchange>>&).
+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
 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 +10154,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
 .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 (&<<SECTlistsepchange>>&).
+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
 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 +10284,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
 .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 (&<<SECTlistsepchange>>&).

 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.
 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 +11295,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
 .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 (&<<SECTlistsepchange>>&).
+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
 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 +13676,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
 .endlist
 
 The default list separator in both cases is a colon, but this can be changed as

-described in section &<<SECTlistconstruct>>&. When IPv6 addresses are involved,
+described in section &<<SECTlistsepchange>>&. When IPv6 addresses are involved,

 it is usually best to change the separator to avoid having to double all the
 colons. For example:
 .code
 it is usually best to change the separator to avoid having to double all the
 colons. For example:
 .code


@@ -13721,7 +13743,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
 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 (&<<SECTlistsepchange>>&) 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
 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 +17500,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
 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 (&<<SECTlistsepchange>>&) >to avoid confusion under IPv6.

 
 &*Note*&: Under versions of OpenSSL preceding 1.1.1,
 when a list of more than one
 
 &*Note*&: Under versions of OpenSSL preceding 1.1.1,
 when a list of more than one


@@ -18282,7 +18305,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
 .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 &<<SECTlistconstruct>>&), and a port can be specified with
+changed (see section &<<SECTlistsepchange>>&), 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
 &<<SECTformatonehostitem>>&).
 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
 &<<SECTformatonehostitem>>&).


@@ -18314,7 +18337,7 @@ and the discussion in chapter &<<CHAPenvironment>>&.
 .cindex "header lines" "adding"
 .cindex "router" "adding header lines"
 This option specifies a list of text headers,
 .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 &<<SECTlistsepchange>>&),

 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
 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 +18375,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,
 .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 &<<SECTlistsepchange>>&),

 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
 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 +18658,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
 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
+(&<<SECTlistsepchange>>&).

 If any expansion is forced to fail, the item is ignored. Other expansion
 failures cause routing of the address to be deferred.
 
 If any expansion is forced to fail, the item is ignored. Other expansion
 failures cause routing of the address to be deferred.
 


@@ -19737,7 +19761,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
 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 &<<SECTlistconstruct>>&.
+as described in section &<<SECTlistsepchange>>&.

 
 If the list of hosts was obtained from a &%route_list%& item, the following
 variables are set during its expansion:
 
 If the list of hosts was obtained from a &%route_list%& item, the following
 variables are set during its expansion:


@@ -21462,7 +21486,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,
 .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 &<<SECTlistsepchange>>&),

 which are (separately) expanded and added to the header
 portion of a message as it is transported, as described in section
 &<<SECTheadersaddrem>>&. Additional header lines can also be specified by
 which are (separately) expanded and added to the header
 portion of a message as it is transported, as described in section
 &<<SECTheadersaddrem>>&. Additional header lines can also be specified by


@@ -21488,7 +21512,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,
 .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 &<<SECTlistsepchange>>&);

 these headers are omitted from the message as it is transported, as described
 in section &<<SECTheadersaddrem>>&. Header removal can also be specified by
 routers.
 these headers are omitted from the message as it is transported, as described
 in section &<<SECTheadersaddrem>>&. Header removal can also be specified by
 routers.


@@ -23561,7 +23585,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
 .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
 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 +24661,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
 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 (&<<SECTlistsepchange>>&).
+For example:

 .code
 interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061
 .endd
 .code
 interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061
 .endd


@@ -32552,7 +32578,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,
 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 &<<SECTlistsepchange>>&).

 .endlist
 
 You can append a &`defer_ok`& element to the &%malware%& argument list to accept
 .endlist
 
 You can append a &`defer_ok`& element to the &%malware%& argument list to accept


@@ -32635,7 +32661,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
 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
 .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


@@ -32663,7 +32689,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%&
 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 &<<SECTlistsepchange>>&):

 .code
 spamd_address = 192.168.2.10 783 : \
                 192.168.2.11 783 : \
 .code
 spamd_address = 192.168.2.10 783 : \
                 192.168.2.11 783 : \


@@ -32676,7 +32702,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
 
 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 (&<<SECTlistsepchange>>&);
+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,
 
 For TCP socket specifications a host name or IP (v4 or v6, but
 subject to list-separator quoting rules) address can be used,


@@ -39408,8 +39435,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
 
 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)
 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)


@@ -39429,10 +39457,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
 
 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:
 
 .option dkim_hash smtp string&!! sha256
 Can be set to any one of the supported hash methods, which are: