net-imap 0.3.7 → 0.4.2

data/lib/net/imap/sasl/scram_authenticator.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+
+require_relative "gs2_header"
+require_relative "scram_algorithm"
+
+module Net
+  class IMAP
+    module SASL
+
+      # Abstract base class for the "+SCRAM-*+" family of SASL mechanisms,
+      # defined in RFC5802[https://tools.ietf.org/html/rfc5802].  Use via
+      # Net::IMAP#authenticate.
+      #
+      # Directly supported:
+      # * +SCRAM-SHA-1+   --- ScramSHA1Authenticator
+      # * +SCRAM-SHA-256+ --- ScramSHA256Authenticator
+      #
+      # New +SCRAM-*+ mechanisms can easily be added for any hash algorithm
+      # supported by
+      # OpenSSL::Digest[https://ruby.github.io/openssl/OpenSSL/Digest.html].
+      # Subclasses need only set an appropriate +DIGEST_NAME+ constant.
+      #
+      # === SCRAM algorithm
+      #
+      # See the documentation and method definitions on ScramAlgorithm for an
+      # overview of the algorithm.  The different mechanisms differ only by
+      # which hash function that is used (or by support for channel binding with
+      # +-PLUS+).
+      #
+      # See also the methods on GS2Header.
+      #
+      # ==== Server messages
+      #
+      # As server messages are received, they are validated and loaded into
+      # the various attributes, e.g: #snonce, #salt, #iterations, #verifier,
+      # #server_error, etc.
+      #
+      # Unlike many other SASL mechanisms, the +SCRAM-*+ family supports mutual
+      # authentication and can return server error data in the server messages.
+      # If #process raises an Error for the server-final-message, then
+      # server_error may contain error details.
+      #
+      # === TLS Channel binding
+      #
+      # <em>The <tt>SCRAM-*-PLUS</tt> mechanisms and channel binding are not
+      # supported yet.</em>
+      #
+      # === Caching SCRAM secrets
+      #
+      # <em>Caching of salted_password, client_key, stored_key, and server_key
+      # is not supported yet.</em>
+      #
+      class ScramAuthenticator
+        include GS2Header
+        include ScramAlgorithm
+
+        # :call-seq:
+        #   new(username,  password,  **options) -> auth_ctx
+        #   new(username:, password:, **options) -> auth_ctx
+        #   new(authcid:,  password:, **options) -> auth_ctx
+        #
+        # Creates an authenticator for one of the "+SCRAM-*+" SASL mechanisms.
+        # Each subclass defines #digest to match a specific mechanism.
+        #
+        # Called by Net::IMAP#authenticate and similar methods on other clients.
+        #
+        # === Parameters
+        #
+        # * #authcid  ― Identity whose #password is used.
+        #
+        #   #username - An alias for #authcid.
+        # * #password ― Password or passphrase associated with this #username.
+        # * _optional_ #authzid ― Alternate identity to act as or on behalf of.
+        # * _optional_ #min_iterations - Overrides the default value (4096).
+        #
+        # Any other keyword parameters are quietly ignored.
+        def initialize(username_arg = nil, password_arg = nil,
+                       authcid: nil, username: nil,
+                       authzid: nil,
+                       password: nil, secret: nil,
+                       min_iterations: 4096, # see both RFC5802 and RFC7677
+                       cnonce: nil, # must only be set in tests
+                       **options)
+          @username = username || username_arg || authcid or
+            raise ArgumentError, "missing username (authcid)"
+          @password = password || secret || password_arg or
+            raise ArgumentError, "missing password"
+          @authzid = authzid
+
+          @min_iterations = Integer min_iterations
+          @min_iterations.positive? or
+            raise ArgumentError, "min_iterations must be positive"
+
+          @cnonce = cnonce || SecureRandom.base64(32)
+        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
+
+        # A password or passphrase that matches the #username.
+        attr_reader :password
+        alias secret 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.  For example, an administrator or superuser
+        # might take on another role:
+        #
+        #     imap.authenticate "SCRAM-SHA-256", "root", passwd, authzid: "user"
+        #
+        # 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.
+        attr_reader :authzid
+
+        # The minimal allowed iteration count.  Lower #iterations will raise an
+        # Error.
+        attr_reader :min_iterations
+
+        # The client nonce, generated by SecureRandom
+        attr_reader :cnonce
+
+        # The server nonce, which must start with #cnonce
+        attr_reader :snonce
+
+        # The salt used by the server for this user
+        attr_reader :salt
+
+        # The iteration count for the selected hash function and user
+        attr_reader :iterations
+
+        # An error reported by the server during the \SASL exchange.
+        #
+        # Does not include errors reported by the protocol, e.g.
+        # Net::IMAP::NoResponseError.
+        attr_reader :server_error
+
+        # Returns a new OpenSSL::Digest object, set to the appropriate hash
+        # function for the chosen mechanism.
+        #
+        # <em>The class's +DIGEST_NAME+ constant must be set to the name of an
+        # algorithm supported by OpenSSL::Digest.</em>
+        def digest; OpenSSL::Digest.new self.class::DIGEST_NAME end
+
+        # See {RFC5802 §7}[https://www.rfc-editor.org/rfc/rfc5802#section-7]
+        # +client-first-message+.
+        def initial_client_response
+          "#{gs2_header}#{client_first_message_bare}"
+        end
+
+        # responds to the server's challenges
+        def process(challenge)
+          case (@state ||= :initial_client_response)
+          when :initial_client_response
+            initial_client_response.tap { @state = :server_first_message }
+          when :server_first_message
+            recv_server_first_message challenge
+            final_message_with_proof.tap { @state = :server_final_message }
+          when :server_final_message
+            recv_server_final_message challenge
+            "".tap { @state = :done }
+          else
+            raise Error, "server sent after complete, %p" % [challenge]
+          end
+        rescue Exception => ex
+          @state = ex
+          raise
+        end
+
+        # Is the authentication exchange complete?
+        #
+        # If false, another server continuation is required.
+        def done?; @state == :done end
+
+        private
+
+        # Need to store this for auth_message
+        attr_reader :server_first_message
+
+        def format_message(hash) hash.map { _1.join("=") }.join(",") end
+
+        def recv_server_first_message(server_first_message)
+          @server_first_message = server_first_message
+          sparams = parse_challenge server_first_message
+          @snonce = sparams["r"] or
+            raise Error, "server did not send nonce"
+          @salt = sparams["s"]&.unpack1("m") or
+            raise Error, "server did not send salt"
+          @iterations = sparams["i"]&.then {|i| Integer i } or
+            raise Error, "server did not send iteration count"
+          min_iterations <= iterations or
+            raise Error, "too few iterations: %d" % [iterations]
+          mext = sparams["m"] and
+            raise Error, "mandatory extension: %p" % [mext]
+          snonce.start_with? cnonce or
+            raise Error, "invalid server nonce"
+        end
+
+        def recv_server_final_message(server_final_message)
+          sparams = parse_challenge server_final_message
+          @server_error = sparams["e"] and
+            raise Error, "server error: %s" % [server_error]
+          verifier = sparams["v"].unpack1("m") or
+            raise Error, "server did not send verifier"
+          verifier == server_signature or
+            raise Error, "server verify failed: %p != %p" % [
+              server_signature, verifier
+            ]
+        end
+
+        # See {RFC5802 §7}[https://www.rfc-editor.org/rfc/rfc5802#section-7]
+        # +client-first-message-bare+.
+        def client_first_message_bare
+          @client_first_message_bare ||=
+            format_message(n: gs2_saslname_encode(SASL.saslprep(username)),
+                           r: cnonce)
+        end
+
+        # See {RFC5802 §7}[https://www.rfc-editor.org/rfc/rfc5802#section-7]
+        # +client-final-message+.
+        def final_message_with_proof
+          proof = [client_proof].pack("m0")
+          "#{client_final_message_without_proof},p=#{proof}"
+        end
+
+        # See {RFC5802 §7}[https://www.rfc-editor.org/rfc/rfc5802#section-7]
+        # +client-final-message-without-proof+.
+        def client_final_message_without_proof
+          @client_final_message_without_proof ||=
+            format_message(c: [cbind_input].pack("m0"), # channel-binding
+                           r: snonce)                   # nonce
+        end
+
+        # See {RFC5802 §7}[https://www.rfc-editor.org/rfc/rfc5802#section-7]
+        # +cbind-input+.
+        #
+        # >>>
+        #   *TODO:* implement channel binding, appending +cbind-data+ here.
+        alias cbind_input gs2_header
+
+        # RFC5802 specifies "that the order of attributes in client or server
+        # messages is fixed, with the exception of extension attributes", but
+        # this parses it simply as a hash, without respect to order.  Note that
+        # repeated keys (violating the spec) will use the last value.
+        def parse_challenge(challenge)
+          challenge.split(/,/).to_h {|pair| pair.split(/=/, 2) }
+        rescue ArgumentError
+          raise Error, "unparsable challenge: %p" % [challenge]
+        end
+
+      end
+
+      # Authenticator for the "+SCRAM-SHA-1+" SASL mechanism, defined in
+      # RFC5802[https://tools.ietf.org/html/rfc5802].
+      #
+      # Uses the "SHA-1" digest algorithm from OpenSSL::Digest.
+      #
+      # See ScramAuthenticator.
+      class ScramSHA1Authenticator < ScramAuthenticator
+        DIGEST_NAME = "SHA1"
+      end
+
+      # Authenticator for the "+SCRAM-SHA-256+" SASL mechanism, defined in
+      # RFC7677[https://tools.ietf.org/html/rfc7677].
+      #
+      # Uses the "SHA-256" digest algorithm from OpenSSL::Digest.
+      #
+      # See ScramAuthenticator.
+      class ScramSHA256Authenticator < ScramAuthenticator
+        DIGEST_NAME = "SHA256"
+      end
+
+    end
+  end
+end

