GSASL: provide $autnN for scram option expansions

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 1d4c39c6d6a898b9e71ea616826b45c028fbdc55..4d02bdc32e8c339ae29431a5fabfd913fa8a34ac 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -27435,6 +27435,9 @@ auth_mechanisms = plain login ntlm
 .cindex "authentication" "DIGEST-MD5"
 .cindex "authentication" "CRAM-MD5"
 .cindex "authentication" "SCRAM-SHA-1"
+.cindex "authentication" "SCRAM-SHA-1-PLUS"
+.cindex "authentication" "SCRAM-SHA-256"
+.cindex "authentication" "SCRAM-SHA-256-PLUS"
 The &(gsasl)& authenticator provides integration for the GNU SASL
 library and the mechanisms it provides.  This is new as of the 4.80 release
 and there are a few areas where the library does not let Exim smoothly
@@ -27442,8 +27445,13 @@ scale to handle future authentication mechanisms, so no guarantee can be
 made that any particular new authentication mechanism will be supported
 without code changes in Exim.
 
-
 .new
+The library is expected to add support in an upcoming
+realease for the SCRAM-SHA-256 method.
+The macro _HAVE_AUTH_GSASL_SCRAM_SHA_256 will be defined
+when this happens.
+
+
 .option client_authz gsasl string&!! unset
 This option can be used to supply an &'authorization id'&
 which is different to the &'authentication_id'& provided
@@ -27481,6 +27489,7 @@ server to see different identifiers and authentication will fail.
 This is
 only usable by mechanisms which support "channel binding"; at time of
 writing, that's the SCRAM family.
+When using this feature the "-PLUS" variants of the method names need to be used.
 .wen
 
 This defaults off to ensure smooth upgrade across Exim releases, in case
@@ -27535,16 +27544,28 @@ This specifies the SASL realm that the server claims to be in.
 Some mechanisms will use this data.
 
 
-.option server_scram_iter gsasl string&!! unset
+.option server_scram_iter gsasl string&!! 4096
 This option provides data for the SCRAM family of mechanisms.
-&$auth1$& is not available at evaluation time.
-(This may change, as we receive feedback on use)
+.new
+The &$auth1$&, &$auth2$& and &$auth3$& variables are available for expansion.
+
+The result of expansion should be a decimal number,
+and represents both a lower-bound on the security, and
+a compute cost factor imposed on the client
+(if it does not cache results, or the server changes
+either the iteration count or the salt).
+A minimum value of 4096 is required by the standards
+for all current CRAM mechanism variants.
+.wen
 
 
 .option server_scram_salt gsasl string&!! unset
 This option provides data for the SCRAM family of mechanisms.
-&$auth1$& is not available at evaluation time.
-(This may change, as we receive feedback on use)
+.new
+The &$auth1$&, &$auth2$& and &$auth3$& variables are available for expansion.
+If unset or empty after expansion the library will provides a value for the
+protocol conversation.
+.wen
 
 
 .option server_service gsasl string &`smtp`&
@@ -37355,7 +37376,7 @@ the following table:
 &`DKIM`&        domain verified in incoming message
 &`DN  `&        distinguished name from peer certificate
 &`DS  `&        DNSSEC secured lookups
-&`DT  `&        on &`=>`& lines: time taken for a delivery
+&`DT  `&        on &`=>`&, &'=='& and &'**'& lines: time taken for, or to attempt, a delivery
 &`F   `&        sender address (on delivery lines)
 &`H   `&        host name and IP address
 &`I   `&        local interface used
@@ -37453,7 +37474,7 @@ selection marked by asterisks:
 &` arguments                  `&  command line arguments
 &`*connection_reject          `&  connection rejections
 &`*delay_delivery             `&  immediate delivery delayed
-&` deliver_time               `&  time taken to perform delivery
+&` deliver_time               `&  time taken to attempt delivery
 &` delivery_size              `&  add &`S=`&&'nnn'& to => lines
 &`*dkim                       `&  DKIM verified domain on <= lines
 &` dkim_verbose               `&  separate full DKIM verification result line, per signature
@@ -40571,9 +40592,8 @@ defines the location of a text file of valid
 top level domains the opendmarc library uses
 during domain parsing. Maintained by Mozilla,
 the most current version can be downloaded
-from a link at &url(https://publicsuffix.org/list/, currently pointing
-at https://publicsuffix.org/list/public_suffix_list.dat)
-See also util/renew-opendmarc-tlds.sh script.
+from a link at &url(https://publicsuffix.org/list/public_suffix_list.dat).
+See also the util/renew-opendmarc-tlds.sh script.
 .new
 The default for the option is unset.
 If not set, DMARC processing is disabled.