DKIM: permit dkim_private_key to override dkim_strict on signing. Bug 2220

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index faa84977c8c866521f8cee039a9bdab051cac5ef..e36e32190ce6bf77cbd8d231149f7e494b01c10e 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -1667,6 +1667,9 @@ Symbolic links to the sources are installed in this directory, which is where
 the actual building takes place. In most cases, Exim can discover the machine
 architecture and operating system for itself, but the defaults can be
 overridden if necessary.
 the actual building takes place. In most cases, Exim can discover the machine
 architecture and operating system for itself, but the defaults can be
 overridden if necessary.

+.cindex compiler requirements
+.cindex compiler version
+A C99-capable compiler will be required for the build.

 
 
 .section "PCRE library" "SECTpcre"
 
 
 .section "PCRE library" "SECTpcre"


@@ -2788,6 +2791,13 @@ files or databases you are using, you must exit and restart Exim before trying
 the same lookup again. Otherwise, because each Exim process caches the results
 of lookups, you will just get the same result as before.
 
 the same lookup again. Otherwise, because each Exim process caches the results
 of lookups, you will just get the same result as before.
 

+.new
+Macro processing is done on lines before string-expansion: new macros can be
+defined and macros will be expanded.
+Because macros in the config file are often used for secrets, those are only
+available to admin users.
+.wen
+

 .vitem &%-bem%&&~<&'filename'&>
 .oindex "&%-bem%&"
 .cindex "testing" "string expansion"
 .vitem &%-bem%&&~<&'filename'&>
 .oindex "&%-bem%&"
 .cindex "testing" "string expansion"


@@ -4274,7 +4284,7 @@ or &%-bs%& is used. For &%-bh%&, the protocol is forced to one of the standard
 SMTP protocol names (see the description of &$received_protocol$& in section
 &<<SECTexpvar>>&). For &%-bs%&, the protocol is always &"local-"& followed by
 one of those same names. For &%-bS%& (batched SMTP) however, the protocol can
 SMTP protocol names (see the description of &$received_protocol$& in section
 &<<SECTexpvar>>&). For &%-bs%&, the protocol is always &"local-"& followed by
 one of those same names. For &%-bS%& (batched SMTP) however, the protocol can

-be set by &%-oMr%&.
+be set by &%-oMr%&. Repeated use of this option is not supported.

 
 .vitem &%-oMs%&&~<&'host&~name'&>
 .oindex "&%-oMs%&"
 
 .vitem &%-oMs%&&~<&'host&~name'&>
 .oindex "&%-oMs%&"


@@ -4374,6 +4384,7 @@ host name and its colon can be omitted when only the protocol is to be set.
 Note the Exim already has two private options, &%-pd%& and &%-ps%&, that refer
 to embedded Perl. It is therefore impossible to set a protocol value of &`d`&
 or &`s`& using this option (but that does not seem a real limitation).
 Note the Exim already has two private options, &%-pd%& and &%-ps%&, that refer
 to embedded Perl. It is therefore impossible to set a protocol value of &`d`&
 or &`s`& using this option (but that does not seem a real limitation).

+Repeated use of this option is not supported.

 
 .vitem &%-q%&
 .oindex "&%-q%&"
 
 .vitem &%-q%&
 .oindex "&%-q%&"


@@ -9963,7 +9974,7 @@ a regular expression, and a substitution string. For example:
 ${sg{abcdefabcdef}{abc}{xyz}}
 .endd
 yields &"xyzdefxyzdef"&. Because all three arguments are expanded before use,
 ${sg{abcdefabcdef}{abc}{xyz}}
 .endd
 yields &"xyzdefxyzdef"&. Because all three arguments are expanded before use,

-if any $ or \ characters are required in the regular expression or in the
+if any $, } or \ characters are required in the regular expression or in the

 substitution string, they have to be escaped. For example:
 .code
 ${sg{abcdef}{^(...)(...)\$}{\$2\$1}}
 substitution string, they have to be escaped. For example:
 .code
 ${sg{abcdef}{^(...)(...)\$}{\$2\$1}}


@@ -10114,7 +10125,15 @@ character. For example:
 .code
 ${addresses:>& Chief <ceo@up.stairs>, sec@base.ment (dogsbody)}
 .endd
 .code
 ${addresses:>& Chief <ceo@up.stairs>, sec@base.ment (dogsbody)}
 .endd

