🔒 SASL PLAIN: Refactor and document

Author: nevans

lib/net/imap/sasl/plain_authenticator.rb

@@ -1,42 +1,95 @@
 # frozen_string_literal: true
 
 # Authenticator for the "+PLAIN+" SASL mechanism, specified in
-# RFC4616[https://tools.ietf.org/html/rfc4616].  See Net::IMAP#authenticate.
+# RFC-4616[https://tools.ietf.org/html/rfc4616].  See Net::IMAP#authenticate.
 #
 # +PLAIN+ authentication sends the password in cleartext.
-# RFC3501[https://tools.ietf.org/html/rfc3501] encourages servers to disable
+# RFC-3501[https://tools.ietf.org/html/rfc3501] encourages servers to disable
 # cleartext authentication until after TLS has been negotiated.
-# RFC8314[https://tools.ietf.org/html/rfc8314] recommends TLS version 1.2 or
+# RFC-8314[https://tools.ietf.org/html/rfc8314] recommends TLS version 1.2 or
 # greater be used for all traffic, and deprecate cleartext access ASAP.  +PLAIN+
 # can be secured by TLS encryption.
 class Net::IMAP::SASL::PlainAuthenticator
 
+  ##
+  # :call-seq:
+  #   new(username, password,  authzid = nil, **)   -> auth_ctx
+  #   new(authcid:, password:, authzid: nil, **)    -> auth_ctx
+  #
+  # Creates an Authenticator for the "+PLAIN+" SASL mechanism.
+  #
+  # Called by Net::IMAP#authenticate and similar methods on other clients.
+  #
+  # === Properties
+  #
+  # * #authcid ― Identity whose #password is used.  Aliased as #username.
+  # * #password ― Password or passphrase associated with this #authcid.
+  # * #authzid ― Alternate identity to act as or on behalf of.  Optional.
+  #
+  # See the documentation on each attribute for more details.
+  #
+  # All three properties may be sent as either positional or keyword arguments.
+  def initialize(username_arg = nil, password_arg = nil, authzid_arg = nil,
+                 authcid: nil, username: nil, password: nil, authzid: nil, **)
+    @authcid  = authcid  || username || username_arg
+    @password = password || password_arg
+    @authzid  = authzid  || authzid_arg
+    @authcid  or raise ArgumentError, "missing authcid (username)"
+    @password or raise ArgumentError, "missing password"
+    [authcid, username, username_arg].compact.count == 1 or
+      raise ArgumentError, "conflicting values for authcid (username)"
+    [password, password_arg].compact.count == 1 or
+      raise ArgumentError, "conflicting values for password (username)"
+    [authzid, authzid_arg].compact.count <= 1 or
+      raise ArgumentError, "conflicting values for authzid (username)"
+    guard_against_null_char(:authcid,  @authcid)
+    guard_against_null_char(:authzid,  @authzid)
+    guard_against_null_char(:password, @password)
+  end
+
+  # :call-seq:
+  #   initial_response? -> true
+  #
+  # +PLAIN+ can send an initial client response.
   def initial_response?; true end
 
-  def process(data)
-    return "#@authzid\0#@username\0#@password"
-  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
+  # to +authcid+.  #username is available as an alias for #authcid, but only
+  # <tt>:authcid</tt> will be sent to callbacks.
+  attr_reader :authcid
+  alias username authcid
 
-  # :nodoc:
-  NULL = -"\0".b
+  # A password or passphrase that matches the #authcid.
+  attr_reader :password
+
+  # 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"
+  #
+  attr_reader :authzid
+
+  # Responds with the client's credentials.
+  def process(data) [authzid, authcid, password].join("\0") end
 
   private
 
-  # +username+ is the authentication identity, the identity whose +password+ is
-  # used.  +username+ is referred to as +authcid+ by
-  # RFC4616[https://tools.ietf.org/html/rfc4616].
-  #
-  # +authzid+ is the authorization identity (identity to act as).  It can
-  # usually be left blank. When +authzid+ is left blank (nil or empty string)
-  # the server will derive an identity from the credentials and use that as the
-  # authorization identity.
-  def initialize(username, password, authzid: nil)
-    raise ArgumentError, "username contains NULL" if username&.include?(NULL)
-    raise ArgumentError, "password contains NULL" if password&.include?(NULL)
-    raise ArgumentError, "authzid  contains NULL" if authzid&.include?(NULL)
-    @username = username
-    @password = password
-    @authzid  = authzid
+  NULL = -"\0".b
+  private_constant :NULL
+
+  def guard_against_null_char(name, value)
+    raise ArgumentError, "#{name} contains NULL"  if value&.include?(NULL)
   end
 
 end

test/net/imap/test_imap_authenticators.rb

@@ -46,6 +46,8 @@ def test_plain_supports_initial_response
 
   def test_plain_response
     assert_equal("\0authc\0passwd", plain("authc", "passwd").process(nil))
+    assert_equal("authz\0user\0pass",
+                 plain("user", "pass", "authz").process(nil))
     assert_equal("authz\0user\0pass",
                  plain("user", "pass", authzid: "authz").process(nil))
   end