data/lib/net/imap/sasl/stringprep.rb

@@ -1,72 +1,12 @@
 # frozen_string_literal: true
 
-require_relative "stringprep_tables"
-
 module Net::IMAP::SASL
 
-  # Regexps and utility methods for implementing stringprep profiles.  The
-  # \StringPrep algorithm is defined by
-  # {RFC-3454}[https://www.rfc-editor.org/rfc/rfc3454.html].  Each
-  # codepoint table defined in the RFC-3454 appendices is matched by a Regexp
-  # defined in this module.
-  #--
-  # TODO: generic StringPrep mapping (not needed for SASLprep implementation)
-  #++
-  module StringPrep
-
-    # Returns a Regexp matching the given +table+ name.
-    def self.[](table)
-      TABLE_REGEXPS.fetch(table)
-    end
-
-    module_function
-
-    # Checks +string+ for any codepoint in +tables+. Raises a
-    # ProhibitedCodepoint describing the first matching table.
-    #
-    # Also checks bidirectional characters, when <tt>bidi: true</tt>, which may
-    # raise a BidiStringError.
-    #
-    # +profile+ is an optional string which will be added to any exception that
-    # is raised (it does not affect behavior).
-    def check_prohibited!(string, *tables, bidi: false, profile: nil)
-      tables = TABLE_TITLES.keys.grep(/^C/) if tables.empty?
-      tables |= %w[C.8] if bidi
-      table = tables.find {|t| TABLE_REGEXPS[t].match?(string) }
-      raise ProhibitedCodepoint.new(
-        table, string: string, profile: nil
-      ) if table
-      check_bidi!(string, profile: profile) if bidi
-    end
-
-    # Checks that +string+ obeys all of the "Bidirectional Characters"
-    # requirements in RFC-3454, §6:
-    #
-    # * The characters in \StringPrep\[\"C.8\"] MUST be prohibited
-    # * If a string contains any RandALCat character, the string MUST NOT
-    #   contain any LCat character.
-    # * If a string contains any RandALCat character, a RandALCat
-    #   character MUST be the first character of the string, and a
-    #   RandALCat character MUST be the last character of the string.
-    #
-    # This is usually combined with #check_prohibited!, so table "C.8" is only
-    # checked when <tt>c_8: true</tt>.
-    #
-    # Raises either ProhibitedCodepoint or BidiStringError unless all
-    # requirements are met.  +profile+ is an optional string which will be
-    # added to any exception that is raised (it does not affect behavior).
-    def check_bidi!(string, c_8: false, profile: nil)
-      check_prohibited!(string, "C.8", profile: profile) if c_8
-      if BIDI_FAILS_REQ2.match?(string)
-        raise BidiStringError.new(
-          BIDI_DESC_REQ2, string: string, profile: profile,
-        )
-      elsif BIDI_FAILS_REQ3.match?(string)
-        raise BidiStringError.new(
-          BIDI_DESC_REQ3, string: string, profile: profile,
-        )
-      end
-    end
+  # Alias for Net::IMAP::StringPrep::SASLprep.
+  SASLprep            = Net::IMAP::StringPrep::SASLprep
+  StringPrep          = Net::IMAP::StringPrep                      # :nodoc:
+  BidiStringError     = Net::IMAP::StringPrep::BidiStringError     # :nodoc:
+  ProhibitedCodepoint = Net::IMAP::StringPrep::ProhibitedCodepoint # :nodoc:
+  StringPrepError     = Net::IMAP::StringPrep::StringPrepError     # :nodoc:
 