-expands to &`ceo@up.stairs&&sec@base.ment`&. Compare the &*address*& (singular)
+expands to &`ceo@up.stairs&&sec@base.ment`&. The string is expanded
+first, so if the expanded string starts with >, it may change the output
+separator unintentionally. This can be avoided by setting the output
+separator explicitly:
+.code
+${addresses:>:$h_from:}
+.endd
+
+Compare the &*address*& (singular)

 expansion item, which extracts the working address from a single RFC2822
 address. See the &*filter*&, &*map*&, and &*reduce*& items for ways of
 processing lists.
 expansion item, which extracts the working address from a single RFC2822
 address. See the &*filter*&, &*map*&, and &*reduce*& items for ways of
 processing lists.


@@ -11646,8 +11665,11 @@ contain the trailing slash. If &$config_file$& does not contain a slash,
 .vindex "&$config_file$&"
 The name of the main configuration file Exim is using.
 
 .vindex "&$config_file$&"
 The name of the main configuration file Exim is using.
 

+.vitem &$dkim_verify_status$& &&&
+Results of DKIM verification.
+For details see chapter &<<CHAPdkim>>&.
+

 .vitem &$dkim_cur_signer$& &&&
 .vitem &$dkim_cur_signer$& &&&

-       &$dkim_verify_status$& &&&

        &$dkim_verify_reason$& &&&
        &$dkim_domain$& &&&
        &$dkim_identity$& &&&
        &$dkim_verify_reason$& &&&
        &$dkim_domain$& &&&
        &$dkim_identity$& &&&


@@ -12792,6 +12814,15 @@ argument, that is, the text that follows the command name, with leading white
 space removed. Following the introduction of &$smtp_command$&, this variable is
 somewhat redundant, but is retained for backwards compatibility.
 
 space removed. Following the introduction of &$smtp_command$&, this variable is
 somewhat redundant, but is retained for backwards compatibility.
 

+.new
+.vitem &$smtp_command_history$&
+.cindex SMTP "command history"
+.vindex "&$smtp_command_history$&"
+A comma-separated list (with no whitespace) of the most-recent SMTP commands
+received, in time-order left to right.  Only a limited number of commands
+are remembered.
+.wen
+

 .vitem &$smtp_count_at_connection_start$&
 .vindex "&$smtp_count_at_connection_start$&"
 This variable is set greater than zero only in processes spawned by the Exim
 .vitem &$smtp_count_at_connection_start$&
 .vindex "&$smtp_count_at_connection_start$&"
 This variable is set greater than zero only in processes spawned by the Exim


@@ -12878,6 +12909,11 @@ It is only useful as the argument of a
 &%certextract%& expansion item, &%md5%&, &%sha1%& or &%sha256%& operator,
 or a &%def%& condition.
 
 &%certextract%& expansion item, &%md5%&, &%sha1%& or &%sha256%& operator,
 or a &%def%& condition.
 

+.new
+&*Note*&: Under current versions of OpenSSL, when a list of more than one
+file is used for &%tls_certificate%&, this variable is not reliable.
+.wen
+

 .vitem &$tls_in_peercert$&
 .vindex "&$tls_in_peercert$&"
 This variable refers to the certificate presented by the peer of an
 .vitem &$tls_in_peercert$&
 .vindex "&$tls_in_peercert$&"
 This variable refers to the certificate presented by the peer of an


@@ -17079,11 +17115,15 @@ using the &%tls_certificate%& option.  If TLS support for incoming connections
 is not required the &%tls_advertise_hosts%& option should be set empty.
 
 
 is not required the &%tls_advertise_hosts%& option should be set empty.
 
 

-.option tls_certificate main string&!! unset
+.option tls_certificate main string list&!! unset

 .cindex "TLS" "server certificate; location of"
 .cindex "certificate" "server, location of"
 .cindex "TLS" "server certificate; location of"
 .cindex "certificate" "server, location of"

-The value of this option is expanded, and must then be the absolute path to a
-file which contains the server's certificates. The server's private key is also
+.new
+The value of this option is expanded, and must then be a list of absolute paths to
+files which contains the server's certificates.  Commonly only one file is
+needed.
+.wen
+The server's private key is also

 assumed to be in this file if &%tls_privatekey%& is unset. See chapter
 &<<CHAPTLS>>& for further details.
 
 assumed to be in this file if &%tls_privatekey%& is unset. See chapter
 &<<CHAPTLS>>& for further details.
 


