X-Git-Url: https://git.exim.org/users/jgh/exim.git/blobdiff_plain/55e70e76c861b5c45ae93a45d0a5da12aa849999..0d9fa8c0a3e0e3dd140880861a60c3def18f176b:/doc/doc-docbook/spec.xfpt?ds=sidebyside diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 15491c3f1..d08a7a040 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -9213,8 +9213,8 @@ The environment is adjusted by the &%keep_environment%& and .cindex "&%extract%&" "substrings by key" The key and <&'string1'&> are first expanded separately. Leading and trailing white space is removed from the key (but not from any of the strings). The key -must not consist entirely of digits. The expanded <&'string1'&> must be of the -form: +must not be empty and must not consist entirely of digits. +The expanded <&'string1'&> must be of the form: .display <&'key1'&> = <&'value1'&> <&'key2'&> = <&'value2'&> ... .endd @@ -10090,6 +10090,21 @@ Last:user@example.com user@example.com .endd +.new +.vitem &*${base32:*&<&'digits'&>&*}*& +.cindex "&%base32%& expansion item" +.cindex "expansion" "conversion to base 32" +The string must consist entirely of decimal digits. The number is converted to +base 32 and output as a (empty, for zero) string of characters. +Only lowercase letters are used. + +.vitem &*${base32d:*&<&'base-32&~digits'&>&*}*& +.cindex "&%base32d%& expansion item" +.cindex "expansion" "conversion to base 32" +The string must consist entirely of base-32 digits. +The number is converted to decimal and output as a string. +.wen + .vitem &*${base62:*&<&'digits'&>&*}*& .cindex "&%base62%& expansion item" .cindex "expansion" "conversion to base 62" @@ -10514,7 +10529,7 @@ variables or headers inside regular expressions. .cindex "SHA-1 hash" .cindex "expansion" "SHA-1 hashing" .cindex certificate fingerprint -.cindex "&%sha2%& expansion item" +.cindex "&%sha1%& expansion item" The &%sha1%& operator computes the SHA-1 hash value of the string, and returns it as a 40-digit hexadecimal number, in which any letters are in upper case. @@ -10522,16 +10537,38 @@ If the string is a single variable of type certificate, returns the SHA-1 hash fingerprint of the certificate. -.vitem &*${sha256:*&<&'certificate'&>&*}*& +.vitem &*${sha256:*&<&'string'&>&*}*& .cindex "SHA-256 hash" .cindex certificate fingerprint .cindex "expansion" "SHA-256 hashing" .cindex "&%sha256%& expansion item" -The &%sha256%& operator computes the SHA-256 hash fingerprint of the -certificate, +.new +The &%sha256%& operator computes the SHA-256 hash value of the string +and returns +it as a 64-digit hexadecimal number, in which any letters are in upper case. +.wen + +If the string is a single variable of type certificate, +returns the SHA-256 hash fingerprint of the certificate. + + +.new +.vitem &*${sha3:*&<&'string'&>&*}*& &&& + &*${sha3_:*&<&'string'&>&*}*& +.cindex "SHA3 hash" +.cindex "expansion" "SHA3 hashing" +.cindex "&%sha3%& expansion item" +The &%sha3%& operator computes the SHA3-256 hash value of the string and returns it as a 64-digit hexadecimal number, in which any letters are in upper case. -Only arguments which are a single variable of certificate type are supported. + +If a number is appended, separated by an underbar, it specifies +the output length. Values of 224, 256, 384 and 512 are accepted; +with 256 being the default. + +The &%sha3%& expansion item is only supported if Exim has been +compiled with GnuTLS 3.5.0 or later. +.wen .vitem &*${stat:*&<&'string'&>&*}*& @@ -12816,7 +12853,7 @@ When a message is received from a remote host over an encrypted SMTP connection, this variable is set to the cipher suite that was negotiated, for example DES-CBC3-SHA. In other circumstances, in particular, for message received over unencrypted connections, the variable is empty. Testing -&$tls_cipher$& for emptiness is one way of distinguishing between encrypted and +&$tls_in_cipher$& for emptiness is one way of distinguishing between encrypted and non-encrypted connections during ACL processing. The deprecated &$tls_cipher$& variable is the same as &$tls_in_cipher$& during message reception, @@ -15955,7 +15992,7 @@ the daemon's command line. .new .cindex queues named -.condex "named queues" +.cindex "named queues" To set limits for different named queues use an expansion depending on the &$queue_name$& variable. .wen @@ -16975,7 +17012,7 @@ in IKE is assigned number 23. Otherwise, the option must expand to the name used by Exim for any of a number of DH primes specified in RFC 2409, RFC 3526 and RFC 5114. As names, Exim uses -"ike" followed by the number used by IKE, of "default" which corresponds to +"ike" followed by the number used by IKE, or "default" which corresponds to "ike23". The available primes are: @@ -17550,7 +17587,7 @@ This applies to all of the SRV, MX, AAAA, A lookup sequence. .cindex "DNSSEC" "MX lookup" .cindex "security" "MX lookup" .cindex "DNS" "DNSSEC" -DNS lookups for domains matching &%dnssec_request_domains%& will be done with +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. @@ -19851,12 +19888,17 @@ list1: :include:/opt/lists/list1 .endd .next .cindex "address redirection" "to black hole" -Sometimes you want to throw away mail to a particular local part. Making the -&%data%& option expand to an empty string does not work, because that causes -the router to decline. Instead, the alias item +.cindex "delivery" "discard" +.cindex "delivery" "blackhole" .cindex "black hole" .cindex "abandoning mail" -&':blackhole:'& can be used. It does what its name implies. No delivery is +Sometimes you want to throw away mail to a particular local part. Making the +&%data%& option expand to an empty string does not work, because that causes +the router to decline. Instead, the alias item +.code +:blackhole: +.endd +can be used. It does what its name implies. No delivery is done, and no error message is generated. This has the same effect as specifying &_/dev/null_& as a destination, but it can be independently disabled. @@ -20826,7 +20868,7 @@ is forced to fail, no action is taken. Other expansion failures are treated as errors and cause the delivery to be deferred. Unlike most options, &%headers_remove%& can be specified multiple times -for a router; all listed headers are removed. +for a transport; all listed headers are removed. &*Warning*&: Because of the separate expansion of the list items, items that contain a list separator must have it doubled. @@ -23594,7 +23636,7 @@ This applies to all of the SRV, MX, AAAA, A lookup sequence. .cindex "DNSSEC" "MX lookup" .cindex "security" "MX lookup" .cindex "DNS" "DNSSEC" -DNS lookups for domains matching &%dnssec_request_domains%& will be done with +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. @@ -28619,6 +28661,8 @@ effect. .vitem &*queue*&&~=&~<&'text'&> This modifier specifies the use of a named queue for spool files for the message. +It can only be used before the message is received (i.e. not in +the DATA ACL). This could be used, for example, for known high-volume burst sources of traffic, or for quarantine of messages. Separate queue-runner processes will be needed for named queues. @@ -28770,13 +28814,18 @@ with &`-d`&, with the output going to a new logfile, by default called &'debuglog'&. The filename can be adjusted with the &'tag'& option, which may access any variables already defined. The logging may be adjusted with the &'opts'& option, which takes the same values as the &`-d`& command-line -option. Some examples (which depend on variables that don't exist in all +option. +.new +Logging may be stopped, and the file removed, with the &'kill'& option. +.wen +Some examples (which depend on variables that don't exist in all contexts): .code control = debug control = debug/tag=.$sender_host_address control = debug/opts=+expand+acl control = debug/tag=.$message_exim_id/opts=+expand + control = debug/kill .endd @@ -29015,7 +29064,7 @@ any ACL verb, including &%deny%& (though this is potentially useful only in a RCPT ACL). Headers will not be added to the message if the modifier is used in -DATA, MIME or DKIM ACLs for messages delivered by cutthrough routing. +DATA, MIME or DKIM ACLs for a message delivered by cutthrough routing. Leading and trailing newlines are removed from the data for the &%add_header%& modifier; if it then @@ -29116,8 +29165,8 @@ receiving a message). The message must ultimately be accepted for with any ACL verb, including &%deny%&, though this is really not useful for any verb that doesn't result in a delivered message. -Headers will not be removed to the message if the modifier is used in -DATA, MIME or DKIM ACLs for messages delivered by cutthrough routing. +Headers will not be removed from the message if the modifier is used in +DATA, MIME or DKIM ACLs for a message delivered by cutthrough routing. More than one header can be removed at the same time by using a colon separated list of header names. The header matching is case insensitive. Wildcards are @@ -31495,7 +31544,7 @@ condition defers. Unix and TCP socket specifications may be mixed in any order. Each element of the list is a list itself, space-separated by default -and changeable in the usual way. +and changeable in the usual way; take care to not double the separator. For TCP socket specifications a host name or IP (v4 or v6, but subject to list-separator quoting rules) address can be used, @@ -35586,6 +35635,7 @@ the following table: &`CV `& certificate verification status &`D `& duration of &"no mail in SMTP session"& &`DN `& distinguished name from peer certificate +&`DS `& DNSSEC secured lookups &`DT `& on &`=>`& lines: time taken for a delivery &`F `& sender address (on delivery lines) &`H `& host name and IP address @@ -35677,6 +35727,7 @@ selection marked by asterisks: &` deliver_time `& time taken to perform delivery &` delivery_size `& add &`S=`&&'nnn'& to => lines &`*dnslist_defer `& defers of DNS list (aka RBL) lookups +&` dnssec `& DNSSEC secured lookups &`*etrn `& ETRN commands &`*host_lookup_failed `& as it says &` ident_timeout `& timeout for ident connection @@ -35784,6 +35835,14 @@ the &"=>"& line, tagged with S=. &%dnslist_defer%&: A log entry is written if an attempt to look up a host in a DNS black list suffers a temporary error. .next +.cindex log dnssec +.cindex dnssec logging +&%dnssec%&: For message acceptance and (attempted) delivery log lines, when +dns lookups gave secure results a tag of DS is added. +For acceptance this covers the reverse and forward lookups for host name verification. +It does not cover helo-name verification. +For delivery this covers the SRV, MX, A and/or AAAA lookups. +.next .cindex "log" "ETRN commands" .cindex "ETRN" "logging" &%etrn%&: Every valid ETRN command that is received is logged, before the ACL @@ -38019,7 +38078,7 @@ senders). .section "Signing outgoing messages" "SECDKIMSIGN" .cindex "DKIM" "signing" -Signing is implemented by setting private options on the SMTP transport. +Signing is enabled by setting private options on the SMTP transport. These options take (expandable) strings as arguments. .option dkim_domain smtp string&!! unset @@ -38076,7 +38135,7 @@ used. .section "Verifying DKIM signatures in incoming mail" "SECID514" .cindex "DKIM" "verification" -Verification of DKIM signatures in incoming email is implemented via the +Verification of DKIM signatures in SMTP incoming email is implemented via the &%acl_smtp_dkim%& ACL. By default, this ACL is called once for each syntactically(!) correct signature in the incoming message. A missing ACL definition defaults to accept. @@ -38438,7 +38497,7 @@ form of the name. Log lines and Received-by: header lines will acquire a "utf8" prefix on the protocol element, eg. utf8esmtp. -The following expansion operator can be used: +The following expansion operators can be used: .code ${utf8_domain_to_alabel:str} ${utf8_domain_from_alabel:str}