X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/c7955b11ec2f588b346b0bcdbd1e2fa1b55b1630..a39409651d6f823248380812dd7d01361a3b0169:/doc/doc-docbook/spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index c13b8358d..c1f845eaf 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -6223,13 +6223,26 @@ using Berkeley DB versions 3 or 4, it opens existing databases for reading with
 the DB_UNKNOWN option. This enables it to handle any of the types of database
 that the library supports, and can be useful for accessing DBM files created by
 other applications. (For earlier DB versions, DB_HASH is always used.)
+.new
+.next
+.cindex "lookup" "dbmjz"
+.cindex "lookup" "dbm &-- embedded NULs"
+.cindex "sasldb2"
+.cindex "dbmjz lookup type"
+&(dbmjz)&: This is the same as &(dbm)&, except that the lookup key is
+interpreted as an Exim list; the elements of the list are joined together with
+ASCII NUL characters to form the lookup key.  An example usage would be to
+authenticate incoming SMTP calls using the passwords from Cyrus SASL's
+&_/etc/sasldb2_& file with the &(gsasl)& authenticator or Exim's own
+&(cram_md5)& authenticator.
+.wen
 .next
 .cindex "lookup" "dbmnz"
 .cindex "lookup" "dbm &-- terminating zero"
 .cindex "binary zero" "in lookup key"
 .cindex "Courier"
 .cindex "&_/etc/userdbshadow.dat_&"
-.cindex "dmbnz lookup type"
+.cindex "dbmnz lookup type"
 &(dbmnz)&: This is the same as &(dbm)&, except that a terminating binary zero
 is not included in the key that is passed to the DBM library. You may need this
 if you want to look up data in files that are created by or shared with some
@@ -8523,6 +8536,13 @@ start of a portion of the string that is interpreted and replaced as described
 below in section &<<SECTexpansionitems>>& onwards. Backslash is used as an
 escape character, as described in the following section.
 
+Whether a string is expanded depends upon the context.  Usually this is solely
+dependent upon the option for which a value is sought; in this documentation,
+options for which string expansion is performed are marked with &dagger; after
+the data type.  ACL rules always expand strings.  A couple of expansion
+conditions do not expand some of the brace-delimited branches, for security
+reasons.
+
 
 
 .section "Literal text in expanded strings" "SECTlittext"
@@ -9904,6 +9924,10 @@ lower case), signifying multiplication by 1024 or 1024*1024, respectively.
 As a special case, the numerical value of an empty string is taken as
 zero.
 
+In all cases, a relative comparator OP is testing if <&'string1'&> OP
+<&'string2'&>; the above example is checking if &$message_size$& is larger than
+10M, not if 10M is larger than &$message_size$&.
+
 
 .vitem &*bool&~{*&<&'string'&>&*}*&
 .cindex "expansion" "boolean parsing"
@@ -24179,6 +24203,20 @@ lookup_cram:
 Note that this expansion explicitly forces failure if the lookup fails
 because &$auth1$& contains an unknown user name.
 
+.new
+As another example, if you wish to re-use a Cyrus SASL sasldb2 file without
+using the relevant libraries, you need to know the realm to specify in the
+lookup and then ask for the &"userPassword"& attribute for that user in that
+realm, with:
+.code
+cyrusless_crammd5:
+  driver = cram_md5
+  public_name = CRAM-MD5
+  server_secret = ${lookup{$auth1:mail.example.org:userPassword}\
+                  dbmjz{/etc/sasldb2}}
+  server_set_id = $auth1
+.endd
+.wen
 
 .section "Using cram_md5 as a client" "SECID177"
 .cindex "options" "&(cram_md5)& authenticator (client)"
@@ -24510,6 +24548,20 @@ An &'anonymous token'& is something passed along as an unauthenticated
 identifier; this is analogous to FTP anonymous authentication passing an
 email address, or software-identifier@, as the "password".
 
+
+An example showing the password having the realm specified in the callback
+and demonstrating a Cyrus SASL to GSASL migration approach is:
+.code
+gsasl_cyrusless_crammd5:
+  driver = gsasl
+  public_name = CRAM-MD5
+  server_realm = imap.example.org
+  server_password = ${lookup{$auth1:$auth3:userPassword}\
+                    dbmjz{/etc/sasldb2}{$value}fail}
+  server_set_id = ${quote:$auth1}
+  server_condition = yes
+.endd
+
 .wen
 
 . ////////////////////////////////////////////////////////////////////////////