fix gsasl / cyrus claims

[users/heiko/exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 8afccbf1d2266d989919bca2b06f52e7252873b8..ed9b0d71014bf579dfe7fe9897046096b37dd95c 100644 (file)
--- 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
@@ -11824,6 +11837,16 @@ command in a filter file. Its use is explained in the description of that
 command, which can be found in the separate document entitled &'Exim's
 interfaces to mail filtering'&.
 
+.new
+.vitem &$tls_bits$&
+.vindex "&$tls_bits$&"
+Contains an approximation of the TLS cipher's bit-strength; the meaning of
+this depends upon the TLS implementation used.
+If TLS has not been negotiated, the value will be 0.
+The value of this is automatically fed into the Cyrus SASL authenticator
+when acting as a server, to specify the "external SSF" (a SASL term).
+.wen
+
 .vitem &$tls_certificate_verified$&
 .vindex "&$tls_certificate_verified$&"
 This variable is set to &"1"& if a TLS certificate was verified when the
@@ -24169,6 +24192,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)"
@@ -24283,8 +24320,10 @@ sasl:
   server_set_id = $auth1
 .endd
 
-.option server_realm cyrus_sasl string unset
+.new
+.option server_realm cyrus_sasl string&!! unset
 This specifies the SASL realm that the server claims to be in.
+.wen
 
 
 .option server_service cyrus_sasl string &`smtp`&
@@ -24498,6 +24537,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
 
 . ////////////////////////////////////////////////////////////////////////////
@@ -24546,7 +24599,8 @@ role suffix.  For instance, &"joe/admin@EXAMPLE.ORG"&.
 .next
 .vindex "&$auth2$&"
 &$auth2$&: the &'authorization id'&, sent within SASL encapsulation after
-authentication.
+authentication.  If that was empty, this will also be set to the
+GSS Display Name.
 .endlist
 
 .wen