Fix crash in mime acl when a parameter is zero-length
[exim.git] / doc / doc-docbook / spec.xfpt
index 2425cac60f06f98445dca89f13b53943d3337efc..4d620a36f98652c710df9db0a8b7182858bf5bf2 100644 (file)
@@ -7338,6 +7338,10 @@ If you specify multiple attributes, the result contains space-separated, quoted
 strings, each preceded by the attribute name and an equals sign. Within the
 quotes, the quote character, backslash, and newline are escaped with
 backslashes, and commas are used to separate multiple values for the attribute.
 strings, each preceded by the attribute name and an equals sign. Within the
 quotes, the quote character, backslash, and newline are escaped with
 backslashes, and commas are used to separate multiple values for the attribute.
+.new
+Any commas in attribute values are doubled
+(permitting treatment of the values as a comma-separated list).
+.wen
 Apart from the escaping, the string within quotes takes the same form as the
 output when a single attribute is requested. Specifying no attributes is the
 same as specifying all of an entry's attributes.
 Apart from the escaping, the string within quotes takes the same form as the
 output when a single attribute is requested. Specifying no attributes is the
 same as specifying all of an entry's attributes.
@@ -7347,21 +7351,26 @@ LDAP query, and the second is the data that is returned. The attribute called
 &%attr1%& has two values, whereas &%attr2%& has only one value:
 .code
 ldap:///o=base?attr1?sub?(uid=fred)
 &%attr1%& has two values, whereas &%attr2%& has only one value:
 .code
 ldap:///o=base?attr1?sub?(uid=fred)
-value1.1, value1.2
+value1.1,value1.2
 
 ldap:///o=base?attr2?sub?(uid=fred)
 value two
 
 ldap:///o=base?attr1,attr2?sub?(uid=fred)
 
 ldap:///o=base?attr2?sub?(uid=fred)
 value two
 
 ldap:///o=base?attr1,attr2?sub?(uid=fred)
-attr1="value1.1, value1.2" attr2="value two"
+attr1="value1.1,value1.2" attr2="value two"
 
 ldap:///o=base??sub?(uid=fred)
 
 ldap:///o=base??sub?(uid=fred)
-objectClass="top" attr1="value1.1, value1.2" attr2="value two"
+objectClass="top" attr1="value1.1,value1.2" attr2="value two"
 .endd
 .endd
-The &%extract%& operator in string expansions can be used to pick out
-individual fields from data that consists of &'key'&=&'value'& pairs. You can
+You can
 make use of Exim's &%-be%& option to run expansion tests and thereby check the
 results of LDAP lookups.
 make use of Exim's &%-be%& option to run expansion tests and thereby check the
 results of LDAP lookups.
+The &%extract%& operator in string expansions can be used to pick out
+individual fields from data that consists of &'key'&=&'value'& pairs.
+.new
+The &%listextract%& operator should be used to pick out individual values
+of attributes, even when only a single value is expected.
+.wen
 
 
 
 
 
 
@@ -11413,6 +11422,11 @@ the result, the name is not accepted, and &$host_lookup_deferred$& is set to
 .vindex "&$host_lookup_failed$&"
 See &$host_lookup_deferred$&.
 
 .vindex "&$host_lookup_failed$&"
 See &$host_lookup_deferred$&.
 
+.vitem &$host_port$&
+.vindex "&$host_port$&"
+This variable is set to the remote host's TCP port whenever &$host$& is set
+for an outbound connection.
+
 
 .vitem &$inode$&
 .vindex "&$inode$&"
 
 .vitem &$inode$&
 .vindex "&$inode$&"
@@ -11659,7 +11673,7 @@ This variable is like &$message_headers$& except that no processing of the
 contents of header lines is done.
 
 .vitem &$message_id$&
 contents of header lines is done.
 
 .vitem &$message_id$&
-This is an old name for &$message_exim_id$&, which is now deprecated.
+This is an old name for &$message_exim_id$&. It is now deprecated.
 
 .vitem &$message_linecount$&
 .vindex "&$message_linecount$&"
 
 .vitem &$message_linecount$&
 .vindex "&$message_linecount$&"
@@ -12355,7 +12369,9 @@ If TLS has not been negotiated, the value will be 0.
 This variable refers to the certificate presented to the peer of an
 inbound connection when the message was received.
 It is only useful as the argument of a
 This variable refers to the certificate presented to the peer of an
 inbound connection when the message was received.
 It is only useful as the argument of a
-&%certextract%& expansion item, &%md5%& or &%sha1%& operator,
+.new
+&%certextract%& expansion item, &%md5%&, &%sha1%& or &%sha256%& operator,
+.wen
 or a &%def%& condition.
 
 .vitem &$tls_in_peercert$&
 or a &%def%& condition.
 
 .vitem &$tls_in_peercert$&
