net-imap 0.3.4 → 0.5.6

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP < Protocol
+    module SASL
+
+      # Authenticator for the "+ANONYMOUS+" SASL mechanism, as specified by
+      # RFC-4505[https://www.rfc-editor.org/rfc/rfc4505].  See
+      # Net::IMAP#authenticate.
+      class AnonymousAuthenticator
+
+        # An optional token sent for the +ANONYMOUS+ mechanism., up to 255 UTF-8
+        # characters in length.
+        #
+        # If it contains an "@" sign, the message must be a valid email address
+        # (+addr-spec+ from RFC-2822[https://www.rfc-editor.org/rfc/rfc2822]).
+        # Email syntax is _not_ validated by AnonymousAuthenticator.
+        #
+        # Otherwise, it can be any UTF8 string which is permitted by the
+        # StringPrep::Trace profile.
+        attr_reader :anonymous_message
+
+        # :call-seq:
+        #   new(anonymous_message = "", **) -> authenticator
+        #   new(anonymous_message:  "", **) -> authenticator
+        #
+        # Creates an Authenticator for the "+ANONYMOUS+" SASL mechanism, as
+        # specified in RFC-4505[https://www.rfc-editor.org/rfc/rfc4505].  To use
+        # this, see Net::IMAP#authenticate or your client's authentication
+        # method.
+        #
+        # ==== Parameters
+        #
+        # * _optional_ #anonymous_message — a message to send to the server.
+        #
+        # Any other keyword arguments are silently ignored.
+        def initialize(anon_msg = nil, anonymous_message: nil, **)
+          message = (anonymous_message || anon_msg || "").to_str
+          @anonymous_message = StringPrep::Trace.stringprep_trace message
+          if (size = @anonymous_message&.length)&.> 255
+            raise ArgumentError,
+                  "anonymous_message is too long.  (%d codepoints)" % [size]
+          end
+          @done = false
+        end
+
+        # :call-seq:
+        #   initial_response? -> true
+        #
+        # +ANONYMOUS+ can send an initial client response.
+        def initial_response?; true end
+
+        # Returns #anonymous_message.
+        def process(_server_challenge_string)
+          anonymous_message
+        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
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    module SASL
+
+      # AuthenticationExchange is used internally by Net::IMAP#authenticate.
+      # But the API is still *experimental*, and may change.
+      #
+      # TODO: catch exceptions in #process and send #cancel_response.
+      # TODO: raise an error if the command succeeds after being canceled.
+      # TODO: use with more clients, to verify the API can accommodate them.
+      # TODO: pass ClientAdapter#service to SASL.authenticator
+      #
+      # An AuthenticationExchange represents a single attempt to authenticate
+      # a SASL client to a SASL server.  It is created from a client adapter, a
+      # mechanism name, and a mechanism authenticator.  When #authenticate is
+      # called, it will send the appropriate authenticate command to the server,
+      # returning the client response on success and raising an exception on
+      # failure.
+      #
+      # In most cases, the client will not need to use
+      # SASL::AuthenticationExchange directly at all.  Instead, use
+      # SASL::ClientAdapter#authenticate.  If customizations are needed, the
+      # custom client adapter is probably the best place for that code.
+      #
+      #     def authenticate(...)
+      #       MyClient::SASLAdapter.new(self).authenticate(...)
+      #     end
+      #
+      # SASL::ClientAdapter#authenticate delegates to ::authenticate, like so:
+      #
+      #     def authenticate(...)
+      #       sasl_adapter = MyClient::SASLAdapter.new(self)
+      #       SASL::AuthenticationExchange.authenticate(sasl_adapter, ...)
+      #     end
+      #
+      # ::authenticate simply delegates to ::build and #authenticate, like so:
+      #
+      #     def authenticate(...)
+      #       sasl_adapter = MyClient::SASLAdapter.new(self)
+      #       SASL::AuthenticationExchange
+      #         .build(sasl_adapter, ...)
+      #         .authenticate
+      #     end
+      #
+      # And ::build delegates to SASL.authenticator and ::new, like so:
+      #
+      #     def authenticate(mechanism, ...)
+      #       sasl_adapter = MyClient::SASLAdapter.new(self)
+      #       authenticator = SASL.authenticator(mechanism, ...)
+      #       SASL::AuthenticationExchange
+      #         .new(sasl_adapter, mechanism, authenticator)
+      #         .authenticate
+      #     end
+      #
+      class AuthenticationExchange
+        # Convenience method for <tt>build(...).authenticate</tt>
+        #
+        # See also: SASL::ClientAdapter#authenticate
+        def self.authenticate(...) build(...).authenticate end
+
+        # Convenience method to combine the creation of a new authenticator and
+        # a new Authentication exchange.
+        #
+        # +client+ must be an instance of SASL::ClientAdapter.
+        #
+        # +mechanism+ must be a SASL mechanism name, as a string or symbol.
+        #
+        # +sasl_ir+ allows or disallows sending an "initial response", depending
+        # also on whether the server capabilities, mechanism authenticator, and
+        # client adapter all support it.  Defaults to +true+.
+        #
+        # +mechanism+, +args+, +kwargs+, and +block+ are all forwarded to
+        # SASL.authenticator.  Use the +registry+ kwarg to override the global
+        # SASL::Authenticators registry.
+        def self.build(client, mechanism, *args, sasl_ir: true, **kwargs, &block)
+          authenticator = SASL.authenticator(mechanism, *args, **kwargs, &block)
+          new(client, mechanism, authenticator, sasl_ir: sasl_ir)
+        end
+
+        attr_reader :mechanism, :authenticator
+
+        def initialize(client, mechanism, authenticator, sasl_ir: true)
+          @client = client
+          @mechanism = Authenticators.normalize_name(mechanism)
+          @authenticator = authenticator
+          @sasl_ir = sasl_ir
+          @processed = false
+        end
+
+        # Call #authenticate to execute an authentication exchange for #client
+        # using #authenticator.  Authentication failures will raise an
+        # exception.  Any exceptions other than those in RESPONSE_ERRORS will
+        # drop the connection.
+        def authenticate
+          client.run_command(mechanism, initial_response) { process _1 }
+            .tap { raise AuthenticationIncomplete, _1 unless done? }
+        rescue *client.response_errors
+          raise # but don't drop the connection
+        rescue
+          client.drop_connection
+          raise
+        rescue Exception # rubocop:disable Lint/RescueException
+          client.drop_connection!
+          raise
+        end
+
+        def send_initial_response?
+          @sasl_ir &&
+            authenticator.respond_to?(:initial_response?) &&
+            authenticator.initial_response? &&
+            client.sasl_ir_capable? &&
+            client.auth_capable?(mechanism)
+        end
+
+        def done?
+          authenticator.respond_to?(:done?) ? authenticator.done? : @processed
+        end
+
+        private
+
+        attr_reader :client
+
+        def initial_response
+          return unless send_initial_response?
+          client.encode_ir authenticator.process nil
+        end
+
+        def process(challenge)
+          client.encode authenticator.process client.decode challenge
+        ensure
+          @processed = true
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Net::IMAP::SASL
+
+  # Registry for SASL authenticators
+  #
+  # Registered authenticators must respond to +#new+ or +#call+ (e.g. a class or
+  # a proc), receiving any credentials and options and returning an
+  # authenticator instance. The returned object represents a single
+  # authentication exchange and <em>must not</em> be reused for multiple
+  # authentication attempts.
+  #
+  # An authenticator instance object must respond to +#process+, receiving the
+  # server's challenge and returning the client's response.  Optionally, it may
+  # also respond to +#initial_response?+ and +#done?+.  When
+  # +#initial_response?+ returns +true+, +#process+ may be called the first
+  # time with +nil+.  When +#done?+ returns +false+, the exchange is incomplete
+  # and an exception should be raised if the exchange terminates prematurely.
+  #
+  # See the source for PlainAuthenticator, XOAuth2Authenticator, and
+  # ScramSHA1Authenticator for examples.
+  class Authenticators
+
+    # Normalize the mechanism name as an uppercase string, with underscores
+    # converted to dashes.
+    def self.normalize_name(mechanism) -(mechanism.to_s.upcase.tr(?_, ?-)) end
+
+    # Create a new Authenticators registry.
+    #
+    # This class is usually not instantiated directly.  Use SASL.authenticators
+    # to reuse the default global registry.
+    #
+    # When +use_defaults+ is +false+, the registry will start empty.  When
+    # +use_deprecated+ is +false+, deprecated authenticators will not be
+    # included with the defaults.
+    def initialize(use_defaults: true, use_deprecated: true)
+      @authenticators = {}
+      return unless use_defaults
+      add_authenticator "Anonymous"
+      add_authenticator "External"
+      add_authenticator "OAuthBearer"
+      add_authenticator "Plain"
+      add_authenticator "Scram-SHA-1"
+      add_authenticator "Scram-SHA-256"
+      add_authenticator "XOAuth2"
+      return unless use_deprecated
+      add_authenticator "Login"      # deprecated
+      add_authenticator "Cram-MD5"   # deprecated
+      add_authenticator "Digest-MD5" # deprecated
+    end
+
+    # Returns the names of all registered SASL mechanisms.
+    def names; @authenticators.keys end
+
+    # :call-seq:
+    #   add_authenticator(mechanism)
+    #   add_authenticator(mechanism, authenticator_class)
+    #   add_authenticator(mechanism, authenticator_proc)
+    #
+    # Registers an authenticator for #authenticator to use.  +mechanism+ is the
+    # name of the
+    # {SASL mechanism}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
+    # implemented by +authenticator_class+ (for instance, <tt>"PLAIN"</tt>).
+    #
+    # If +mechanism+ refers to an existing authenticator,
+    # the old authenticator will be replaced.
+    #
+    # When only a single argument is given, the authenticator class will be
+    # lazily loaded from <tt>Net::IMAP::SASL::#{name}Authenticator</tt> (case is
+    # preserved and non-alphanumeric characters are removed..
+    def add_authenticator(name, authenticator = nil)
+      authenticator ||= begin
+        class_name = "#{name.gsub(/[^a-zA-Z0-9]/, "")}Authenticator".to_sym
+        auth_class = nil
+        ->(*creds, **props, &block) {
+          auth_class ||= Net::IMAP::SASL.const_get(class_name)
+          auth_class.new(*creds, **props, &block)
+        }
+      end
+      key = Authenticators.normalize_name(name)
+      @authenticators[key] = authenticator
+    end
+
+    # Removes the authenticator registered for +name+
+    def remove_authenticator(name)
+      key = Authenticators.normalize_name(name)
+      @authenticators.delete(key)
+    end
+
+    def mechanism?(name)
+      key = Authenticators.normalize_name(name)
+      @authenticators.key?(key)
+    end
+
+    # :call-seq:
+    #   authenticator(mechanism, ...) -> auth_session
+    #
+    # Builds an authenticator instance using the authenticator registered to
+    # +mechanism+.  The returned object represents a single authentication
+    # exchange and <em>must not</em> be reused for multiple authentication
+    # attempts.
+    #
+    # All arguments (except +mechanism+) are forwarded to the registered
+    # authenticator's +#new+ or +#call+ method.  Each authenticator must
+    # document its own arguments.
+    #
+    # [Note]
+    #   This method is intended for internal use by connection protocol code
+    #   only.  Protocol client users should see refer to their client's
+    #   documentation, e.g. Net::IMAP#authenticate.
+    def authenticator(mechanism, ...)
+      key = Authenticators.normalize_name(mechanism)
+      auth = @authenticators.fetch(key) do
+        raise ArgumentError, 'unknown auth type - "%s"' % key
+      end
+      auth.respond_to?(:new) ? auth.new(...) : auth.call(...)
+    end
+    alias new authenticator
+
+  end
+
+end

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Net
+  class IMAP
+    module SASL
+
+      # This API is *experimental*, and may change.
+      #
+      # TODO: use with more clients, to verify the API can accommodate them.
+      #
+      # Represents the client to a SASL::AuthenticationExchange.  By default,
+      # most methods simply delegate to #client.  Clients should subclass
+      # SASL::ClientAdapter and override methods as needed to match the
+      # semantics of this API to their API.
+      #
+      # Subclasses should also include a protocol adapter mixin when the default
+      # ProtocolAdapters::Generic isn't sufficient.
+      #
+      # === Protocol Requirements
+      #
+      # {RFC4422 §4}[https://www.rfc-editor.org/rfc/rfc4422.html#section-4]
+      # lists requirements for protocol specifications to offer SASL.  Where
+      # possible, ClientAdapter delegates the handling of these requirements to
+      # SASL::ProtocolAdapters.
+      class ClientAdapter
+        extend Forwardable
+
+        include ProtocolAdapters::Generic
+
+        # The client that handles communication with the protocol server.
+        #
+        # Most ClientAdapter methods are simply delegated to #client by default.
+        attr_reader :client
+
+        # +command_proc+ can used to avoid exposing private methods on #client.
+        # It's value is set by the block that is passed to ::new, and it is used
+        # by the default implementation of #run_command.  Subclasses that
+        # override #run_command may use #command_proc for any other purpose they
+        # find useful.
+        #
+        # In the default implementation of #run_command, command_proc is called
+        # with the protocols authenticate +command+ name, the +mechanism+ name,
+        # an _optional_ +initial_response+ argument, and a +continuations+
+        # block.  command_proc must run the protocol command with the arguments
+        # sent to it, _yield_ the payload of each continuation, respond to the
+        # continuation with the result of each _yield_, and _return_ the
+        # command's successful result.  Non-successful results *MUST* raise
+        # an exception.
+        attr_reader :command_proc
+
+        # By default, this simply sets the #client and #command_proc attributes.
+        # Subclasses may override it, for example: to set the appropriate
+        # command_proc automatically.
+        def initialize(client, &command_proc)
+          @client, @command_proc = client, command_proc
+        end
+
+        # Attempt to authenticate #client to the server.
+        #
+        # By default, this simply delegates to
+        # AuthenticationExchange.authenticate.
+        def authenticate(...) AuthenticationExchange.authenticate(self, ...) end
+
+        ##
+        # method: sasl_ir_capable?
+        # Do the protocol, server, and client all support an initial response?
+        def_delegator :client, :sasl_ir_capable?
+
+        ##
+        # method: auth_capable?
+        # call-seq: auth_capable?(mechanism)
+        #
+        # Does the server advertise support for the +mechanism+?
+        def_delegator :client, :auth_capable?
+
+        # Calls command_proc with +command_name+ (see
+        # SASL::ProtocolAdapters::Generic#command_name),
+        # +mechanism+, +initial_response+, and a +continuations_handler+ block.
+        # The +initial_response+ is optional; when it's nil, it won't be sent to
+        # command_proc.
+        #
+        # Yields each continuation payload, responds to the server with the
+        # result of each yield, and returns the result.  Non-successful results
+        # *MUST* raise an exception.  Exceptions in the block *MUST* cause the
+        # command to fail.
+        #
+        # Subclasses that override this may use #command_proc differently.
+        def run_command(mechanism, initial_response = nil, &continuations_handler)
+          command_proc or raise Error, "initialize with block or override"
+          args = [command_name, mechanism, initial_response].compact
+          command_proc.call(*args, &continuations_handler)
+        end
+
+        ##
+        # method: host
+        # The hostname to which the client connected.
+        def_delegator :client, :host
+
+        ##
+        # method: port
+        # The destination port to which the client connected.
+        def_delegator :client, :port
+
+        # Returns an array of server responses errors raised by run_command.
+        # Exceptions in this array won't drop the connection.
+        def response_errors; [] end
+
+        ##
+        # method: drop_connection
+        # Drop the connection gracefully, sending a "LOGOUT" command as needed.
+        def_delegator :client, :drop_connection
+
+        ##
+        # method: drop_connection!
+        # Drop the connection abruptly, closing the socket without logging out.
+        def_delegator :client, :drop_connection!
+
+      end
+    end
+  end
+end