@@ -17092,6 +17132,16 @@ receiving incoming messages as a server. If you want to supply certificates for
 use when sending messages as a client, you must set the &%tls_certificate%&
 option in the relevant &(smtp)& transport.
 
 use when sending messages as a client, you must set the &%tls_certificate%&
 option in the relevant &(smtp)& transport.
 

+.new
+&*Note*&: If you use filenames based on IP addresses, change the list
+separator in the usual way to avoid confusion under IPv6.
+
+&*Note*&: Under current versions of OpenSSL, when a list of more than one
+file is used, the &$tls_in_ourcert$& veriable is unreliable.
+
+&*Note*&: OCSP stapling is not usable when a list of more than one file is used.
+.wen
+

 If the option contains &$tls_out_sni$& and Exim is built against OpenSSL, then
 if the OpenSSL build supports TLS extensions and the TLS client sends the
 Server Name Indication extension, then this option and others documented in
 If the option contains &$tls_out_sni$& and Exim is built against OpenSSL, then
 if the OpenSSL build supports TLS extensions and the TLS client sends the
 Server Name Indication extension, then this option and others documented in


@@ -17231,6 +17281,11 @@ Certificate Authority.
 
 Usable for GnuTLS 3.4.4 or 3.3.17 or OpenSSL 1.1.0 (or later).
 
 
 Usable for GnuTLS 3.4.4 or 3.3.17 or OpenSSL 1.1.0 (or later).
 

+.new
+&*Note*&: There is currently no support for multiple OCSP proofs to match the
+multiple certificates facility.
+.wen
+

 
 .option tls_on_connect_ports main "string list" unset
 .cindex SSMTP
 
 .option tls_on_connect_ports main "string list" unset
 .cindex SSMTP


@@ -17242,10 +17297,13 @@ further details, see section &<<SECTsupobssmt>>&.
 
 
 
 
 
 

-.option tls_privatekey main string&!! unset
+.option tls_privatekey main string list&!! unset

 .cindex "TLS" "server private key; location of"
 .cindex "TLS" "server private key; location of"

-The value of this option is expanded, and must then be the absolute path to a
-file which contains the server's private key. If this option is unset, or if
+.new
+The value of this option is expanded, and must then be a list of absolute paths to
+files which contains the server's private keys.
+.wen
+If this option is unset, or if

 the expansion is forced to fail, or the result is an empty string, the private
 key is assumed to be in the same file as the server's certificates. See chapter
 &<<CHAPTLS>>& for further details.
 the expansion is forced to fail, or the result is an empty string, the private
 key is assumed to be in the same file as the server's certificates. See chapter
 &<<CHAPTLS>>& for further details.


@@ -19468,6 +19526,10 @@ instead of TRY_AGAIN. That is why the default action is to try a DNS
 lookup first. Only if that gives a definite &"no such host"& is the local
 function called.
 
 lookup first. Only if that gives a definite &"no such host"& is the local
 function called.
 

+&*Compatibility*&: From Exim 4.85 until fixed for 4.90, there was an
+inadvertent constraint that a transport name as an option had to be the last
+option specified.
+

 
 
 If no IP address for a host can be found, what happens is controlled by the
 
 
 If no IP address for a host can be found, what happens is controlled by the


@@ -22127,10 +22189,14 @@ the obvious value which users understand most easily.
 
 The value of the option is expanded, and must then be a numerical value
 (decimal point allowed), optionally followed by one of the letters K, M, or G,
 
 The value of the option is expanded, and must then be a numerical value
 (decimal point allowed), optionally followed by one of the letters K, M, or G,

-for kilobytes, megabytes, or gigabytes. If Exim is running on a system with
+for kilobytes, megabytes, or gigabytes, optionally followed by a slash
+and further option modifiers. If Exim is running on a system with

 large file support (Linux and FreeBSD have this), mailboxes larger than 2G can
 be handled.
 
 large file support (Linux and FreeBSD have this), mailboxes larger than 2G can
 be handled.
 

