📖 Update SASL mechanism parameter documentation

nevans · nevans · commit 5bc8bff54f94 · 2023-10-19T19:38:51.000-04:00
Harmonized the formatting and language of SASL mechanism parameters.
Made a few corrections (e.g. where `PLAIN` should have been `XOAUTH2`).
Added some RFC reference links.  Etc.
diff --git a/lib/net/imap/sasl/anonymous_authenticator.rb b/lib/net/imap/sasl/anonymous_authenticator.rb
@@ -29,8 +29,9 @@ class AnonymousAuthenticator
         # this, see Net::IMAP#authenticate or your client's authentication
         # method.
         #
-        # #anonymous_message is an optional message which is sent to the server.
-        # It may be sent as a positional argument or as a keyword argument.
+        # ==== Parameters
+        #
+        # * _optional_ #anonymous_message — a message to send to the server.
         #
         # Any other keyword arguments are silently ignored.
         def initialize(anon_msg = nil, anonymous_message: nil, **)
diff --git a/lib/net/imap/sasl/digest_md5_authenticator.rb b/lib/net/imap/sasl/digest_md5_authenticator.rb
@@ -53,10 +53,16 @@ class Net::IMAP::SASL::DigestMD5Authenticator
   #
   # * #username — Identity whose #password is used.
   # * #password — A password or passphrase associated with this #username.
-  # * #authzid ― Alternate identity to act as or on behalf of.  Optional.
-  # * +warn_deprecation+ — Set to +false+ to silence the warning.
   #
-  # See the documentation for each attribute for more details.
+  #
+  # * _optional_ #authzid  ― Authorization identity to act as or on behalf of.
+  #
+  #   When +authzid+ is not set, the server should derive the authorization
+  #   identity from the authentication identity.
+  #
+  # * _optional_ +warn_deprecation+ — Set to +false+ to silence the warning.
+  #
+  # Any other keyword arguments are silently ignored.
   def initialize(user = nil, pass = nil, authz = nil,
                  username: nil, password: nil, authzid: nil,
                  warn_deprecation: true, **)
diff --git a/lib/net/imap/sasl/external_authenticator.rb b/lib/net/imap/sasl/external_authenticator.rb
@@ -12,10 +12,18 @@ module SASL
       # established external to SASL, for example by TLS certificate or IPsec.
       class ExternalAuthenticator
 
-        # Authorization identity: an identity to act as or on behalf of.
+        # Authorization identity: an identity to act as or on behalf of.  The
+        # identity form is application protocol specific.  If not provided or
+        # left blank, the server derives an authorization identity from the
+        # authentication identity.  The server is responsible for verifying the
+        # client's credentials and verifying that the identity it associates
+        # with the client's authentication identity is allowed to act as (or on
+        # behalf of) the authorization identity.
+        #
+        # For example, an administrator or superuser might take on another role:
+        #
+        #     imap.authenticate "PLAIN", "root", passwd, authzid: "user"
         #
-        # If not explicitly provided, the server defaults to using the identity
-        # that was authenticated by the external credentials.
         attr_reader :authzid
 
         # :call-seq:
@@ -26,7 +34,9 @@ class ExternalAuthenticator
         # this, see Net::IMAP#authenticate or your client's authentication
         # method.
         #
-        # #authzid is an optional identity to act as or on behalf of.
+        # ==== Parameters
+        #
+        # * _optional_ #authzid  ― Authorization identity to act as or on behalf of.
         #
         # Any other keyword parameters are quietly ignored.
         def initialize(authzid: nil, **)
diff --git a/lib/net/imap/sasl/oauthbearer_authenticator.rb b/lib/net/imap/sasl/oauthbearer_authenticator.rb
@@ -14,18 +14,24 @@ module SASL
       class OAuthAuthenticator
         include GS2Header
 