data/lib/net/imap/{authenticators/cram_md5.rb → sasl/cram_md5_authenticator.rb}

@@ -1,34 +1,45 @@
 # frozen_string_literal: true
 
 # Authenticator for the "+CRAM-MD5+" SASL mechanism, specified in
-# RFC2195[https://tools.ietf.org/html/rfc2195].  See Net::IMAP#authenticate.
+# RFC2195[https://www.rfc-editor.org/rfc/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]
+# {draft-ietf-sasl-crammd5-to-historic}[https://www.rfc-editor.org/rfc/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
+# Additionally, RFC8314[https://www.rfc-editor.org/rfc/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 Net::IMAP::CramMD5Authenticator
+class Net::IMAP::SASL::CramMD5Authenticator
+  def initialize(user = nil, pass = nil,
+                 authcid: nil, username: nil,
+                 password: nil, secret: nil,
+                 warn_deprecation: true,
+                 **)
+    if warn_deprecation
+      warn "WARNING: CRAM-MD5 mechanism is deprecated.", category: :deprecated
+    end
+    require "digest/md5"
+    @user = authcid || username || user
+    @password = password || secret || pass
+    @done = false
+  end
+
+  def initial_response?; false end
+
   def process(challenge)
     digest = hmac_md5(challenge, @password)
     return @user + " " + digest
+  ensure
+    @done = true
   end
 
-  private
+  def done?; @done end
 
-  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
-  end
+  private
 
   def hmac_md5(text, key)
     if key.length > 64
@@ -47,5 +58,4 @@ class Net::IMAP::CramMD5Authenticator
     return Digest::MD5.hexdigest(k_opad + digest)
   end
 
-  Net::IMAP.add_authenticator "CRAM-MD5", self
 end