+The option modifier &%no_check%& can be used to force delivery even if the over
+quota condition is met. The quota gets updated as usual.
+

 &*Note*&: A value of zero is interpreted as &"no quota"&.
 
 The expansion happens while Exim is running as root, before it changes uid for
 &*Note*&: A value of zero is interpreted as &"no quota"&.
 
 The expansion happens while Exim is running as root, before it changes uid for


@@ -22165,6 +22231,8 @@ can only be used if &%quota%& is also set. The value is expanded; an expansion
 failure causes delivery to be deferred. A value of zero is interpreted as
 &"no quota"&.
 
 failure causes delivery to be deferred. A value of zero is interpreted as
 &"no quota"&.
 

+The option modifier &%no_check%& can be used to force delivery even if the over
+quota condition is met. The quota gets updated as usual.

 
 .option quota_is_inclusive appendfile boolean true
 See &%quota%& above.
 
 .option quota_is_inclusive appendfile boolean true
 See &%quota%& above.


@@ -23775,7 +23843,9 @@ of the message. Its value must not be zero. See also &%final_timeout%&.
 .option dkim_private_key smtp string&!! unset
 .option dkim_canon smtp string&!! unset
 .option dkim_strict smtp string&!! unset
 .option dkim_private_key smtp string&!! unset
 .option dkim_canon smtp string&!! unset
 .option dkim_strict smtp string&!! unset

-.option dkim_sign_headers smtp string&!! unset
+.option dkim_sign_headers smtp string&!! "per RFC"
+.option dkim_hash smtp string&!! sha256
+.option dkim_identity smtp string&!! unset

 DKIM signing options.  For details see section &<<SECDKIMSIGN>>&.
 
 
 DKIM signing options.  For details see section &<<SECDKIMSIGN>>&.
 
 


@@ -24114,7 +24184,7 @@ This option provides a list of servers to which, provided they announce
 CHUNKING support, Exim will attempt to use BDAT commands rather than DATA.
 BDAT will not be used in conjunction with a transport filter.
 
 CHUNKING support, Exim will attempt to use BDAT commands rather than DATA.
 BDAT will not be used in conjunction with a transport filter.
 

-.option hosts_try_fastopen smtp "host list!!" unset
+.option hosts_try_fastopen smtp "host list&!!" unset

 .cindex "fast open, TCP" "enabling, in client"
 .cindex "TCP Fast Open" "enabling, in client"
 .cindex "RFC 7413" "TCP Fast Open"
 .cindex "fast open, TCP" "enabling, in client"
 .cindex "TCP Fast Open" "enabling, in client"
 .cindex "RFC 7413" "TCP Fast Open"


@@ -24130,6 +24200,9 @@ as the initiator must present a cookie in the SYN segment.
 
 On (at least some) current Linux distributions the facility must be enabled
 in the kernel by the sysadmin before the support is usable.
 
 On (at least some) current Linux distributions the facility must be enabled
 in the kernel by the sysadmin before the support is usable.

+There is no option for control of the server side; if the system supports
+it it is always enebled.  Note that legthy operations in the connect ACL,
+such as DNSBL lookups, will still delay the emission of the SMTP banner.

 
 .option hosts_try_prdr smtp "host list&!!" *
 .cindex "PRDR" "enabling, optional in client"
 
 .option hosts_try_prdr smtp "host list&!!" *
 .cindex "PRDR" "enabling, optional in client"


