X-Git-Url: https://git.exim.org/users/jgh/exim.git/blobdiff_plain/b4f579d134197249b448cb5d8abf801ba4c729bb..9300a61f79604940f3b0c6fbc4b72f1a3c882caf:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 5463cc1a5..51c4e0160 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 @@ -6104,6 +6109,9 @@ dnslookup: domains = ! +local_domains transport = remote_smtp ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8 +.ifdef _HAVE_DNSSEC + dnssec_request_domains = * +.endif no_more .endd The &%domains%& option behaves as per smarthost, above. @@ -6255,7 +6263,6 @@ remote_smtp: driver = smtp message_size_limit = ${if > {$max_received_linelength}{998} {1}{0}} .ifdef _HAVE_DANE - dnssec_request_domains = * hosts_try_dane = * .endif .ifdef _HAVE_PRDR @@ -6266,7 +6273,7 @@ This transport is used for delivering messages over SMTP connections. The list of remote hosts comes from the router. The &%message_size_limit%& usage is a hack to avoid sending on messages 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; +to use DANE for delivery; see section &<>& for more details. The &%hosts_try_prdr%& option enables an efficiency SMTP option. It is @@ -9214,7 +9221,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 +14349,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 +15096,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. @@ -16007,6 +16043,10 @@ when Exim is entered, so it can, for example, contain a reference to the host name. If no specific path is set for the log files at compile or runtime, or if the option is unset at runtime (i.e. &`log_file_path = `&) they are written in a sub-directory called &_log_& in Exim's spool directory. +.new +A path must start with a slash. +To send to syslog, use the word &"syslog"&. +.wen Chapter &<>& contains further details about Exim's logging, and section &<>& describes how the contents of &%log_file_path%& are used. If this string is fixed at your installation (contains no expansion @@ -16864,11 +16904,11 @@ it qualifies them only if the message came from a host that matches &%sender_unqualified_hosts%&, or if the message was submitted locally (not using TCP/IP), and the &%-bnq%& option was not set. -.option set_environment main "string list" empty +.option add_environment main "string list" empty .cindex "environment" -This option allows to set individual environment variables that the +This option allows to add individual environment variables that the currently linked libraries and programs in child processes use. The -default list is empty, +default list is empty. .option slow_lookup_log main integer 0 @@ -17610,8 +17650,8 @@ is not required the &%tls_advertise_hosts%& option should be set empty. .cindex "TLS" "server certificate; location of" .cindex "certificate" "server, location of" 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. +files which contain the server's certificates (in PEM format). +Commonly only one file is needed. The server's private key is also assumed to be in this file if &%tls_privatekey%& is unset. See chapter &<>& for further details. @@ -17780,6 +17820,7 @@ For GnuTLS 3.5.6 or later the expanded value of this option can be a list of files, to match a list given for the &%tls_certificate%& option. The ordering of the two lists must match. +The file(s) should be in DER format .option tls_on_connect_ports main "string list" unset .cindex SSMTP @@ -18873,11 +18914,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. @@ -19011,13 +19065,12 @@ matters. .cindex router variables This option may be used multiple times on a router; because of this the list aspect is mostly irrelevant. -The list separator is a colon but can be changed in the +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_"&. -Values containing colons should either have them doubled, or -the entire list should be prefixed with a list-separator change. +Values containing a list-separator should have them doubled. When a router runs, the strings are evaluated in order, to create variables which are added to the set associated with the address. @@ -22813,6 +22866,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 @@ -24407,15 +24469,23 @@ of the message. Its value must not be zero. See also &%final_timeout%&. .option dkim_canon smtp string&!! unset +DKIM signing option. For details see section &<>&. .option dkim_domain smtp string list&!! unset +DKIM signing option. For details see section &<>&. .option dkim_hash smtp string&!! sha256 +DKIM signing option. For details see section &<>&. .option dkim_identity smtp string&!! unset +DKIM signing option. For details see section &<>&. .option dkim_private_key smtp string&!! unset +DKIM signing option. For details see section &<>&. .option dkim_selector smtp string&!! unset +DKIM signing option. For details see section &<>&. .option dkim_strict smtp string&!! unset +DKIM signing option. For details see section &<>&. .option dkim_sign_headers smtp string&!! "per RFC" +DKIM signing option. For details see section &<>&. .option dkim_timestamps smtp string&!! unset -DKIM signing options. For details see section &<>&. +DKIM signing option. For details see section &<>&. .option delay_after_cutoff smtp boolean true @@ -24463,8 +24533,9 @@ details. .cindex "security" "MX lookup" .cindex "DNS" "DNSSEC" DNS lookups for domains matching &%dnssec_request_domains%& will be done with -the dnssec request bit set. -This applies to all of the SRV, MX, AAAA, A lookup sequence. +the dnssec request bit set. Setting this transport option is only useful if the +transport overrides or sets the host names. See the &%dnssec_request_domains%& +router option. @@ -24474,9 +24545,9 @@ This applies to all of the SRV, MX, AAAA, A lookup sequence. .cindex "security" "MX lookup" .cindex "DNS" "DNSSEC" DNS lookups for domains matching &%dnssec_require_domains%& will be done with -the dnssec request bit set. Any returns not having the Authenticated Data bit -(AD bit) set will be ignored and logged as a host-lookup failure. -This applies to all of the SRV, MX, AAAA, A lookup sequence. +the dnssec request bit set. Setting this transport option is only +useful if the transport overrides or sets the host names. See the +&%dnssec_require_domains%& router option. @@ -24755,7 +24826,8 @@ TLS session for any host that matches this list. .cindex DANE "requiring for certain servers" If built with DANE support, Exim will require that a DNSSEC-validated TLSA record is present for any host matching the list, -and that a DANE-verified TLS connection is made. +and that a DANE-verified TLS connection is made. See +the &%dnssec_request_domains%& router and transport options. There will be no fallback to in-clear communication. See section &<>&. @@ -24791,11 +24863,11 @@ BDAT will not be used in conjunction with a transport filter. .option hosts_try_dane smtp "host list&!!" * .cindex DANE "transport options" .cindex DANE "attempting for certain servers" -If built with DANE support, Exim will lookup a -TLSA record for any host matching the list. -If found and verified by DNSSEC, -a DANE-verified TLS connection is made to that host; -there will be no fallback to in-clear communication. +If built with DANE support, Exim will require that a DNSSEC-validated +TLSA record is present for any host matching the list, +and that a DANE-verified TLS connection is made. See +the &%dnssec_request_domains%& router and transport options. +There will be no fallback to in-clear communication. See section &<>&. .option hosts_try_fastopen smtp "host list&!!" * @@ -28478,6 +28550,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 @@ -28601,7 +28680,7 @@ Great care should be taken to deal with matters of case, various injection attacks in the string (&`../`& or SQL), and ensuring that a valid filename can always be referenced; it is important to remember that &$tls_in_sni$& is arbitrary unverified data provided prior to authentication. -Further, the initial certificate is loaded before SNI is arrived, so +Further, the initial certificate is loaded before SNI has arrived, so an expansion for &%tls_certificate%& must have a default which is used when &$tls_in_sni$& is empty. @@ -28796,7 +28875,12 @@ Support for client-side operation of DANE can be included at compile time by def in &_Local/Makefile_&. If it has been included, the macro "_HAVE_DANE" will be defined. -The TLSA record for the server may have "certificate usage" of DANE-TA(2) or DANE-EE(3). +A TLSA record consist of 4 fields, the "Certificate Usage", the +"Selector", the "Matching type", and the "Certificate Association Data". +For a detailed description of the TLSA record see +&url(https://tools.ietf.org/html/rfc7671#page-5,RFC 7671). + +The TLSA record for the server may have "Certificate Usage" (1st) field of DANE-TA(2) or DANE-EE(3). These are the "Trust Anchor" and "End Entity" variants. The latter specifies the End Entity directly, i.e. the certificate involved is that of the server (and if only DANE-EE is used then it should be the sole one transmitted during the TLS handshake); @@ -28837,19 +28921,29 @@ If you're not already using a private CA, or it doesn't meet these requirements, then we encourage you to avoid all these issues and use a public CA such as &url(https://letsencrypt.org/,Let's Encrypt) instead. -The TLSA record should have a Selector field of SPKI(1) and a Matching Type field of SHA2-512(2). +The TLSA record should have a "Selector" (2nd) field of SPKI(1) and +a "Matching Type" (3rd) field of SHA2-512(2). -At the time of writing, &url(https://www.huque.com/bin/gen_tlsa) -is useful for quickly generating TLSA records; and commands like +For the "Certificate Authority Data" (4th) field, commands like .code - openssl x509 -in -pubkey -noout /dev/null \ | openssl sha512 \ | awk '{print $2}' .endd -are workable for 4th-field hashes. +are workable to create a hash of the certificate's public key. + +An example TLSA record for DANE-EE(3), SPKI(1), and SHA-512 (2) looks like + +.code + _25._tcp.mail.example.com. TLSA 3 1 2 8BA8A336E... +.endd + +At the time of writing, &url(https://www.huque.com/bin/gen_tlsa) +is useful for quickly generating TLSA records. + For use with the DANE-TA model, server certificates must have a correct name (SubjectName or SubjectAltName). @@ -28883,7 +28977,9 @@ those who use &%hosts_require_ocsp%&, should consider the interaction with DANE For client-side DANE there are three new smtp transport options, &%hosts_try_dane%&, &%hosts_require_dane%& and &%dane_require_tls_ciphers%&. -The require variant will result in failure if the target host is not DNSSEC-secured. +The require variant will result in failure if the target host is not +DNSSEC-secured. To get DNSSEC-secured hostname resolution, use +the &%dnssec_request_domains%& router or transport option. DANE will only be usable if the target host has DNSSEC-secured MX, A and TLSA records. @@ -28913,7 +29009,7 @@ If DANE is requested and useable (see above) the following transport options are If DANE is not usable, whether requested or not, and CA-anchored verification evaluation is wanted, the above variables should be set appropriately. -Currently the &%dnssec_request_domains%& must be active and &%dnssec_require_domains%& is ignored. +Currently the (router or transport options) &%dnssec_request_domains%& must be active and &%dnssec_require_domains%& is ignored. If verification was successful using DANE then the "CV" item in the delivery log line will show as "CV=dane". @@ -30796,7 +30892,9 @@ the next &%local_parts%& test. .cindex "&ACL;" "virus scanning" .cindex "&ACL;" "scanning for viruses" This condition is available only when Exim is compiled with the -content-scanning extension. It causes the incoming message to be scanned for +content-scanning extension +and only after a DATA command. +It causes the incoming message to be scanned for viruses. For details, see chapter &<>&. .vitem &*mime_regex&~=&~*&<&'list&~of&~regular&~expressions'&> @@ -32584,6 +32682,15 @@ It supports a &"generic"& interface to scanners called via the shell, and specialized interfaces for &"daemon"& type virus scanners, which are resident in memory and thus are much faster. +.new +Since message data needs to have arrived, +the condition may be only called in ACL defined by +&%acl_smtp_data%&, +&%acl_smtp_data_prdr%&, +&%acl_smtp_mime%& or +&%acl_smtp_dkim%& +.wen + A timeout of 2 minutes is applied to a scanner call (by default); if it expires then a defer action is taken. @@ -39532,6 +39639,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%& @@ -39878,15 +39990,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). @@ -39897,11 +40022,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 @@ -39939,7 +40064,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): @@ -40033,8 +40158,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'. @@ -40301,7 +40430,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}} @@ -40309,7 +40442,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.