✨ SASL SCRAM-SHA-*: Add mechanisms [🚧 more tests, credit]

Also, don't forget to credit the PR on net-sasl for getting this
started!

Author: nevans

lib/net/imap/sasl.rb

@@ -33,6 +33,16 @@ class IMAP
     # +PLAIN+::       See PlainAuthenticator.
     #                 Login using clear-text username and password.
     #
+    # +SCRAM-SHA-1+, +SCRAM-SHA-256+::
+    #                 See ScramAuthenticator.
+    #                 Login by username and password.  The password is not sent
+    #                 to the server but is used in a salted challenge/response
+    #                 exchange.  One of the benefits over +PLAIN+ is that the
+    #                 server cannot impersonate the user to other servers.
+    #                 +SCRAM-SHA-1+ and +SCRAM-SHA-256+ are supported, but any
+    #                 algorithm supported by OpenSSL::Digest can easily be
+    #                 added.
+    #
     # +OAUTHBEARER+:: See OAuthBearerAuthenticator.
     #                 Login using an OAUTH2 Bearer token.  This is the
     #                 standard mechanism for using OAuth2 with \SASL, but it
@@ -77,10 +87,15 @@ module SASL
       autoload :Authenticator,            "#{sasl_dir}/authenticator"
       autoload :Authenticators,           "#{sasl_dir}/authenticators"
       autoload :GS2Header,                "#{sasl_dir}/gs2_header"
+      autoload :ScramAlgorithm,           "#{sasl_dir}/scram_algorithm"
+      autoload :ScramAuthenticator,       "#{sasl_dir}/scram_authenticator"
+
       autoload :AnonymousAuthenticator,   "#{sasl_dir}/anonymous_authenticator"
       autoload :ExternalAuthenticator,    "#{sasl_dir}/external_authenticator"
       autoload :OAuthBearerAuthenticator, "#{sasl_dir}/oauthbearer_authenticator"
       autoload :PlainAuthenticator,       "#{sasl_dir}/plain_authenticator"
+      autoload :ScramSHA1Authenticator,   "#{sasl_dir}/scram_sha1_authenticator"
+      autoload :ScramSHA256Authenticator, "#{sasl_dir}/scram_sha256_authenticator"
       autoload :XOAuth2Authenticator,     "#{sasl_dir}/xoauth2_authenticator"
 
       autoload :CramMD5Authenticator,     "#{sasl_dir}/cram_md5_authenticator"
@@ -94,6 +109,8 @@ def self.authenticators
           registry.add_authenticator "External"
           registry.add_authenticator "OAuthBearer"
           registry.add_authenticator "Plain"
+          registry.add_authenticator "Scram-SHA-1"
+          registry.add_authenticator "Scram-SHA-256"
           registry.add_authenticator "XOAuth2"
           registry.add_authenticator "Login"      # deprecated
           registry.add_authenticator "Cram-MD5"   # deprecated

lib/net/imap/sasl/authenticator.rb

@@ -59,7 +59,6 @@ module SASL
       # * +scram_sha1_salted_passwords+, +scram_sha256_salted_password+ ---
       #   Salted password(s) (with salt and iteration count) for the +SCRAM-*+
       #   mechanism family.  <tt>[salt, iterations, pbkdf2_hmac]</tt> tuple.
-      #   <em>(not implemented yet...)</em>
       # * +passcode+ --- passcode for SecurID 2FA <em>(not implemented)</em>
       # * +pin+ --- Personal Identification number, e.g. for SecurID 2FA
       #   <em>(not implemented)</em>

lib/net/imap/sasl/scram_algorithm.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    module SASL
+
+      # For method descriptions, see {RFC5802
+      # §2}[https://www.rfc-editor.org/rfc/rfc5802#section-2] and {RFC5802
+      # §3}[https://www.rfc-editor.org/rfc/rfc5802#section-3].
+      #
+      # Expects:
+      # * #Hi, #H, and #HMAC use:
+      #   * +#digest+ --- an OpenSSL::Digest.
+      # * #salted_password uses:
+      #   * +#salt+ and +#iterations+ --- the server's values for this user
+      #   * +#password+
+      # * #auth_message is built from:
+      #   * +#client_first_message_bare+     --- contains +#cnonce+
+      #   * +#server_first_message+          --- contains +#snonce+
+      #   * +#client_final_message_no_proof+ --- contains +#snonce+
+      module ScramAlgorithm
+        def Normalize(str) SASL.saslprep(str) end
+
+        def Hi(str, salt, iterations)
+          length = digest.digest_length
+          OpenSSL::KDF.pbkdf2_hmac(
+            str,
+            salt:       salt,
+            iterations: iterations,
+            length: length,
+            hash: digest,
+          )
+        end
+
+        def H(str) digest.digest str end
+
+        def HMAC(key, data) OpenSSL::HMAC.digest(digest, key, data) end
+
+        def XOR(str1, str2)
+          str1.unpack("C*")
+            .zip(str2.unpack("C*"))
+            .map {|a, b| a ^ b }
+            .pack("C*")
+        end
+
+        def auth_message
+          [
+            client_first_message_bare,
+            server_first_message,
+            client_final_message_no_proof,
+          ]
+            .join(",")
+        end
+
+        def salted_password
+          Hi(Normalize(password), salt, iterations)
+        end
+
+        def client_key;       HMAC(salted_password, "Client Key") end
+        def server_key;       HMAC(salted_password, "Server Key") end
+        def stored_key;       H(client_key)                       end
+        def client_signature; HMAC(stored_key, auth_message)      end
+        def server_signature; HMAC(server_key, auth_message)      end
+        def client_proof;     XOR(client_key, client_signature)   end
+      end
+
+    end
+  end
+end