TLS documentation bugfixes Fixes: #888
[users/jgh/exim.git] / doc / doc-docbook / spec.xfpt
index 201aefc5dd3fbcd1e5d7a6c4fc1da6c963aa2223..62a07ad75bdf854f4715ffc1a09d106dd181b930 100644 (file)
@@ -1,4 +1,4 @@
-. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.55 2009/10/14 14:48:40 nm4 Exp $
+. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.63 2009/10/26 13:14:23 nm4 Exp $
 .
 . /////////////////////////////////////////////////////////////////////////////
 . This is the primary source of the Exim Manual. It is an xfpt document that is
@@ -2975,6 +2975,7 @@ local part) and outputs what it finds.
 
 .cindex "options" "router &-- extracting"
 .cindex "options" "transport &-- extracting"
+.cindex "options" "authenticator &-- extracting"
 If one of the words &%router%&, &%transport%&, or &%authenticator%& is given,
 followed by the name of an appropriate driver instance, the option settings for
 that driver are output. For example:
@@ -2988,6 +2989,11 @@ using one of the words &%router_list%&, &%transport_list%&, or
 settings can be obtained by using &%routers%&, &%transports%&, or
 &%authenticators%&.
 
+.cindex "options" "macro &-- extracting"
+If invoked by an admin user, then &%macro%&, &%macro_list%& and &%macros%&
+are available, similarly to the drivers.  Because macros are sometimes used
+for storing passwords, this option is restricted.
+The output format is one item per line.
 
 .vitem &%-bp%&
 .oindex "&%-bp%&"
@@ -5885,6 +5891,10 @@ password are correct. In the examples it just produces an error message.
 To make the authenticators work, you can use a string expansion
 expression like one of the examples in &<<CHAPplaintext>>&.
 
+Beware that the sequence of the parameters to PLAIN and LOGIN differ; the
+usercode and password are in different positions.  &<<CHAPplaintext>>&
+covers both.
+
 .ecindex IIDconfiwal
 
 
@@ -6128,7 +6138,7 @@ IPv6 addresses must be enclosed in quotes to prevent the first internal colon
 being interpreted as a key terminator. For example:
 .code
 1.2.3.4:           data for 1.2.3.4
-192.168.0.0/16     data for 192.168.0.0/16
+192.168.0.0/16:    data for 192.168.0.0/16
 "abcd::cdab":      data for abcd::cdab
 "abcd:abcd::/32"   data for abcd:abcd::/32
 .endd
@@ -10199,6 +10209,10 @@ configuration, you might have this:
 .code
 server_condition = ${if pwcheck{$auth1:$auth2}}
 .endd
+Again, for a PLAIN authenticator configuration, this would be:
+.code
+server_condition = ${if pwcheck{$auth2:$auth3}}
+.endd
 .vitem &*queue_running*&
 .cindex "queue runner" "detecting when delivering from"
 .cindex "expansion" "queue runner test"
@@ -10986,7 +11000,7 @@ precise size of the file that has been written. See also
 &$message_body_size$&, &$body_linecount$&, and &$body_zerocount$&.
 
 .cindex "RCPT" "value of &$message_size$&"
-While running an ACL at the time of an SMTP RCPT command, &$message_size$&
+While running a per message ACL (mail/rcpt/predata), &$message_size$&
 contains the size supplied on the MAIL command, or -1 if no size was given. The
 value may not, of course, be truthful.
 
@@ -12354,6 +12368,7 @@ listed in more than one group.
 .row &%gnutls_require_kx%&           "control GnuTLS key exchanges"
 .row &%gnutls_require_mac%&          "control GnuTLS MAC algorithms"
 .row &%gnutls_require_protocols%&    "control GnuTLS protocols"
+.row &%gnutls_compat_mode%&          "use GnuTLS compatibility mode"
 .row &%tls_advertise_hosts%&         "advertise TLS to these hosts"
 .row &%tls_certificate%&             "location of server certificate"
 .row &%tls_crl%&                     "certificate revocation list"
@@ -13353,6 +13368,11 @@ server. For details, see section &<<SECTreqciphgnu>>&.
 This option controls the protocols when GnuTLS is used in an Exim
 server. For details, see section &<<SECTreqciphgnu>>&.
 
