♻️ SASL CRAM-MD5: Add "#done?", moved to SASL

The protocol client is responsible for raising an error if the command
completes successfully but "done?" returns false.

Also moved to sasl dir and SASL module, and deprecated the old constant.

Other than one or two minor stylistic changes, the code was left the
same as before.  This mechanism has not been updated to inherit from
SASL::Authenticator.

Author: nevans

lib/net/imap/authenticators/cram_md5.rb

@@ -65,6 +65,7 @@ module SASL
       autoload :PlainAuthenticator,       "#{sasl_dir}/plain_authenticator"
       autoload :XOAuth2Authenticator,     "#{sasl_dir}/xoauth2_authenticator"
 
+      autoload :CramMD5Authenticator,     "#{sasl_dir}/cram_md5_authenticator"
       autoload :DigestMD5Authenticator,   "#{sasl_dir}/digest_md5_authenticator"
 
       # Authenticators are all lazy loaded
@@ -73,7 +74,7 @@ def self.authenticators
           registry.add_authenticator "Plain"
           registry.add_authenticator "XOAuth2"
           registry.add_authenticator "Login",      LoginAuthenticator     # deprecated
-          registry.add_authenticator "Cram-MD5",   CramMD5Authenticator   # deprecated
+          registry.add_authenticator "Cram-MD5"   # deprecated
           registry.add_authenticator "Digest-MD5" # deprecated
         end
       end
@@ -106,4 +107,3 @@ def saslprep(string, **opts)
 end
 
 require_relative "authenticators/login"
-require_relative "authenticators/cram_md5"

lib/net/imap/sasl.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP < Protocol
+    module SASL
+
+      # Authenticator for the "+CRAM-MD5+" SASL mechanism, specified in
+      # RFC2195[https://tools.ietf.org/html/rfc2195].  See Net::IMAP#authenticate.
+      #
+      # == Deprecated
+      #
+      # +CRAM-MD5+ is obsolete and insecure.  It is included for compatibility with
+      # existing servers.
+      # {draft-ietf-sasl-crammd5-to-historic}[https://tools.ietf.org/html/draft-ietf-sasl-crammd5-to-historic-00.html]
+      # recommends using +SCRAM-*+ or +PLAIN+ protected by TLS instead.
+      #
+      # Additionally, RFC8314[https://tools.ietf.org/html/rfc8314] discourage the use
+      # of cleartext and recommends TLS version 1.2 or greater be used for all
+      # traffic.  With TLS +CRAM-MD5+ is okay, but so is +PLAIN+
+      class CramMD5Authenticator
+        def process(challenge)
+          digest = hmac_md5(challenge, @password)
+          @user + " " + digest
+        ensure
+          @done = true
+        end
+
+        def done?; @done end
+
+        private
+
+        def initialize(user, password, warn_deprecation: true, **_ignored)
+          if warn_deprecation
+            warn "WARNING: CRAM-MD5 mechanism is deprecated." # TODO: recommend SCRAM
+          end
+          require "digest/md5"
+          @user = user
+          @password = password
+          @done = false
+        end
+
+        def hmac_md5(text, key)
+          if key.length > 64
+            key = Digest::MD5.digest(key)
+          end
+
+          k_ipad = key + "\0" * (64 - key.length)
+          k_opad = key + "\0" * (64 - key.length)
+          (0..63).each do |i|
+            k_ipad[i] = (k_ipad[i].ord ^ 0x36).chr
+            k_opad[i] = (k_opad[i].ord ^ 0x5c).chr
+          end
+
+          digest = Digest::MD5.digest(k_ipad + text)
+
+          Digest::MD5.hexdigest(k_opad + digest)
+        end
+
+      end
+    end
+
+    CramMD5Authenticator = SASL::CramMD5Authenticator # :nodoc:
+    deprecate_constant :CramMD5Authenticator
+
+  end
+end

lib/net/imap/sasl/cram_md5_authenticator.rb

@@ -123,7 +123,7 @@ def cram_md5(*args, warn_deprecation: false, **kwargs, &block)
   end
 
   def test_cram_md5_authenticator_matches_mechanism
-    assert_kind_of(Net::IMAP::CramMD5Authenticator, cram_md5("n", "p"))
+    assert_kind_of(Net::IMAP::SASL::CramMD5Authenticator, cram_md5("n", "p"))
   end
 
   def test_cram_md5_authenticator_deprecated