-        # Authorization identity: an identity to act as or on behalf of.
+        # Authorization identity: an identity to act as or on behalf of.  The
+        # identity form is application protocol specific.  If not provided or
+        # left blank, the server derives an authorization identity from the
+        # authentication identity.  The server is responsible for verifying the
+        # client's credentials and verifying that the identity it associates
+        # with the client's authentication identity is allowed to act as (or on
+        # behalf of) the authorization identity.
+        #
+        # For example, an administrator or superuser might take on another role:
+        #
+        #     imap.authenticate "PLAIN", "root", passwd, authzid: "user"
         #
-        # If no explicit authorization identity is provided, it is usually
-        # derived from the authentication identity.  For the OAuth-based
-        # mechanisms, the authentication identity is the identity established by
-        # the OAuth credential.
         attr_reader :authzid
 
-        # Hostname to which the client connected.
+        # Hostname to which the client connected.  (optional)
         attr_reader :host
 
-        # Service port to which the client connected.
+        # Service port to which the client connected.  (optional)
         attr_reader :port
 
         # HTTP method.  (optional)
@@ -47,20 +53,22 @@ class OAuthAuthenticator
         # Creates an RFC7628[https://tools.ietf.org/html/rfc7628] OAuth
         # authenticator.
         #
-        # === Options
+        # ==== Parameters
         #
-        # See child classes for required configuration parameter(s).  The
-        # following parameters are all optional, but protocols or servers may
-        # add requirements for #authzid, #host, #port, or any other parameter.
+        # See child classes for required parameter(s).  The following parameters
+        # are all optional, but it is worth noting that <b>application protocols
+        # are allowed to require</b> #authzid (or other parameters, such as
+        # #host or #port) <b>as are specific server implementations</b>.
         #
-        # * #authzid ― Identity to act as or on behalf of.
-        # * #host — Hostname to which the client connected.
-        # * #port — Service port to which the client connected.
-        # * #mthd — HTTP method
-        # * #path — HTTP path data
-        # * #post — HTTP post data
-        # * #qs   — HTTP query string
+        # * _optional_ #authzid  ― Authorization identity to act as or on behalf of.
+        # * _optional_ #host — Hostname to which the client connected.
+        # * _optional_ #port — Service port to which the client connected.
+        # * _optional_ #mthd — HTTP method
+        # * _optional_ #path — HTTP path data
+        # * _optional_ #post — HTTP post data
+        # * _optional_ #qs   — HTTP query string
         #
+        # Any other keyword parameters are quietly ignored.
         def initialize(authzid: nil, host: nil, port: nil,
                        mthd: nil, path: nil, post: nil, qs: nil, **)
           @authzid = authzid
@@ -116,7 +124,7 @@ def authorization; raise "must be implemented by subclass" end
       # the bearer token.
       class OAuthBearerAuthenticator < OAuthAuthenticator
 
-        # An OAuth2 bearer token, generally the access token.
+        # An OAuth 2.0 bearer token.  See {RFC-6750}[https://www.rfc-editor.org/rfc/rfc6750]
         attr_reader :oauth2_token
 
         # :call-seq:
@@ -127,19 +135,22 @@ class OAuthBearerAuthenticator < OAuthAuthenticator
         #
         # Called by Net::IMAP#authenticate and similar methods on other clients.
         #
-        # === Options
+        # ==== Parameters
+        #
+        # * #oauth2_token — An OAuth2 bearer token
         #
-        # Only +oauth2_token+ is required by the mechanism, however protocols
-        # and servers may add requirements for #authzid, #host, #port, or any
-        # other parameter.
+        # All other keyword parameters are passed to
+        # {super}[rdoc-ref:OAuthAuthenticator::new] (see OAuthAuthenticator).
+        # The most common ones are:
         #
-        # * #oauth2_token — An OAuth2 bearer token or access token. *Required.*
-        #   May be provided as either regular or keyword argument.
-        # * #authzid ― Identity to act as or on behalf of.
-        # * #host — Hostname to which the client connected.
-        # * #port — Service port to which the client connected.
-        # * See OAuthAuthenticator documentation for less common parameters.
+        # * _optional_ #authzid  ― Authorization identity to act as or on behalf of.
+        # * _optional_ #host — Hostname to which the client connected.
+        # * _optional_ #port — Service port to which the client connected.
         #