@@ -27072,6 +27145,11 @@ When using OpenSSL, this option is ignored.
 (If an API is found to let OpenSSL be configured in this way,
 let the Exim Maintainers know and we'll likely use it).
 .next
 (If an API is found to let OpenSSL be configured in this way,
 let the Exim Maintainers know and we'll likely use it).
 .next

+.new
+With GnuTLS, if an explicit list is used for the &%tls_privatekey%& main option
+main option, it must be ordered to match the &%tls_certificate%& list.
+.wen
+.next

 Some other recently added features may only be available in one or the other.
 This should be documented with the feature.  If the documentation does not
 explicitly state that the feature is infeasible in the other TLS
 Some other recently added features may only be available in one or the other.
 This should be documented with the feature.  If the documentation does not
 explicitly state that the feature is infeasible in the other TLS


@@ -27227,6 +27305,12 @@ tls_require_ciphers = ${if =={$received_port}{25}\
                            {HIGH:!MD5:!SHA1}}
 .endd
 
                            {HIGH:!MD5:!SHA1}}
 .endd
 

+.new
+This example will prefer ECDSA-authenticated ciphers over RSA ones:
+.code
+tls_require_ciphers = ECDSA:RSA:!COMPLEMENTOFDEFAULT
+.endd
+.wen

 
 
 .section "Requiring specific ciphers or other parameters in GnuTLS" &&&
 
 
 .section "Requiring specific ciphers or other parameters in GnuTLS" &&&


@@ -27315,8 +27399,7 @@ from someone able to intercept the communication.
 
 Further protection requires some further configuration at the server end.
 
 
 Further protection requires some further configuration at the server end.
 

-It is rumoured that all existing clients that support TLS/SSL use RSA
-encryption. To make this work you need to set, in the server,
+To make TLS work you need to set, in the server,

 .code
 tls_certificate = /some/file/name
 tls_privatekey = /some/file/name
 .code
 tls_certificate = /some/file/name
 tls_privatekey = /some/file/name


@@ -27335,6 +27418,15 @@ is assumed to be the case. The certificate file may also contain intermediate
 certificates that need to be sent to the client to enable it to authenticate
 the server's certificate.
 
 certificates that need to be sent to the client to enable it to authenticate
 the server's certificate.
 

+.new
+For dual-stack (eg. RSA and ECDSA) configurations, these options can be
+colon-separated lists of file paths.  Ciphers using given authentication
+algorithms require the presence of a suitable certificate to supply the
+public-key.  The server selects among the certificates to present to the
+client depending on the selected cipher, hence the priority ordering for
+ciphers will affect which certificate is used.
+.wen
+

 If you do not understand about certificates and keys, please try to find a
 source of this background information, which is not Exim-specific. (There are a
 few comments below in section &<<SECTcerandall>>&.)
 If you do not understand about certificates and keys, please try to find a
 source of this background information, which is not Exim-specific. (There are a
 few comments below in section &<<SECTcerandall>>&.)


@@ -27568,11 +27660,10 @@ if it requests it. If the server is Exim, it will request a certificate only if
 
 If the &%tls_verify_certificates%& option is set on the &(smtp)& transport, it
 specifies a collection of expected server certificates.
 
 If the &%tls_verify_certificates%& option is set on the &(smtp)& transport, it
 specifies a collection of expected server certificates.

-These may be the system default set (depending on library version),
-a file or,
-depending on library version, a directory,
-must name a file or,
-for OpenSSL only (not GnuTLS), a directory.
+These may be
+the system default set (depending on library version),
+a file,
+or (depending on library version) a directory.

 The client verifies the server's certificate
 against this collection, taking into account any revoked certificates that are
 in the list defined by &%tls_crl%&.
 The client verifies the server's certificate
 against this collection, taking into account any revoked certificates that are
 in the list defined by &%tls_crl%&.


@@ -28956,6 +29047,7 @@ This modifier puts a value into one of the ACL variables (see section
 
 
 .vitem &*udpsend*&&~=&~<&'parameters'&>
 
 
 .vitem &*udpsend*&&~=&~<&'parameters'&>

+.cindex "UDP communications"

 This modifier sends a UDP packet, for purposes such as statistics
 collection or behaviour monitoring. The parameters are expanded, and
 the result of the expansion must be a colon-separated list consisting
 This modifier sends a UDP packet, for purposes such as statistics
 collection or behaviour monitoring. The parameters are expanded, and
 the result of the expansion must be a colon-separated list consisting


@@ -31244,6 +31336,7 @@ address and some time-based randomizing information. The &%prvs%& expansion
 item creates a signed address, and the &%prvscheck%& expansion item checks one.
 The syntax of these expansion items is described in section
 &<<SECTexpansionitems>>&.
 item creates a signed address, and the &%prvscheck%& expansion item checks one.
 The syntax of these expansion items is described in section
 &<<SECTexpansionitems>>&.

+The validity period on signed addresses is seven days.

 
 As an example, suppose the secret per-address keys are stored in an MySQL
 database. A query to look up the key for an address could be defined as a macro
 
 As an example, suppose the secret per-address keys are stored in an MySQL
 database. A query to look up the key for an address could be defined as a macro


@@ -31710,10 +31803,10 @@ av_scanner = sock:127.0.0.1 6001:%s:(SPAM|VIRUS):(.*)$
 .new
 Note that surrounding whitespace is stripped from each option, meaning
 there is no way to specify a trailing newline.
 .new
 Note that surrounding whitespace is stripped from each option, meaning
 there is no way to specify a trailing newline.

+The socket specifier and both regular-expressions are required.
+Default for the commandline is &_%s\n_& (note this does have a trailing newline);
+specify an empty element to get this.

 .wen
 .wen

-Default for the socket specifier is &_/tmp/malware.sock_&.
-Default for the commandline is &_%s\n_& (note this does have a trailing newline).
-Both regular-expressions are required.

 
 .vitem &%sophie%&
 .cindex "virus scanners" "Sophos and Sophie"
 
 .vitem &%sophie%&
 .cindex "virus scanners" "Sophos and Sophie"


@@ -36017,6 +36110,7 @@ the following table:
 &`SNI `&        server name indication from TLS client hello
 &`ST  `&        shadow transport name
 &`T   `&        on &`<=`& lines: message subject (topic)
 &`SNI `&        server name indication from TLS client hello
 &`ST  `&        shadow transport name
 &`T   `&        on &`<=`& lines: message subject (topic)

+&`TFO `&        connection took advantage of TCP Fast Open

 &`    `&        on &`=>`& &`**`& and &`==`& lines: transport name
 &`U   `&        local user or RFC 1413 identity
 &`X   `&        TLS cipher suite
 &`    `&        on &`=>`& &`**`& and &`==`& lines: transport name
 &`U   `&        local user or RFC 1413 identity
 &`X   `&        TLS cipher suite


@@ -36098,6 +36192,7 @@ selection marked by asterisks:
 &` incoming_interface         `&  local interface on <= and => lines
 &` incoming_port              `&  remote port on <= lines
 &`*lost_incoming_connection   `&  as it says (includes timeouts)
 &` incoming_interface         `&  local interface on <= and => lines
 &` incoming_port              `&  remote port on <= lines
 &`*lost_incoming_connection   `&  as it says (includes timeouts)

+&` millisec                   `&  millisecond timestamps and QT,DT,D times

 &` outgoing_interface         `&  local interface on => lines
 &` outgoing_port              `&  add remote port to => lines
 &`*queue_run                  `&  start and end queue runs
 &` outgoing_interface         `&  local interface on => lines
 &` outgoing_port              `&  add remote port to => lines
 &`*queue_run                  `&  start and end queue runs


@@ -36187,6 +36282,8 @@ process is started because &%queue_only%& is set or &%-odq%& was used.
 .cindex "log" "delivery duration"
 &%deliver_time%&: For each delivery, the amount of real time it has taken to
 perform the actual delivery is logged as DT=<&'time'&>, for example, &`DT=1s`&.
 .cindex "log" "delivery duration"
 &%deliver_time%&: For each delivery, the amount of real time it has taken to
 perform the actual delivery is logged as DT=<&'time'&>, for example, &`DT=1s`&.

+If millisecond logging is enabled, short times will be shown with greater
+precision, eg. &`DT=0.304`&.

 .next
 .cindex "log" "message size on delivery"
 .cindex "size" "of message"
 .next
 .cindex "log" "message size on delivery"
 .cindex "size" "of message"


@@ -36262,6 +36359,14 @@ important with the widening use of NAT (see RFC 2505).
 &%lost_incoming_connection%&: A log line is written when an incoming SMTP
 connection is unexpectedly dropped.
 .next
 &%lost_incoming_connection%&: A log line is written when an incoming SMTP
 connection is unexpectedly dropped.
 .next

+.new
+.cindex "log" "millisecond timestamps"
+.cindex millisecond logging
+.cindex timstamps "millisecond, in logs"
+&%millisec%&: Timestamps have a period and three decimal places of finer granularity
+appended to the seconds value.
+.wen
+.next

 .cindex "log" "outgoing interface"
 .cindex "log" "local interface"
 .cindex "log" "local address and port"
 .cindex "log" "outgoing interface"
 .cindex "log" "local interface"
 .cindex "log" "local address and port"


@@ -36300,6 +36405,8 @@ includes reception time as well as the delivery time for the current address.
 This means that it may be longer than the difference between the arrival and
 delivery log line times, because the arrival log line is not written until the
 message has been successfully received.
 This means that it may be longer than the difference between the arrival and
 delivery log line times, because the arrival log line is not written until the
 message has been successfully received.

+If millisecond logging is enabled, short times will be shown with greater
+precision, eg. &`QT=1.578s`&.

 .next
 &%queue_time_overall%&: The amount of time the message has been in the queue on
 the local host is logged as QT=<&'time'&> on &"Completed"& lines, for
 .next
 &%queue_time_overall%&: The amount of time the message has been in the queue on
 the local host is logged as QT=<&'time'&> on &"Completed"& lines, for


@@ -38486,15 +38593,19 @@ After expansion, this can be a list.
 Each element in turn is put into the &%$dkim_domain%& expansion variable
 while expanding the remaining signing options.
 .wen
 Each element in turn is put into the &%$dkim_domain%& expansion variable
 while expanding the remaining signing options.
 .wen

-If it is empty after expansion, DKIM signing is not done.
+If it is empty after expansion, DKIM signing is not done,
+and no error will result even if &%dkim_strict%& is set.

 
 

-.option dkim_selector smtp string&!! unset
+.option dkim_selector smtp string list&!! unset

 This sets the key selector string.
 This sets the key selector string.

-You can use the &%$dkim_domain%& expansion variable to look up a matching selector.
-The result is put in the expansion
+.new
+After expansion, which can use &$dkim_domain$&, this can be a list.
+Each element in turn is put in the expansion

 variable &%$dkim_selector%& which may be used in the &%dkim_private_key%&
 option along with &%$dkim_domain%&.
 variable &%$dkim_selector%& which may be used in the &%dkim_private_key%&
 option along with &%$dkim_domain%&.

-If the option is empty after expansion, DKIM signing is not done.
+.wen
+If the option is empty after expansion, DKIM signing is not done for this domain,
+and no error will result even if &%dkim_strict%& is set.

 
 .option dkim_private_key smtp string&!! unset
 This sets the private key to use.
 
 .option dkim_private_key smtp string&!! unset
 This sets the private key to use.


@@ -38511,7 +38622,19 @@ be "0", "false" or the empty string, in which case the message will not
 be signed. This case will not result in an error, even if &%dkim_strict%&
 is set.
 .endlist
 be signed. This case will not result in an error, even if &%dkim_strict%&
 is set.
 .endlist

-If the option is empty after expansion, DKIM signing is not done.
+
+.new
+.option dkim_hash smtp string&!! sha256
+Can be set alternatively to &"sha1"& to use an alternate hash
+method.  Note that sha1 is now condidered insecure, and deprecated.
+
+.option dkim_identity smtp string&!! unset
+If set after expansion, the value is used to set an "i=" tag in
+the signing header.  The DKIM standards restrict the permissible
+syntax of this optional tag to a mail address, with possibly-empty
+local part, an @, and a domain identical to or subdomain of the "d="
+tag value.  Note that Exim does not check the value.
+.wen

 
 .option dkim_canon smtp string&!! unset
 This option sets the canonicalization method used when signing a message.
 
 .option dkim_canon smtp string&!! unset
 This option sets the canonicalization method used when signing a message.


@@ -38526,11 +38649,28 @@ either "1" or "true", Exim will defer. Otherwise Exim will send the message
 unsigned. You can use the &%$dkim_domain%& and &%$dkim_selector%& expansion
 variables here.
 
 unsigned. You can use the &%$dkim_domain%& and &%$dkim_selector%& expansion
 variables here.
 

-.option dkim_sign_headers smtp string&!! unset
-If set, this option must expand to (or be specified as) a colon-separated
-list of header names. Headers with these names will be included in the message
-signature.
-When unspecified, the header names recommended in RFC4871 will be used.
+.option dkim_sign_headers smtp string&!! "see below"
+If set, this option must expand to a colon-separated
+list of header names.
+.new
+Headers with these names, or the absence or such a header, will be included
+in the message signature.
+When unspecified, the header names listed in RFC4871 will be used,
+whether or not each header is present in the message.
+The default list is available for the expansion in the macro
+"_DKIM_SIGN_HEADERS".
+
+If a name is repeated, multiple headers by that name (or the absence therof)
+will be signed.  The textually later headers in the headers part of the
+message are signed first, if there are multiples.
+
+A name can be prefixed with either an '=' or a '+' character.
+If an '=' prefix is used, all headers that are present with this name
+will be signed.
+If a '+' prefix if used, all headers that are present with this name
+will be signed, and one signtature added for a missing header with the
+name will be appended.
+.wen

 
 
 .section "Verifying DKIM signatures in incoming mail" "SECID514"
 
 
 .section "Verifying DKIM signatures in incoming mail" "SECID514"


@@ -38541,7 +38681,7 @@ Verification of DKIM signatures in SMTP incoming email is implemented via the
 syntactically(!) correct signature in the incoming message.
 A missing ACL definition defaults to accept.
 If any ACL call does not accept, the message is not accepted.
 syntactically(!) correct signature in the incoming message.
 A missing ACL definition defaults to accept.
 If any ACL call does not accept, the message is not accepted.

-If a cutthrough delivery was in progress for the message it is
+If a cutthrough delivery was in progress for the message, that is

 summarily dropped (having wasted the transmission effort).
 
 To evaluate the signature in the ACL a large number of expansion variables
 summarily dropped (having wasted the transmission effort).
 
 To evaluate the signature in the ACL a large number of expansion variables


@@ -38579,6 +38719,11 @@ dkim_verify_signers = $sender_address_domain:$dkim_signers
 If a domain or identity is listed several times in the (expanded) value of
 &%dkim_verify_signers%&, the ACL is only called once for that domain or identity.
 
 If a domain or identity is listed several times in the (expanded) value of
 &%dkim_verify_signers%&, the ACL is only called once for that domain or identity.
 

+.new
+If multiple signatures match a domain (or identity), the ACL is called once
+for each matching signature.
+.wen
+

 
 Inside the &%acl_smtp_dkim%&, the following expansion variables are
 available (from most to least important):
 
 Inside the &%acl_smtp_dkim%&, the following expansion variables are
 available (from most to least important):


@@ -38591,7 +38736,8 @@ an identity. This is one of the list items from the expanded main option
 &%dkim_verify_signers%& (see above).
 
 .vitem &%$dkim_verify_status%&
 &%dkim_verify_signers%& (see above).
 
 .vitem &%$dkim_verify_status%&

-A string describing the general status of the signature. One of
+Within the DKIM ACL,
+a string describing the general status of the signature. One of

 .ilist
 &%none%&: There is no signature in the message for the current domain or
 identity (as reflected by &%$dkim_cur_signer%&).
 .ilist
 &%none%&: There is no signature in the message for the current domain or
 identity (as reflected by &%$dkim_cur_signer%&).


@@ -38605,6 +38751,22 @@ available in &%$dkim_verify_reason%&.
 &%pass%&: The signature passed verification. It is valid.
 .endlist
 
 &%pass%&: The signature passed verification. It is valid.
 .endlist
 

+.new
+This variable can be overwritten using an ACL 'set' modifier.
+This might, for instance, be done to enforce a policy restriction on
+hash-method or key-size:
+.code
+  warn condition =     ${if eq {$dkim_algo}{rsa-sha1}}
+       condition =     ${if eq {$dkim_verify_status}{pass}}
+       logwrite =      NOTE: forcing dkim verify fail (was pass)
+       set dkim_verify_status = fail
+       set dkim_verify_reason = hash too weak
+.endd
+
+After all the DKIM ACL runs have completed, the value becomes a
+colon-separated list of the values after each run.
+.wen
+

 .vitem &%$dkim_verify_reason%&
 A string giving a little bit more detail when &%$dkim_verify_status%& is either
 "fail" or "invalid". One of
 .vitem &%$dkim_verify_reason%&
 A string giving a little bit more detail when &%$dkim_verify_status%& is either
 "fail" or "invalid". One of


@@ -38625,6 +38787,10 @@ re-written or otherwise changed in a way which is incompatible with
 DKIM verification. It may of course also mean that the signature is forged.
 .endlist
 
 DKIM verification. It may of course also mean that the signature is forged.
 .endlist
 

+.new
+This variable can be overwritten using an ACL 'set' modifier.
+.wen
+

 .vitem &%$dkim_domain%&
 The signing domain. IMPORTANT: This variable is only populated if there is
 an actual signature in the message for the current domain or identity (as
 .vitem &%$dkim_domain%&
 The signing domain. IMPORTANT: This variable is only populated if there is
 an actual signature in the message for the current domain or identity (as