+.option gnutls_compat_mode main boolean unset
+This option controls whether GnuTLS is used in compatibility mode in an Exim
+server. This reduces security slightly, but improves interworking with older
+implementations of TLS.
+
 
 .option headers_charset main string "see below"
 This option sets a default character set for translating from encoded MIME
@@ -13424,7 +13444,7 @@ do.
 By default, Exim just checks the syntax of HELO and EHLO commands (see
 &%helo_accept_junk_hosts%& and &%helo_allow_chars%&). However, some sites like
 to do more extensive checking of the data supplied by these commands. The ACL
-condition &`verify`& &`=`& &`helo`& is provided to make this possible.
+condition &`verify = helo`& is provided to make this possible.
 Formerly, it was necessary also to set this option (&%helo_try_verify_hosts%&)
 to force the check to occur. From release 4.53 onwards, this is no longer
 necessary. If the check has not been done before &`verify`& &`=`& &`helo`& is
@@ -17826,10 +17846,10 @@ redirection items of the form
 :defer:
 :fail:
 .endd
-respectively. When a redirection list contains such an item, it applies to the
-entire redirection; any other items in the list are ignored (&':blackhole:'& is
-different). Any text following &':fail:'& or &':defer:'& is placed in the error
-text associated with the failure. For example, an alias file might contain:
+respectively. When a redirection list contains such an item, it applies
+to the entire redirection; any other items in the list are ignored. Any
+text following &':fail:'& or &':defer:'& is placed in the error text
+associated with the failure. For example, an alias file might contain:
 .code
 X.Employee:  :fail: Gone away, no forwarding address
 .endd
@@ -21453,6 +21473,11 @@ client. For details, see section &<<SECTreqciphgnu>>&.
 This option controls the protocols when GnuTLS is used in an Exim
 client. For details, see section &<<SECTreqciphgnu>>&.
 
+.option gnutls_compat_mode main boolean unset
+This option controls whether GnuTLS is used in compatibility mode in an Exim
+server. This reduces security slightly, but improves interworking with older
+implementations of TLS.
+
 .option helo_data smtp string&!! "see below"
 .cindex "HELO" "argument, setting"
 .cindex "EHLO" "argument, setting"
@@ -23813,7 +23838,7 @@ sasl_cram_md5:
 sasl_plain:
   driver = cyrus_sasl
   public_name = PLAIN
-  server_set_id = $auth1
+  server_set_id = $auth2
 .endd
 Cyrus SASL does implement the LOGIN authentication method, even though it is
 not a standard method. It is disabled by default in the source distribution,
@@ -23846,7 +23871,7 @@ dovecot_plain:
   driver = dovecot
   public_name = PLAIN
   server_socket = /var/run/dovecot/auth-client
-  server_set_id = $auth1
+  server_set_id = $auth2
 
 dovecot_ntlm:
   driver = dovecot
@@ -24429,13 +24454,10 @@ unencrypted.
 The &%tls_certificate%& and &%tls_privatekey%& options of the &(smtp)&
 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. &*Note*&:
-These options must be set in the &(smtp)& transport for Exim to use TLS when it
-is operating as a client. Exim does not assume that a server certificate (set
-by the global options of the same name) should also be used when operating as a
-client.
+&%tls_verify_hosts%& or &%tls_try_verify_hosts%& matches the client.
 
-If &%tls_verify_certificates%& is set, it must name a file or,
+If the &%tls_verify_certificates%& option is set on the &(smtp)& transport, it
+must name a file or,
 for OpenSSL only (not GnuTLS), a directory, that contains a collection of
 expected server certificates. The client verifies the server's certificate
 against this collection, taking into account any revoked certificates that are
@@ -24447,6 +24469,12 @@ list of permitted cipher suites. If either of these checks fails, delivery to
 the current host is abandoned, and the &(smtp)& transport tries to deliver to
 alternative hosts, if any.
 
+ &*Note*&:
+These options must be set in the &(smtp)& transport for Exim to use TLS when it
+is operating as a client. Exim does not assume that a server certificate (set
+by the global options of the same name) should also be used when operating as a
+client.
+
 .vindex "&$host$&"
 .vindex "&$host_address$&"
 All the TLS options in the &(smtp)& transport are expanded before use, with
