git://git.exim.org / exim.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
fix all sdop "line overflow" doc complaints
[exim.git] / doc / doc-docbook / spec.xfpt
diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 32e24ca8086811f1669b75f8f3c2436f835433f5..11381a5b81dce7449da4fa5bfcde720cbed418bf 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -9755,11 +9755,13 @@ dotted-quad decimal form, while for IPv6 addreses the result is in
 dotted-nibble hexadecimal form.  In both cases, this is the "natural" form
 for DNS.  For example,
 .code
 dotted-nibble hexadecimal form.  In both cases, this is the "natural" form
 for DNS.  For example,
 .code
-${reverse_ip:192.0.2.4} and ${reverse_ip:2001:0db8:c42:9:1:abcd:192.0.2.3}
+${reverse_ip:192.0.2.4}
+${reverse_ip:2001:0db8:c42:9:1:abcd:192.0.2.3}
 .endd
 returns
 .code
 .endd
 returns
 .code
-4.2.0.192 and 3.0.2.0.0.0.0.c.d.c.b.a.1.0.0.0.9.0.0.0.2.4.c.0.8.b.d.0.1.0.0.2
+4.2.0.192
+3.0.2.0.0.0.0.c.d.c.b.a.1.0.0.0.9.0.0.0.2.4.c.0.8.b.d.0.1.0.0.2
 .endd
 
 
 .endd
 
 
@@ -11899,8 +11901,9 @@ If the variable appears in &%tls_certificate%& then this option and
 a different certificate to be presented (and optionally a different key to be
 used) to the client, based upon the value of the SNI extension.
 
 a different certificate to be presented (and optionally a different key to be
 used) to the client, based upon the value of the SNI extension.
 
-The value will be retained for the lifetime of the message, and not changed
-during outbound SMTP.
+The value will be retained for the lifetime of the message.  During outbound
+SMTP deliveries, it reflects the value of the &%tls_sni%& option on
+the transport.
 
 This is currently only available when using OpenSSL, built with support for
 SNI.
 
 This is currently only available when using OpenSSL, built with support for
 SNI.
@@ -14380,61 +14383,63 @@ some now infamous attacks.
 
 An example:
 .code
 
 An example:
 .code
-openssl_options = -all +microsoft_big_sslv3_buffer +dont_insert_empty_fragments
+# Make both old MS and old Eudora happy:
+openssl_options = -all +microsoft_big_sslv3_buffer \
+                       +dont_insert_empty_fragments
 .endd
 
 Possible options may include:
 .ilist
 &`all`&
 .endd
 
 Possible options may include:
 .ilist
 &`all`&
-.ilist
+.next
 &`allow_unsafe_legacy_renegotiation`&
 &`allow_unsafe_legacy_renegotiation`&
-.ilist
+.next
 &`cipher_server_preference`&
 &`cipher_server_preference`&
-.ilist
+.next
 &`dont_insert_empty_fragments`&
 &`dont_insert_empty_fragments`&
-.ilist
+.next
 &`ephemeral_rsa`&
 &`ephemeral_rsa`&
-.ilist
+.next
 &`legacy_server_connect`&
 &`legacy_server_connect`&
-.ilist
+.next
 &`microsoft_big_sslv3_buffer`&
 &`microsoft_big_sslv3_buffer`&
-.ilist
+.next
 &`microsoft_sess_id_bug`&
 &`microsoft_sess_id_bug`&
-.ilist
+.next
 &`msie_sslv2_rsa_padding`&
 &`msie_sslv2_rsa_padding`&
-.ilist
+.next
 &`netscape_challenge_bug`&
 &`netscape_challenge_bug`&
-.ilist
+.next
 &`netscape_reuse_cipher_change_bug`&
 &`netscape_reuse_cipher_change_bug`&
-.ilist
+.next
 &`no_compression`&
 &`no_compression`&
-.ilist
+.next
 &`no_session_resumption_on_renegotiation`&
 &`no_session_resumption_on_renegotiation`&
