♻️ 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.rb

@@ -1000,7 +1000,7 @@ def starttls(options = {}, verify = true)
     #
     #   For +LOGIN+, see LoginAuthenticator.
     #
-    #   For +CRAM-MD5+, see CramMD5Authenticator.
+    #   For +CRAM-MD5+, see SASL::CramMD5Authenticator.
     #
     #   <em>Using a deprecated mechanism will print a warning.</em>
     #

lib/net/imap/authenticators.rb

@@ -72,5 +72,5 @@ def authenticators
 
 # deprecated
 require_relative "authenticators/login"
-require_relative "authenticators/cram_md5"
+require_relative "sasl/cram_md5_authenticator"
 require_relative "sasl/digest_md5_authenticator"

lib/net/imap/authenticators/cram_md5.rb

@@ -35,7 +35,7 @@ module SASL
       #
       #   For +LOGIN+, see LoginAuthenticator.
       #
-      #   For +CRAM-MD5+, see CramMD5Authenticator.
+      #   For +CRAM-MD5+, see SASL::CramMD5Authenticator.
       #
       #   <em>Using a deprecated mechanism will print a warning.</em>
       #

lib/net/imap/sasl/authenticator.rb

@@ -0,0 +1,67 @@
+# 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
+
+        Net::IMAP.add_authenticator "CRAM-MD5", self
+      end
+    end
+
+    CramMD5Authenticator = SASL::CramMD5Authenticator # :nodoc:
+    deprecate_constant :CramMD5Authenticator
+
+  end
+end

lib/net/imap/sasl/cram_md5_authenticator.rb

@@ -117,7 +117,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