@@ -26975,7 +27003,7 @@ entry must set the rate for the same key (otherwise it will always be zero).
 For example:
 .code
 acl_check_connect:
-  deny ratelimit = 100 / 5m / strict / noupdate
+  deny ratelimit = 100 / 5m / strict / per_cmd / noupdate
        log_message = RATE: $sender_rate/$sender_rate_period \
                      (max $sender_rate_limit)
 .endd
@@ -34392,39 +34420,48 @@ 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
-&%$dkim_signing_domains%& exist.
+&%$dkim_signers%& exist.
 
 The global 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_signing_domains%& already contains a colon-
-separated list of signer domains for the message. When &%dkim_verify_signers%&
-is not specified in the main configuration, it defaults as:
+the expansion variable &%$dkim_signers%& already contains a colon-
+separated list of signer domains and identities for the message. When
+&%dkim_verify_signers%& is not specified in the main configuration,
+it defaults as:
 .code
-dkim_verify_signers = $dkim_signing_domains
+dkim_verify_signers = $dkim_signers
 .endd
 This leads to the default behaviour of calling &%acl_smtp_dkim%& for each
 DKIM signature in the message. Current DKIM verifiers may want to explicitly
 call the ACL for known domains or identities. This would be achieved as follows:
 .code
-dkim_verify_signers = paypal.com:ebay.com:$dkim_signing_domains
+dkim_verify_signers = paypal.com:ebay.com:$dkim_signers
 .endd
 This would result in &%acl_smtp_dkim%& always being called for "paypal.com"
-and "ebay.com", plus all domains that have signatures in the message. You can
-also be more creative in constructing your policy. Example:
+and "ebay.com", plus all domains and identities that have signatures in the message.
+You can also be more creative in constructing your policy. Example:
 .code
-dkim_verify_signers = $sender_address_domain:$dkim_signing_domains
+dkim_verify_signers = $sender_address_domain:$dkim_signers
 .endd
 
+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.
+
+
 Inside the &%acl_smtp_dkim%&, the following expansion variables are
 available (from most to least important):
 
 .vlist
+.vitem &%$dkim_cur_signer%&
+The signer that is being evaluated in this ACL run. This can be domain or
+an identity. This is one of the list items from the expanded main option
+&%dkim_verify_signers%& (see above).
 .vitem &%$dkim_verify_status%&
 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.
+identity (as reflected by &%$dkim_cur_signer%&).
 .next
 &%invalid%&: The signature could not be verified due to a processing error.
 More detail is available in &%$dkim_verify_reason%&.
@@ -34455,14 +34492,12 @@ DKIM verification. It may of course also mean that the signature is forged.
 .endlist
 .vitem &%$dkim_domain%&
 The signing domain. IMPORTANT: This variable is only populated if there is
-ab actual signature in the message. It does NOT neccessarily carry the
-domain that is currently being evaluated. Please use the &%dkim_signers%& ACL
-condition for that.
+an actual signature in the message for the current domain or identity (as
+reflected by &%$dkim_cur_signer%&).
 .vitem &%$dkim_identity%&
-The signing identity. IMPORTANT: This variable is only populated if there is
-ab actual signature in the message. It does NOT neccessarily carry the
-identity that is currently being evaluated. Please use the &%dkim_signers%& ACL
-condition for that.
+The signing identity, if present. IMPORTANT: This variable is only populated
+if there is an actual signature in the message for the current domain or
+identity (as reflected by &%$dkim_cur_signer%&).
 .vitem &%$dkim_selector%&
 The key record selector string
 .vitem &%$dkim_algo%&
@@ -34507,8 +34542,9 @@ In addition, two ACL conditions are provided:
 .vlist
 .vitem &%dkim_signers%&
 ACL condition that checks a colon-separated list of domains or identities
-for a match against the domain or identity that the ACL is currently verifying.
-This is typically used to restrict an ACL verb to a group of domains or identities, like:
+for a match against the domain or identity that the ACL is currently verifying
+(reflected by &%$dkim_cur_signer%&). This is typically used to restrict an ACL
+verb to a group of domains or identities, like:
 
 .code
 # Warn when message apparently from GMail has no signature at all