-.ilist
+.next
 &`no_sslv2`&
 &`no_sslv2`&
-.ilist
+.next
 &`no_sslv3`&
 &`no_sslv3`&
-.ilist
+.next
 &`no_ticket`&
 &`no_ticket`&
-.ilist
+.next
 &`no_tlsv1`&
 &`no_tlsv1`&
-.ilist
+.next
 &`no_tlsv1_1`&
 &`no_tlsv1_1`&
-.ilist
+.next
 &`no_tlsv1_2`&
 &`no_tlsv1_2`&
-.ilist
+.next
 &`single_dh_use`&
 &`single_dh_use`&
-.ilist
+.next
 &`single_ecdh_use`&
 &`single_ecdh_use`&
-.ilist
+.next
 &`ssleay_080_client_dh_bug`&
 &`ssleay_080_client_dh_bug`&
-.ilist
+.next
 &`sslref2_reuse_cert_type_bug`&
 &`sslref2_reuse_cert_type_bug`&
-.ilist
+.next
 &`tls_block_padding_bug`&
 &`tls_block_padding_bug`&
-.ilist
+.next
 &`tls_d5_bug`&
 &`tls_d5_bug`&
-.ilist
+.next
 &`tls_rollback_bug`&
 .endlist
 
 &`tls_rollback_bug`&
 .endlist
 
@@ -15627,6 +15632,12 @@ receiving incoming messages as a server. If you want to supply certificates for
 use when sending messages as a client, you must set the &%tls_certificate%&
 option in the relevant &(smtp)& transport.
 
 use when sending messages as a client, you must set the &%tls_certificate%&
 option in the relevant &(smtp)& transport.
 
+.new
+If the option contains &$tls_sni$& and Exim is built against OpenSSL, then
+if the OpenSSL build supports TLS extensions and the TLS client sends the
+Server Name Indication extension, then this option and &%tls_privatekey%&
+will be re-expanded.
+.wen
 
 .option tls_crl main string&!! unset
 .cindex "TLS" "server certificate revocation list"
 
 .option tls_crl main string&!! unset
 .cindex "TLS" "server certificate revocation list"
@@ -15659,6 +15670,11 @@ the expansion is forced to fail, or the result is an empty string, the private
 key is assumed to be in the same file as the server's certificates. See chapter
 &<<CHAPTLS>>& for further details.
 
 key is assumed to be in the same file as the server's certificates. See chapter
 &<<CHAPTLS>>& for further details.
 
+.new
+See &%tls_certificate%& discussion of &$tls_sni$& for when this option may be
+re-expanded.
+.wen
+
 
 .option tls_remember_esmtp main boolean false
 .cindex "TLS" "esmtp state; remembering"
 
 .option tls_remember_esmtp main boolean false
 .cindex "TLS" "esmtp state; remembering"
@@ -22371,6 +22387,20 @@ ciphers is a preference order.
 
 
 
 
 
 
+.new
+.option tls_sni smtp string&!! unset
+.cindex "TLS" "Server Name Indication"
+.vindex "&$tls_sni$&"
+If this option is set then it sets the $tls_sni variable and causes any
+TLS session to pass this value as the Server Name Indication extension to
+the remote side, which can be used by the remote side to select an appropriate
+certificate and private key for the session.
+
+OpenSSL only, also requiring a build of OpenSSL that supports TLS extensions.
+.wen
+
+
+
 .option tls_tempfail_tryclear smtp boolean true
 .cindex "4&'xx'& responses" "to STARTTLS"
 When the server host is not in &%hosts_require_tls%&, and there is a problem in
 .option tls_tempfail_tryclear smtp boolean true
 .cindex "4&'xx'& responses" "to STARTTLS"
 When the server host is not in &%hosts_require_tls%&, and there is a problem in
