X-Git-Url: https://vcs.fsf.org/?p=exim.git;a=blobdiff_plain;f=doc%2Fdoc-docbook%2Fspec.xfpt;h=d44349c20092edf8000e26485b5eb1b4926f10c7;hp=80d8aef811ca053cc661950c3e5b4b8d390cd721;hb=baf5730b704991a1c5f22770b6220f07b9a855f4;hpb=d2a2c69b7b97d080d63dfb434584d98eb3228332 diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 80d8aef81..d44349c20 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -52,7 +52,7 @@ .set I "    " .macro copyyear -2014 +2015 .endmacro . ///////////////////////////////////////////////////////////////////////////// @@ -5598,6 +5598,13 @@ find that they send unqualified addresses. The two commented-out options: show how you can specify hosts that are permitted to send unqualified sender and recipient addresses, respectively. +The &%log_selector%& option is used to increase the detail of logging +over the default: +.code +log_selector = +smtp_protocol_error +smtp_syntax_error \ + +tls_certificate_verified +.endd + The &%percent_hack_domains%& option is also commented out: .code # percent_hack_domains = @@ -8965,7 +8972,7 @@ The field selectors marked as "RFC4514" above output a Distinguished Name string which is not quite parseable by Exim as a comma-separated tagged list -(the exceptions being elements containin commas). +(the exceptions being elements containing commas). RDN elements of a single type may be selected by a modifier of the type label; if so the expansion result is a list (newline-separated by default). @@ -9031,6 +9038,30 @@ When compiling a function that is to be used in this way with gcc, you need to add &%-shared%& to the gcc command. Also, in the Exim build-time configuration, you must add &%-export-dynamic%& to EXTRALIBS. + +.vitem "&*${env{*&<&'key'&>&*}{*&<&'string1'&>&*}{*&<&'string2'&>&*}}*&" +.cindex "expansion" "extracting value from environment" +.cindex "environment" "value from" +The key is first expanded separately, and leading and trailing white space +removed. +This is then searched for as a name in the environment. +If a variable is found then its value is placed in &$value$& +and <&'string1'&> is expanded, otherwise <&'string2'&> is expanded. + +Instead of {<&'string2'&>} the word &"fail"& (not in curly brackets) can +appear, for example: +.code +${env{USER}{$value} fail } +.endd +This forces an expansion failure (see section &<>&); +{<&'string1'&>} must be present for &"fail"& to be recognized. + +If {<&'string2'&>} is omitted an empty string is substituted on +search failure. +If {<&'string1'&>} is omitted the search result is substituted on +search success. + + .vitem "&*${extract{*&<&'key'&>&*}{*&<&'string1'&>&*}{*&<&'string2'&>&*}&&& {*&<&'string3'&>&*}}*&" .cindex "expansion" "extracting substrings by key" @@ -11318,6 +11349,34 @@ This variable is available when Exim is compiled with the content-scanning extension and the obsolete &%demime%& condition. For details, see section &<>&. +.vitem &$dkim_cur_signer$& &&& + &$dkim_verify_status$& &&& + &$dkim_verify_reason$& &&& + &$dkim_domain$& &&& + &$dkim_identity$& &&& + &$dkim_selector$& &&& + &$dkim_algo$& &&& + &$dkim_canon_body$& &&& + &$dkim_canon_headers$& &&& + &$dkim_copiedheaders$& &&& + &$dkim_bodylength$& &&& + &$dkim_created$& &&& + &$dkim_expires$& &&& + &$dkim_headernames$& &&& + &$dkim_key_testing$& &&& + &$dkim_key_nosubdomains$& &&& + &$dkim_key_srvtype$& &&& + &$dkim_key_granularity$& &&& + &$dkim_key_notes$& +These variables are only available within the DKIM ACL. +For details see chapter &<>&. + +.vitem &$dkim_signers$& +.vindex &$dkim_signers$& +When a message has been received this variable contains +a colon-separated list of signer domains and identities for the message. +For details see chapter &<>&. + .vitem &$dnslist_domain$& &&& &$dnslist_matched$& &&& &$dnslist_text$& &&& @@ -11415,7 +11474,7 @@ This variable contains the numerical value of the Exim user id. .new .vitem &$exim_version$& -.vindex "&$exim_uid$&" +.vindex "&$exim_version$&" This variable contains the version string of the Exim build. The first character is a major version number, currently 4. Then after a dot, the next group of digits is a minor version number. @@ -11681,6 +11740,7 @@ the space value is -1. See also the &%check_log_space%& option. .vindex "&$lookup_dnssec_authenticated$&" This variable is set after a DNS lookup done by a dnsdb lookup expansion, dnslookup router or smtp transport. +.cindex "DNS" "DNSSEC" It will be empty if &(DNSSEC)& was not requested, &"no"& if the result was not labelled as authenticated data and &"yes"& if it was. @@ -12198,6 +12258,14 @@ verification either failed or was not requested. A host name in parentheses is the argument of a HELO or EHLO command. This is omitted if it is identical to the verified host name or to the host's IP address in square brackets. +.new +.vitem &$sender_helo_dnssec$& +.vindex "&$sender_helo_dnssec$&" +This boolean variable is true if a successful HELO verification was +.cindex "DNS" "DNSSEC" +done using DNS information the resolver library stated was authenticatied data. +.wen + .vitem &$sender_helo_name$& .vindex "&$sender_helo_name$&" When a message is received from a remote host that has issued a HELO or EHLO @@ -12223,9 +12291,11 @@ received. It is empty if there was no successful authentication. See also If an attempt to populate &$sender_host_name$& has been made (by reference, &%hosts_lookup%& or otherwise) then this boolean will have been set true if, and only if, the -resolver library states that the reverse DNS was authenticated data. At all +resolver library states that both +the reverse and forward DNS were authenticated data. At all other times, this variable is false. +.cindex "DNS" "DNSSEC" It is likely that you will need to coerce DNSSEC support on in the resolver library, by setting: .code @@ -12235,9 +12305,6 @@ dns_dnssec_ok = 1 Exim does not perform DNSSEC validation itself, instead leaving that to a validating resolver (eg, unbound, or bind with suitable configuration). -Exim does not (currently) check to see if the forward DNS was also secured -with DNSSEC, only the reverse DNS. - If you have changed &%host_lookup_order%& so that &`bydns`& is not the first mechanism in the list, then this variable will be false. @@ -13423,6 +13490,7 @@ 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 &%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" @@ -13631,6 +13699,12 @@ is run for each recipient after an SMTP DATA command has been processed and the message itself has been received, but before the acknowledgment is sent. See chapter &<>& for further details. +.option acl_smtp_dkim main string&!! unset +.cindex DKIM "ACL for" +This option defines the ACL that is run for each DKIM signature +of a received message. +See chapter &<>& for further details. + .option acl_smtp_etrn main string&!! unset .cindex "ETRN" "ACL for" This option defines the ACL that is run when an SMTP ETRN command is @@ -14106,6 +14180,14 @@ etc. are ignored. If IP literals are enabled, the &(ipliteral)& router declines to handle IPv6 literal addresses. +.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. +It is expanded after the message is received; by default it runs +the ACL once for each signature in the message. +See chapter &<>&. + + .option dns_again_means_nonexist main "domain list&!!" unset .cindex "DNS" "&""try again""& response; overriding" DNS lookups give a &"try again"& response for the DNS errors @@ -14537,14 +14619,17 @@ is an IP literal matching the calling address of the host, or matches the host name that Exim obtains by doing a reverse lookup of the calling host address, or .next -when looked up using &[gethostbyname()]& (or &[getipnodebyname()]& when -available) yields the calling host address. +when looked up in DNS yields the calling host address. .endlist However, the EHLO or HELO command is not rejected if any of the checks fail. Processing continues, but the result of the check is remembered, and can be detected later in an ACL by the &`verify = helo`& condition. +If DNS was used for successful verification, the variable +.cindex "DNS" "DNSSEC" +&$helo_verify_dnssec$& records the DNSSEC status of the lookups. + .option helo_verify_hosts main "host list&!!" unset .cindex "HELO verifying" "mandatory" .cindex "EHLO" "verifying, mandatory" @@ -14918,8 +15003,9 @@ section &<>&. This option sets the path which is used to determine the names of Exim's log files, or indicates that logging is to be to syslog, or both. It is expanded 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 run time, they -are written in a sub-directory called &_log_& in Exim's spool directory. +name. If no specific path is set for the log files at compile or run time, +or if the option is unset at run time (i.e. &`log_file_path = `&) +they are written in a sub-directory called &_log_& in Exim's spool directory. 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 @@ -17074,7 +17160,7 @@ This applies to all of the SRV, MX, AAAA, A lookup sequence. .cindex "DNS" "DNSSEC" DNS lookups for domains matching &%dnssec_request_domains%& will be done with the dnssec request bit set. Any returns not having the Authenticated Data bit -(AD bit) set wil be ignored and logged as a host-lookup failure. +(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. @@ -24830,6 +24916,7 @@ AUTH_GSASL=yes AUTH_HEIMDAL_GSSAPI=yes AUTH_PLAINTEXT=yes AUTH_SPA=yes +AUTH_TLS=yes .endd in &_Local/Makefile_&, respectively. The first of these supports the CRAM-MD5 authentication mechanism (RFC 2195), and the second provides an interface to @@ -24844,6 +24931,8 @@ The sixth can be configured to support the PLAIN authentication mechanism (RFC 2595) or the LOGIN mechanism, which is not formally documented, but used by several MUAs. The seventh authenticator supports Microsoft's &'Secure Password Authentication'& mechanism. +The eighth is an Exim authenticator but not an SMTP one; +instead it can use information from a TLS negotiation. The authenticators are configured using the same syntax as other drivers (see section &<>&). If no authenticators are required, no @@ -25563,7 +25652,7 @@ cyrusless_crammd5: driver = cram_md5 public_name = CRAM-MD5 server_secret = ${lookup{$auth1:mail.example.org:userPassword}\ - dbmjz{/etc/sasldb2}} + dbmjz{/etc/sasldb2}{$value}fail} server_set_id = $auth1 .endd @@ -26050,6 +26139,81 @@ msn: +. //////////////////////////////////////////////////////////////////////////// +. //////////////////////////////////////////////////////////////////////////// + +.new +.chapter "The tls authenticator" "CHAPtlsauth" +.scindex IIDtlsauth1 "&(tls)& authenticator" +.scindex IIDtlsauth2 "authenticators" "&(tls)&" +.cindex "authentication" "Client Certificate" +.cindex "authentication" "X509" +.cindex "Certificate-based authentication" +The &(tls)& authenticator provides server support for +authentication based on client certificates. + +It is not an SMTP authentication mechanism and is not +advertised by the server as part of the SMTP EHLO response. +It is an Exim authenticator in the sense that it affects +the protocol element of the log line, can be tested for +by the &%authenticated%& ACL condition, and can set +the &$authenticated_id$& variable. + +The client must present a verifiable certificate, +for which it must have been requested via the +&%tls_verify_hosts%& or &%tls_try_verify_hosts%& main options +(see &<>&). + +If an authenticator of this type is configured it is +run before any SMTP-level communication is done, +and can authenticate the connection. +If it does, SMTP suthentication is not offered. + +A maximum of one authenticator of this type may be present. + + +.cindex "options" "&(tls)& authenticator (server)" +The &(tls)& authenticator has three server options: + +.option server_param1 tls string&!! unset +.cindex "variables (&$auth1$& &$auth2$& etc)" "in &(tls)& authenticator" +This option is expanded after the TLS negotiation and +the result is placed in &$auth1$&. +If the expansion is forced to fail, authentication fails. Any other expansion +failure causes a temporary error code to be returned. + +.option server_param2 tls string&!! unset +.option server_param3 tls string&!! unset +As above, for &$auth2$& and &$auth3$&. + +&%server_param1%& may also be spelled &%server_param%&. + + +Example: +.code +tls: + driver = tls + server_param1 = ${certextract {subj_altname,mail,>:} \ + {$tls_in_peercert}} + server_condition = ${if forany {$auth1} \ + {!= {0} \ + {${lookup ldap{ldap:///\ + mailname=${quote_ldap_dn:${lc:$item}},\ + ou=users,LDAP_DC?mailid} {$value}{0} \ + } } } } + server_set_id = ${if = {1}{${listcount:$auth1}} {$auth1}{}} +.endd +.ecindex IIDtlsauth1 +.ecindex IIDtlsauth2 +.wen + + +Note that because authentication is traditionally an SMTP operation, +the &%authenticated%& ACL condition cannot be used in +a connect- or helo-ACL. + + + . //////////////////////////////////////////////////////////////////////////// . //////////////////////////////////////////////////////////////////////////// @@ -26978,6 +27142,7 @@ options in the main part of the configuration. These options are: .cindex "EXPN" "ACL for" .cindex "HELO" "ACL for" .cindex "EHLO" "ACL for" +.cindex "DKIM" "ACL for" .cindex "MAIL" "ACL for" .cindex "QUIT, ACL for" .cindex "RCPT" "ACL for" @@ -26996,6 +27161,7 @@ options in the main part of the configuration. These options are: .irow &%acl_smtp_connect%& "ACL for start of SMTP connection" .irow &%acl_smtp_data%& "ACL after DATA is complete" .irow &%acl_smtp_data_prdr%& "ACL for each recipient, after DATA is complete" +.irow &%acl_smtp_dkim%& "ACL for each DKIM signer" .irow &%acl_smtp_etrn%& "ACL for ETRN" .irow &%acl_smtp_expn%& "ACL for EXPN" .irow &%acl_smtp_helo%& "ACL for HELO or EHLO" @@ -34636,8 +34802,9 @@ equivalent to the setting: .code log_file_path = $spool_directory/log/%slog .endd -If you do not specify anything at build time or run time, that is where the -logs are written. +If you do not specify anything at build time or run time, +or if you unset the option at run time (i.e. &`log_file_path = `&), +that is where the logs are written. A log file path may also contain &`%D`& or &`%M`& if datestamped log file names are in use &-- see section &<>& below.