+        # Although only oauth2_token is required by this mechanism, it is worth
+        # noting that <b><em>application protocols are allowed to
+        # require</em></b> #authzid (<em>or other parameters, such as</em> #host
+        # _or_ #port) <b><em>as are specific server implementations</em></b>.
         def initialize(oauth2_token_arg = nil, oauth2_token: nil, **args, &blk)
           super(**args, &blk) # handles authzid, host, port, etc
           oauth2_token && oauth2_token_arg and
diff --git a/lib/net/imap/sasl/plain_authenticator.rb b/lib/net/imap/sasl/plain_authenticator.rb
@@ -47,13 +47,17 @@ class Net::IMAP::SASL::PlainAuthenticator
   #
   # Called by Net::IMAP#authenticate and similar methods on other clients.
   #
-  # === Parameters
+  # ==== Parameters
   #
   # * #username ― Identity whose +password+ is used.
   # * #password ― Password or passphrase associated with this username+.
-  # * #authzid ― Alternate identity to act as or on behalf of.  Optional.
   #
-  # See attribute documentation for more details.
+  # * _optional_ #authzid  ― Authorization identity to act as or on behalf of.
+  #
+  #   When +authzid+ is not set, the server should derive the authorization
+  #   identity from the authentication identity.
+  #
+  # Any other keyword parameters are quietly ignored.
   def initialize(user = nil, pass = nil,
                  username: nil, password: nil, authzid: nil, **)
     [username, user].compact.count == 1 or
diff --git a/lib/net/imap/sasl/scram_authenticator.rb b/lib/net/imap/sasl/scram_authenticator.rb
@@ -70,10 +70,10 @@ class ScramAuthenticator
         #
         # * #username ― Identity whose #password is used.  Aliased as #authcid.
         # * #password ― Password or passphrase associated with this #username.
-        # * #authzid ― Alternate identity to act as or on behalf of.  Optional.
-        # * #min_iterations - Overrides the default value (4096).  Optional.
+        # * _optional_ #authzid ― Alternate identity to act as or on behalf of.
+        # * _optional_ #min_iterations - Overrides the default value (4096).
         #