@@ -24135,9 +24165,10 @@ login:
   server_prompts = Username:: : Password::
   server_condition = ${if and{{ \
     !eq{}{$auth1} }{ \
   server_prompts = Username:: : Password::
   server_condition = ${if and{{ \
     !eq{}{$auth1} }{ \
-    ldapauth{user="cn=${quote_ldap_dn:$auth1},ou=people,o=example.org" \
-             pass=${quote:$auth2} \
-             ldap://ldap.example.org/} }} }
+    ldapauth{\
+      user="uid=${quote_ldap_dn:$auth1},ou=people,o=example.org" \
+      pass=${quote:$auth2} \
+      ldap://ldap.example.org/} }} }
   server_set_id = uid=$auth1,ou=people,o=example.org
 .endd
 We have to check that the username is not empty before using it, because LDAP
   server_set_id = uid=$auth1,ou=people,o=example.org
 .endd
 We have to check that the username is not empty before using it, because LDAP
@@ -27796,14 +27827,14 @@ in the MAIL ACL. Subsequent connections from the same client will check this
 new rate.
 .code
 acl_check_connect:
 new rate.
 .code
 acl_check_connect:
-  deny ratelimit = 100 / 5m / readonly
-       log_message = RATE CHECK: $sender_rate/$sender_rate_period \
-                     (max $sender_rate_limit)
+ deny ratelimit = 100 / 5m / readonly
+    log_message = RATE CHECK: $sender_rate/$sender_rate_period \
+                  (max $sender_rate_limit)
 # ...
 acl_check_mail:
 # ...
 acl_check_mail:
-  warn ratelimit = 100 / 5m / strict
-       log_message  = RATE UPDATE: $sender_rate/$sender_rate_period \
-                      (max $sender_rate_limit)
+ warn ratelimit = 100 / 5m / strict
+    log_message = RATE UPDATE: $sender_rate/$sender_rate_period \
+                  (max $sender_rate_limit)
 .endd
 
 If Exim encounters multiple &%ratelimit%& conditions with the same key when
 .endd
 
 If Exim encounters multiple &%ratelimit%& conditions with the same key when
@@ -33155,6 +33186,7 @@ selection marked by asterisks:
 &` tls_certificate_verified   `&  certificate verification status
 &`*tls_cipher                 `&  TLS cipher suite on <= and => lines
 &` tls_peerdn                 `&  TLS peer DN on <= and => lines
 &` tls_certificate_verified   `&  certificate verification status
 &`*tls_cipher                 `&  TLS cipher suite on <= and => lines
 &` tls_peerdn                 `&  TLS peer DN on <= and => lines
+&` tls_sni                    `&  TLS SNI on <= lines
 &` unknown_in_list            `&  DNS lookup failed in list match
 
 &` all                        `&  all of the above
 &` unknown_in_list            `&  DNS lookup failed in list match
 
 &` all                        `&  all of the above
@@ -33450,6 +33482,12 @@ connection, the cipher suite used is added to the log line, preceded by X=.
 connection, and a certificate is supplied by the remote host, the peer DN is
 added to the log line, preceded by DN=.
 .next
 connection, and a certificate is supplied by the remote host, the peer DN is
 added to the log line, preceded by DN=.
 .next
+.cindex "log" "TLS SNI"
+.cindex "TLS" "logging SNI"
+&%tls_sni%&: When a message is received over an encrypted connection, and
+the remote host provided the Server Name Indication extension, the SNI is
+added to the log line, preceded by SNI=.
+.next
 .cindex "log" "DNS failure in list"
 &%unknown_in_list%&: This setting causes a log entry to be written when the
 result of a list match is failure because a DNS lookup failed.
 .cindex "log" "DNS failure in list"
 &%unknown_in_list%&: This setting causes a log entry to be written when the
 result of a list match is failure because a DNS lookup failed.
@@ -35254,10 +35292,15 @@ unqualified domain &'foundation'&.
 . ////////////////////////////////////////////////////////////////////////////
 . ////////////////////////////////////////////////////////////////////////////
 
 . ////////////////////////////////////////////////////////////////////////////
 . ////////////////////////////////////////////////////////////////////////////
 
-.chapter "Support for DKIM (DomainKeys Identified Mail) - RFC4871" "CHID12" &&&
+.chapter "Support for DKIM (DomainKeys Identified Mail)" "CHID12" &&&
          "DKIM Support"
 .cindex "DKIM"
 
          "DKIM Support"
 .cindex "DKIM"
 
+DKIM is a mechanism by which messages sent by some entity can be provably
+linked to a domain which that entity controls.  It permits reputation to
+be tracked on a per-domain basis, rather than merely upon source IP address.
+DKIM is documented in RFC 4871.
+
 Since version 4.70, DKIM support is compiled into Exim by default. It can be
 disabled by setting DISABLE_DKIM=yes in Local/Makefile.
 
 Since version 4.70, DKIM support is compiled into Exim by default. It can be
 disabled by setting DISABLE_DKIM=yes in Local/Makefile.
 
@@ -35278,9 +35321,12 @@ Exim's standard controls.
 Please note that verification of DKIM signatures in incoming mail is turned
 on by default for logging purposes. For each signature in incoming email,
 exim will log a line displaying the most important signature details, and the
 Please note that verification of DKIM signatures in incoming mail is turned
 on by default for logging purposes. For each signature in incoming email,
 exim will log a line displaying the most important signature details, and the
-signature status. Here is an example:
+signature status. Here is an example (with line-breaks added for clarity):
 .code
 .code
-2009-09-09 10:22:28 1MlIRf-0003LU-U3 DKIM: d=facebookmail.com s=q1-2009b c=relaxed/relaxed a=rsa-sha1 i=@facebookmail.com t=1252484542 [verification succeeded]
+2009-09-09 10:22:28 1MlIRf-0003LU-U3 DKIM:
+    d=facebookmail.com s=q1-2009b
+    c=relaxed/relaxed a=rsa-sha1
+    i=@facebookmail.com t=1252484542 [verification succeeded]
 .endd
 You might want to turn off DKIM verification processing entirely for internal
 or relay mail sources. To do that, set the &%dkim_disable_verify%& ACL
 .endd
 You might want to turn off DKIM verification processing entirely for internal
 or relay mail sources. To do that, set the &%dkim_disable_verify%& ACL
@@ -35488,7 +35534,7 @@ for a match against the domain or identity that the ACL is currently verifying
 verb to a group of domains or identities. For example:
 
 .code
 verb to a group of domains or identities. For example:
 
 .code
-# Warn when message apparently from GMail has no signature at all
+# Warn when Mail purportedly from GMail has no signature at all
 warn log_message = GMail sender without DKIM signature
      sender_domains = gmail.com
      dkim_signers = gmail.com
 warn log_message = GMail sender without DKIM signature
      sender_domains = gmail.com
      dkim_signers = gmail.com
@@ -35498,10 +35544,10 @@ warn log_message = GMail sender without DKIM signature
 .vitem &%dkim_status%&
 ACL condition that checks a colon-separated list of possible DKIM verification
 results agains the actual result of verification. This is typically used
 .vitem &%dkim_status%&
 ACL condition that checks a colon-separated list of possible DKIM verification
 results agains the actual result of verification. This is typically used
-to restrict an ACL verb to a list of verification outcomes, like:
+to restrict an ACL verb to a list of verification outcomes, for example:
 
 .code
 
 .code
-deny message = Message from Paypal with invalid or missing signature
+deny message = Mail from Paypal with invalid/missing signature
      sender_domains = paypal.com:paypal.de
      dkim_signers = paypal.com:paypal.de
      dkim_status = none:invalid:fail
      sender_domains = paypal.com:paypal.de
      dkim_signers = paypal.com:paypal.de
      dkim_status = none:invalid:fail
Master Exim source repository