@@ -12363,21 +12379,27 @@ or a &%def%& condition.
 This variable refers to the certificate presented by the peer of an
 inbound connection when the message was received.
 It is only useful as the argument of a
 This variable refers to the certificate presented by the peer of an
 inbound connection when the message was received.
 It is only useful as the argument of a
-&%certextract%& expansion item, &%md5%& or &%sha1%& operator,
+.new
+&%certextract%& expansion item, &%md5%&, &%sha1%& or &%sha256%& operator,
+.wen
 or a &%def%& condition.
 
 .vitem &$tls_out_ourcert$&
 .vindex "&$tls_out_ourcert$&"
 This variable refers to the certificate presented to the peer of an
 outbound connection.  It is only useful as the argument of a
 or a &%def%& condition.
 
 .vitem &$tls_out_ourcert$&
 .vindex "&$tls_out_ourcert$&"
 This variable refers to the certificate presented to the peer of an
 outbound connection.  It is only useful as the argument of a
-&%certextract%& expansion item, &%md5%& or &%sha1%& operator,
+.new
+&%certextract%& expansion item, &%md5%&, &%sha1%& or &%sha256%& operator,
+.wen
 or a &%def%& condition.
 
 .vitem &$tls_out_peercert$&
 .vindex "&$tls_out_peercert$&"
 This variable refers to the certificate presented by the peer of an
 outbound connection.  It is only useful as the argument of a
 or a &%def%& condition.
 
 .vitem &$tls_out_peercert$&
 .vindex "&$tls_out_peercert$&"
 This variable refers to the certificate presented by the peer of an
 outbound connection.  It is only useful as the argument of a
-&%certextract%& expansion item, &%md5%& or &%sha1%& operator,
+.new
+&%certextract%& expansion item, &%md5%&, &%sha1%& or &%sha256%& operator,
+.wen
 or a &%def%& condition.
 
 .vitem &$tls_in_certificate_verified$&
 or a &%def%& condition.
 
 .vitem &$tls_in_certificate_verified$&
@@ -16800,6 +16822,39 @@ If the expansion fails (other than forced failure) delivery is deferred. Some
 of the other precondition options are common special cases that could in fact
 be specified using &%condition%&.
 
 of the other precondition options are common special cases that could in fact
 be specified using &%condition%&.
 
+.new
+When originally designed, Exim's ACL system enforced very strict parsing
+of the &%condition%& expansion everywhere it was being processed.
+Through the 4.7x release cycle, the &%condition%& processing while in a
+router became more loose, internally adopting the use of &%bool_lax%&
+instead of the more rigid &%bool%&.  This is best illustrated in an
+example:
+.code
+# This used to fail with a syntax error, now it
+# treats any extra characters as a string
+
+$ exim -be '${if eq {${lc:GOOGLE.com}} {google.com}} {yes} {no}}'
+true {yes} {no}}
+
+$ exim -be '${if eq {${lc:WHOIS.com}} {google.com}} {yes} {no}}'
+ {yes} {no}}
+.endd
+In each example above, the &%if%& statement actually ends after
+&"{google.com}}"&.  Since no true or false braces were defined, the
+default &%if%& behavior is to return a boolean true or a null answer
+(which evaluates to false). The rest of the line is then treated as a
+string. So the first example resulted in the boolean answer &"true"&
+with the string &" {yes} {no}}"& appended to it. The second example
+resulted in the null output (indicating false) with the string
+&" {yes} {no}}"& appended to it.
+
+In fact you can put excess forward braces in too.  In the router
+&%condition%&, Exim's ACL parser only looks for &"{"& symbols when they
+mean something, like after a &"$"& or when required as part of a
+conditional.  But otherwise &"{"& and &"}"& are treated as ordinary
+string characters.
+.wen
+
 
 .option debug_print routers string&!! unset
 .cindex "testing" "variables in drivers"
 
 .option debug_print routers string&!! unset
 .cindex "testing" "variables in drivers"
@@ -27624,6 +27679,11 @@ anyway. If the message contains newlines, this gives rise to a multi-line SMTP
 response.
 
 .vindex "&$acl_verify_message$&"
 response.
 
 .vindex "&$acl_verify_message$&"
+.new
+For ACLs that are called by an &%acl =%& ACL condition, the message is
+stored in &$acl_verify_message$&, from which the calling ACL may use it.
+.wen
+
 If &%message%& is used on a statement that verifies an address, the message
 specified overrides any message that is generated by the verification process.
 However, the original message is available in the variable
 If &%message%& is used on a statement that verifies an address, the message
 specified overrides any message that is generated by the verification process.
 However, the original message is available in the variable