-  end
 end

data/lib/net/imap/sasl/xoauth2_authenticator.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# Authenticator for the "+XOAUTH2+" SASL mechanism.  This mechanism was
+# originally created for GMail and widely adopted by hosted email providers.
+# +XOAUTH2+ has been documented by
+# 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 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.
+#
+# See Net::IMAP::SASL:: OAuthBearerAuthenticator.
+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+).  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_ 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
+
+  # Note that, unlike most other authenticators, #username is an alias for the
+  # authorization identity and not the authentication identity.  The
+  # authenticated identity is established for the client by the #oauth2_token.
+  alias authzid username
+
+  # An OAuth2 access token which has been authorized with the appropriate OAuth2
+  # scopes to use the service for #username.
+  attr_reader :oauth2_token
+  alias secret oauth2_token
+
+  # :call-seq:
+  #   new(username,  oauth2_token,  **) -> authenticator
+  #   new(username:, oauth2_token:, **) -> authenticator
+  #   new(authzid:,  oauth2_token:, **) -> authenticator
+  #
+  # Creates an Authenticator for the "+XOAUTH2+" SASL mechanism, as specified by
+  # Google[https://developers.google.com/gmail/imap/xoauth2-protocol],
+  # Microsoft[https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth]
+  # and Yahoo[https://senders.yahooinc.com/developer/documentation].
+  #
+  # === Properties
+  #
+  # * #username --- the username for the account being accessed.
+  #
+  #   #authzid  --- an alias for #username.
+  #
+  #   Note that, unlike some other authenticators, +username+ sets the
+  #   _authorization_ identity and not the _authentication_ identity.  The
+  #   authenticated identity is established for the client with the OAuth token.
+  #
+  # * #oauth2_token --- An OAuth2.0 access token which is authorized to access
+  #   the service for #username.
+  #
+  # Any other keyword parameters are quietly ignored.
+  def initialize(user = nil, token = nil, username: nil, oauth2_token: nil,
+                 authzid: nil, secret: nil, **)
+    @username = authzid || username || user or
+      raise ArgumentError, "missing username (authzid)"
+    @oauth2_token = oauth2_token || secret || token or
+      raise ArgumentError, "missing oauth2_token"
+    @done = false
+  end
+
+  # :call-seq:
+  #   initial_response? -> true
+  #
+  # +XOAUTH2+ can send an initial client response.
+  def initial_response?; true end
+
+  # Returns the XOAUTH2 formatted response, which combines the +username+
+  # with the +oauth2_token+.
+  def process(_data)
+    build_oauth2_string(@username, @oauth2_token)
+  ensure
+    @done = true
+  end
+
+  # Returns true when the initial client response was sent.
+  #
+  # The authentication should not succeed unless this returns true, but it
+  # does *not* indicate success.
+  def done?; @done end
+
+  private
+
+  def build_oauth2_string(username, oauth2_token)
+    format("user=%s\1auth=Bearer %s\1\1", username, oauth2_token)
+  end
+
+end