-        # See the documentation on the corresponding attributes for more.
+        # Any other keyword parameters are quietly ignored.
         def initialize(username_arg = nil, password_arg = nil,
                        username: nil, password: nil, authcid: nil, authzid: nil,
                        min_iterations: 4096, # see both RFC5802 and RFC7677
@@ -96,6 +96,12 @@ def initialize(username_arg = nil, password_arg = nil,
         end
 
         # Authentication identity: the identity that matches the #password.
+        #
+        # RFC-2831[https://tools.ietf.org/html/rfc2831] uses the term +username+.
+        # "Authentication identity" is the generic term used by
+        # RFC-4422[https://tools.ietf.org/html/rfc4422].
+        # RFC-4616[https://tools.ietf.org/html/rfc4616] and many later RFCs abbreviate
+        # this to +authcid+.
         attr_reader :username
         alias authcid username
 
diff --git a/lib/net/imap/sasl/xoauth2_authenticator.rb b/lib/net/imap/sasl/xoauth2_authenticator.rb
@@ -6,9 +6,10 @@
 # Google[https://developers.google.com/gmail/imap/xoauth2-protocol] and
 # Microsoft[https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth].
 #
-# This mechanism requires an OAuth2 +access_token+ which has been authorized
-# with the appropriate OAuth2 scopes to access IMAP.  These scopes are not
-# standardized---consult each email service provider's documentation.
+# This mechanism requires an OAuth2 access token which has been authorized
+# with the appropriate OAuth2 scopes to access the user's services.  Most of
+# these scopes are not standardized---consult each service provider's
+# documentation for their scopes.
 #
 # Although this mechanism was never standardized and has been obsoleted by
 # "+OAUTHBEARER+", it is still very widely supported.
@@ -19,12 +20,18 @@ class Net::IMAP::SASL::XOAuth2Authenticator
   # It is unclear from {Google's original XOAUTH2
   # documentation}[https://developers.google.com/gmail/imap/xoauth2-protocol],
   # whether "User" refers to the authentication identity (+authcid+) or the
-  # authorization identity (+authzid+).  It appears to behave as +authzid+.
+  # authorization identity (+authzid+).  The authentication identity is
+  # established for the client by the OAuth token, so it seems that +username+
+  # must be the authorization identity.
   #
   # {Microsoft's documentation for shared
   # mailboxes}[https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth#sasl-xoauth2-authentication-for-shared-mailboxes-in-office-365]
-  # clearly indicate that the Office 365 server interprets it as the
+  # _clearly_ indicates that the Office 365 server interprets it as the
   # authorization identity.
+  #
+  # Although they _should_ validate that the token has been authorized to access
+  # the service for +username+, _some_ servers appear to ignore this field,
+  # relying only the identity and scope authorized by the token.
   attr_reader :username
 
   # An OAuth2 access token which has been authorized with the appropriate OAuth2
@@ -46,7 +53,7 @@ class Net::IMAP::SASL::XOAuth2Authenticator
   # * #oauth2_token --- An OAuth2.0 access token which is authorized to access
   #   the service for #username.
   #
-  # See the documentation for each attribute for more details.
+  # Any other keyword parameters are quietly ignored.
   def initialize(user = nil, token = nil, username: nil, oauth2_token: nil, **)
     @username = username || user or
       raise ArgumentError, "missing username"
@@ -62,7 +69,7 @@ def initialize(user = nil, token = nil, username: nil, oauth2_token: nil, **)
   # :call-seq:
   #   initial_response? -> true
   #
-  # +PLAIN+ can send an initial client response.
+  # +XOAUTH2+ can send an initial client response.
   def initial_response?; true end
 
   # Returns the XOAUTH2 formatted response, which combines the +username+

Original file line number	Diff line number	Diff line change
`@@ -29,8 +29,9 @@ class AnonymousAuthenticator`
`29`	`29`	`# this, see Net::IMAP#authenticate or your client's authentication`
`30`	`30`	`# method.`
`31`	`31`	`#`
`32`		`- # #anonymous_message is an optional message which is sent to the server.`
`33`		`- # It may be sent as a positional argument or as a keyword argument.`
	`32`	`+ # ==== Parameters`
	`33`	`+ #`
	`34`	`+ # * _optional_ #anonymous_message — a message to send to the server.`
`34`	`35`	`#`
`35`	`36`	`# Any other keyword arguments are silently ignored.`
`36`	`37`	`def initialize(anon_msg = nil, anonymous_message: nil, **)`
Original file line number	Diff line number	Diff line change
`@@ -47,13 +47,17 @@ class Net::IMAP::SASL::PlainAuthenticator`
`47`	`47`	`#`
`48`	`48`	`# Called by Net::IMAP#authenticate and similar methods on other clients.`
`49`	`49`	`#`
`50`		`- # === Parameters`
	`50`	`+ # ==== Parameters`
`51`	`51`	`#`
`52`	`52`	`# * #username ― Identity whose +password+ is used.`
`53`	`53`	`# * #password ― Password or passphrase associated with this username+.`
`54`		`- # * #authzid ― Alternate identity to act as or on behalf of. Optional.`
`55`	`54`	`#`
`56`		`- # See attribute documentation for more details.`
	`55`	`+ # * _optional_ #authzid ― Authorization identity to act as or on behalf of.`
	`56`	`+ #`
	`57`	`+ # When +authzid+ is not set, the server should derive the authorization`
	`58`	`+ # identity from the authentication identity.`
	`59`	`+ #`
	`60`	`+ # Any other keyword parameters are quietly ignored.`
`57`	`61`	`def initialize(user = nil, pass = nil,`
`58`	`62`	`username: nil, password: nil, authzid: nil, **)`
`59`	`63`	`[username, user].compact.count == 1 or`