X-Git-Url: https://git.exim.org/users/jgh/exim.git/blobdiff_plain/fa7b17bdbc8c055c475a50791627cd75d257f4f3..c5b0340697326238b0e2afd9d341185077d60d35:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index a073730c6..63db8ef70 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -2528,6 +2528,8 @@ use of Exim's filtering capabilities, you should make the document entitled If you are already running Exim on your host, building and installing a new version automatically makes it available to MUAs, or any other programs that call the MTA directly. However, if you are running an Exim daemon, you do need +.cindex restart "on HUP signal" +.cindex signal "HUP, to restart" to send it a HUP signal, to make it re-execute itself, and thereby pick up the new binary. You do not need to stop processing mail in order to install a new version of Exim. The install script does not modify an existing runtime @@ -2766,9 +2768,12 @@ used to specify a path on the command line if a pid file is required. The SIGHUP signal .cindex "SIGHUP" +.cindex restart "on HUP signal" +.cindex signal "HUP, to restart" .cindex "daemon" "restarting" .cindex signal "to reload configuration" .cindex daemon "reload configuration" +.cindex reload configuration can be used to cause the daemon to re-execute itself. This should be done whenever Exim's configuration file, or any file that is incorporated into it by means of the &%.include%& facility, is changed, and also whenever a new version @@ -9214,7 +9219,13 @@ dependent upon the option for which a value is sought; in this documentation, options for which string expansion is performed are marked with † after the data type. ACL rules always expand strings. A couple of expansion conditions do not expand some of the brace-delimited branches, for security -reasons. +reasons, +.new +.cindex "tainted data" expansion +.cindex expansion "tainted data" +and expansion of data deriving from the sender (&"tainted data"&) +is not permitted. +.wen @@ -14336,7 +14347,9 @@ listed in more than one group. See also the &'Policy controls'& section above. .table2 -.row &%dkim_verify_signers%& "DKIM domain for which DKIM ACL is run" +.row &%dkim_verify_hashes%& "DKIM hash methods accepted for signatures" +.row &%dkim_verify_keytypes%& "DKIM key types accepted for signatures" +.row &%dkim_verify_signers%& "DKIM domains for which DKIM ACL is run" .row &%host_lookup%& "host name looked up for these hosts" .row &%host_lookup_order%& "order of DNS and local name lookups" .row &%recipient_unqualified_hosts%& "may send unqualified recipients" @@ -15081,6 +15094,27 @@ etc. are ignored. If IP literals are enabled, the &(ipliteral)& router declines to handle IPv6 literal addresses. +.new +.option dkim_verify_hashes main "string list" "sha256 : sha512 : sha1" +.cindex DKIM "selecting signature algorithms" +This option gives a list of hash types which are acceptable in signatures, +and an order of processing. +Signatures with algorithms not in the list will be ignored. + +Note that the presence of sha1 violates RFC 8301. +Signatures using the rsa-sha1 are however (as of writing) still common. +The default inclusion of sha1 may be dropped in a future release. + +.option dkim_verify_keytypes main "string list" "ed25519 : rsa" +This option gives a list of key types which are acceptable in signatures, +and an order of processing. +Signatures with algorithms not in the list will be ignored. + +.option dkim_verify_minimal main boolean false +If set to true, verification of signatures will terminate after the +first success. +.wen + .option dkim_verify_signers main "domain list&!!" $dkim_signers .cindex DKIM "controlling calls to the ACL" This option gives a list of DKIM domains for which the DKIM ACL is run. @@ -18873,11 +18907,24 @@ latter kind. This option controls whether the local part is used to form the key for retry hints for addresses that suffer temporary errors while being handled by this -router. The default value is true for any router that has &%check_local_user%& +.new +router. The default value is true for any router that has any of +&%check_local_user%&, +&%local_parts%&, +&%condition%&, +&%local_part_prefix%&, +&%local_part_suffix%&, +&%senders%& or +&%require_files%& +.wen set, and false otherwise. Note that this option does not apply to hints keys for transport delays; they are controlled by a generic transport option of the same name. +Failing to set this option when it is needed +(because a remote router handles only some of the local-parts for a domain) +can result in incorrect error messages being generated. + The setting of &%retry_use_local_part%& applies only to the router on which it appears. If the router generates child addresses, they are routed independently; this setting does not become attached to them. @@ -19007,14 +19054,19 @@ matters. .new -.option set routers string unset +.option set routers "string list" unset .cindex router variables -This option may be used multiple times on a router. -Each string given must be of the form $"name = value"$ +This option may be used multiple times on a router; +because of this the list aspect is mostly irrelevant. +The list separator is a semicolon but can be changed in the +usual way. + +Each list-element given must be of the form $"name = value"$ and the names used must start with the string &"r_"&. -Strings are accumulated for each router which is run. +Values containing a list-separator should have them doubled. When a router runs, the strings are evaluated in order, -to create variables. +to create variables which are added to the set associated with +the address. The variable is set with the expansion of the value. The variables can be used by the router options (not including any preconditions) @@ -22807,6 +22859,15 @@ sometimes add other information onto the ends of message filenames. Section &<>& contains further information. +.new +This option should not be used when other message-handling software +may duplicate messages by making hardlinks to the files. When that is done Exim +will count the message size once for each filename, in contrast with the actual +disk usage. When the option is not set, calculating total usage requires +a system-call per file to get the size; the number of links is then available also +as is used to adjust the effective size. +.wen + .option quota_warn_message appendfile string&!! "see below" See below for the use of this option. If it is not set when @@ -28472,6 +28533,13 @@ transport provide the client with a certificate, which is passed to the server if it requests it. If the server is Exim, it will request a certificate only if &%tls_verify_hosts%& or &%tls_try_verify_hosts%& matches the client. +.new +Do not use a certificate which has the OCSP-must-staple extension, +for client use (they are usable for server use). +As TLS has no means for the client to staple before TLS 1.3 it will result +in failed connections. +.wen + If the &%tls_verify_certificates%& option is set on the &(smtp)& transport, it specifies a collection of expected server certificates. These may be @@ -39526,6 +39594,11 @@ was received from the client, this records the Distinguished Name from that certificate. .endlist +.new +Any of the above may have an extra hyphen prepended, to indicate the the +corresponding data is untrusted. +.wen + Following the options there is a list of those addresses to which the message is not to be delivered. This set of addresses is initialized from the command line when the &%-t%& option is used and &%extract_addresses_remove_arguments%& @@ -39872,15 +39945,28 @@ RFC 6376 lists these tags as RECOMMENDED. Verification of DKIM signatures in SMTP incoming email is done for all messages for which an ACL control &%dkim_disable_verify%& has not been set. +.new +.cindex DKIM "selecting signature algorithms" +Individual classes of signature algorithm can be ignored by changing +the main options &%dkim_verify_hashes%& or &%dkim_verify_keytypes%&. +The &%dkim_verify_minimal%& option can be set to cease verification +processing for a message once the first passing signature is found. +.wen + .cindex authentication "expansion item" Performing verification sets up information used by the &$authresults$& expansion item. -The results of that verification are then made available to the +.new +For most purposes the default option settings suffice and the remainder +of this section can be ignored. +.wen + +The results of verification are made available to the &%acl_smtp_dkim%& ACL, which can examine and modify them. -By default, this ACL is called once for each -syntactically(!) correct signature in the incoming message. A missing ACL definition defaults to accept. +By default, the ACL is called once for each +syntactically(!) correct signature in the incoming message. If any ACL call does not accept, the message is not accepted. If a cutthrough delivery was in progress for the message, that is summarily dropped (having wasted the transmission effort). @@ -39891,11 +39977,11 @@ containing the signature status and its details are set up during the runtime of the ACL. Calling the ACL only for existing signatures is not sufficient to build -more advanced policies. For that reason, the global option -&%dkim_verify_signers%&, and a global expansion variable +more advanced policies. For that reason, the main option +&%dkim_verify_signers%&, and an expansion variable &%$dkim_signers%& exist. -The global option &%dkim_verify_signers%& can be set to a colon-separated +The main option &%dkim_verify_signers%& can be set to a colon-separated list of DKIM domains or identities for which the ACL &%acl_smtp_dkim%& is called. It is expanded when the message has been received. At this point, the expansion variable &%$dkim_signers%& already contains a colon-separated @@ -39933,7 +40019,7 @@ If multiple signatures match a domain (or identity), the ACL is called once for each matching signature. -Inside the &%acl_smtp_dkim%&, the following expansion variables are +Inside the DKIM ACL, the following expansion variables are available (from most to least important): @@ -40027,8 +40113,12 @@ DKIM signatures identified as having been signed with historic algorithms (currently, rsa-sha1) have permanently failed evaluation .endd -To enforce this you must have a DKIM ACL which checks this variable -and overwrites the &$dkim_verify_status$& variable as discussed above. +To enforce this you must either have a DKIM ACL which checks this variable +and overwrites the &$dkim_verify_status$& variable as discussed above, +.new +or have set the main option &%dkim_verify_hashes%& to exclude +processing of such signatures. +.wen .vitem &%$dkim_canon_body%& The body canonicalization method. One of 'relaxed' or 'simple'. @@ -40295,7 +40385,11 @@ would relax host matching rules to a broader network range. .cindex SPF "lookup expansion" .cindex lookup spf A lookup expansion is also available. It takes an email -address as the key and an IP address as the database: +address as the key and an IP address +.new +(v4 or v6) +.wen +as the database: .code ${lookup {username@domain} spf {ip.ip.ip.ip}} @@ -40303,7 +40397,6 @@ address as the key and an IP address as the database: The lookup will return the same result strings as can appear in &$spf_result$& (pass,fail,softfail,neutral,none,err_perm,err_temp). -Currently, only IPv4 addresses are supported.