net-imap 0.3.4 → 0.4.1

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP < Protocol
+    module SASL
+
+      # Authenticator for the "+ANONYMOUS+" SASL mechanism, as specified by
+      # RFC-4505[https://tools.ietf.org/html/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://tools.ietf.org/html/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://tools.ietf.org/html/rfc4505].  To use
+        # this, see Net::IMAP#authenticate or your client's authentication
+        # method.
+        #
+        # #anonymous_message is an optional message which is sent to the server.
+        # It may be sent as a positional argument or as a keyword argument.
+        #
+        # 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,107 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    module SASL
+
+      # This API is *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.
+      #
+      # Create an AuthenticationExchange from a client adapter and a mechanism
+      # authenticator:
+      #     def authenticate(mechanism, ...)
+      #       authenticator = SASL.authenticator(mechanism, ...)
+      #       SASL::AuthenticationExchange.new(
+      #         sasl_adapter, mechanism, authenticator
+      #       ).authenticate
+      #     end
+      #
+      #     private
+      #
+      #     def sasl_adapter = MyClientAdapter.new(self, &method(:send_command))
+      #
+      # Or delegate creation of the authenticator to ::build:
+      #     def authenticate(...)
+      #       SASL::AuthenticationExchange.build(sasl_adapter, ...)
+      #         .authenticate
+      #     end
+      #
+      # As a convenience, ::authenticate combines ::build and #authenticate:
+      #     def authenticate(...)
+      #       SASL::AuthenticationExchange.authenticate(sasl_adapter, ...)
+      #     end
+      #
+      # Likewise, ClientAdapter#authenticate delegates to #authenticate:
+      #     def authenticate(...) = sasl_adapter.authenticate(...)
+      #
+      class AuthenticationExchange
+        # Convenience method for <tt>build(...).authenticate</tt>
+        def self.authenticate(...) build(...).authenticate end
+
+        # Use +registry+ to override the global 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 = -mechanism.to_s.upcase.tr(?_, ?-)
+          @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,118 @@
+# 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
+
+    # 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, a warning will be
+    # printed and 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)
+      key = -name.to_s.upcase.tr(?_, ?-)
+      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
+      @authenticators[key] = authenticator
+    end
+
+    # Removes the authenticator registered for +name+
+    def remove_authenticator(name)
+      key = -name.to_s.upcase.tr(?_, ?-)
+      @authenticators.delete(key)
+    end
+
+    def mechanism?(name)
+      key = -name.to_s.upcase.tr(?_, ?-)
+      @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 = -mechanism.to_s.upcase.tr(?_, ?-)
+      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,72 @@
+# frozen_string_literal: true
+
+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.
+      #
+      # An abstract base class for implementing a SASL authentication exchange.
+      # Different clients will each have their own adapter subclass, overridden
+      # to match their needs.
+      #
+      # Although the default implementations _may_ be sufficient, subclasses
+      # will probably need to override some methods.  Additionally, subclasses
+      # may need to include a protocol adapter mixin, if the default
+      # ProtocolAdapters::Generic isn't sufficient.
+      class ClientAdapter
+        include ProtocolAdapters::Generic
+
+        attr_reader :client, :command_proc
+
+        # +command_proc+ can used to avoid exposing private methods on #client.
+        # It should run a command with the arguments sent to it, yield each
+        # continuation payload, respond to the server with the result of each
+        # yield, and return the result.  Non-successful results *MUST* raise an
+        # exception.  Exceptions in the block *MUST* cause the command to fail.
+        #
+        # Subclasses that override #run_command may use #command_proc for
+        # other purposes.
+        def initialize(client, &command_proc)
+          @client, @command_proc = client, command_proc
+        end
+
+        # Delegates to AuthenticationExchange.authenticate.
+        def authenticate(...) AuthenticationExchange.authenticate(self, ...) end
+
+        # Do the protocol and server both support an initial response?
+        def sasl_ir_capable?; client.sasl_ir_capable? end
+
+        # Does the server advertise support for the mechanism?
+        def auth_capable?(mechanism); client.auth_capable?(mechanism) end
+
+        # Runs the authenticate command with +mechanism+ and +initial_response+.
+        # When +initial_response+ is nil, an initial response must NOT be sent.
+        #
+        # 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, &block)
+          command_proc or raise Error, "initialize with block or override"
+          args = [command_name, mechanism, initial_response].compact
+          command_proc.call(*args, &block)
+        end
+
+        # Returns an array of server responses errors raised by run_command.
+        # Exceptions in this array won't drop the connection.
+        def response_errors; [] end
+
+        # Drop the connection gracefully.
+        def drop_connection;  client.drop_connection end
+
+        # Drop the connection abruptly.
+        def drop_connection!; client.drop_connection! end
+      end
+    end
+  end
+end

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

@@ -13,14 +13,7 @@
 # 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 Net::IMAP::CramMD5Authenticator
-  def process(challenge)
-    digest = hmac_md5(challenge, @password)
-    return @user + " " + digest
-  end
-
-  private
-
+class Net::IMAP::SASL::CramMD5Authenticator
   def initialize(user, password, warn_deprecation: true, **_ignored)
     if warn_deprecation
       warn "WARNING: CRAM-MD5 mechanism is deprecated." # TODO: recommend SCRAM
@@ -28,8 +21,22 @@ class Net::IMAP::CramMD5Authenticator
     require "digest/md5"
     @user = user
     @password = password
+    @done = false
+  end
+
+  def initial_response?; false end
+
+  def process(challenge)
+    digest = hmac_md5(challenge, @password)
+    return @user + " " + digest
+  ensure
+    @done = true
   end
 
+  def done?; @done end
+
+  private
+
   def hmac_md5(text, key)
     if key.length > 64
       key = Digest::MD5.digest(key)
@@ -47,5 +54,4 @@ class Net::IMAP::CramMD5Authenticator
     return Digest::MD5.hexdigest(k_opad + digest)
   end
 
-  Net::IMAP.add_authenticator "CRAM-MD5", self
 end

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

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+# Net::IMAP authenticator for the "`DIGEST-MD5`" SASL mechanism type, specified
+# in RFC-2831[https://tools.ietf.org/html/rfc2831].  See Net::IMAP#authenticate.
+#
+# == Deprecated
+#
+# "+DIGEST-MD5+" has been deprecated by
+# RFC-6331[https://tools.ietf.org/html/rfc6331] and should not be relied on for
+# security.  It is included for compatibility with existing servers.
+class Net::IMAP::SASL::DigestMD5Authenticator
+  STAGE_ONE = :stage_one
+  STAGE_TWO = :stage_two
+  STAGE_DONE = :stage_done
+  private_constant :STAGE_ONE, :STAGE_TWO, :STAGE_DONE
+
+  # 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
+  # that to +authcid+.  So +authcid+ is available as an alias for #username.
+  attr_reader :username
+
+  # A password or passphrase that matches the #username.
+  #
+  # The +password+ will be used to create the response digest.
+  attr_reader :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.
+  # 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.
+  #
+  # For example, an administrator or superuser might take on another role:
+  #
+  #     imap.authenticate "DIGEST-MD5", "root", ->{passwd}, authzid: "user"
+  #
+  attr_reader :authzid
+
+  # :call-seq:
+  #   new(username,  password,  authzid = nil, **options) -> authenticator
+  #   new(username:, password:, authzid:  nil, **options) -> authenticator
+  #
+  # Creates an Authenticator for the "+DIGEST-MD5+" SASL mechanism.
+  #
+  # Called by Net::IMAP#authenticate and similar methods on other clients.
+  #
+  # ==== Parameters
+  #
+  # * #username — Identity whose #password is used.
+  # * #password — A password or passphrase associated with this #username.
+  # * #authzid ― Alternate identity to act as or on behalf of.  Optional.
+  # * +warn_deprecation+ — Set to +false+ to silence the warning.
+  #
+  # See the documentation for each attribute for more details.
+  def initialize(user = nil, pass = nil, authz = nil,
+                 username: nil, password: nil, authzid: nil,
+                 warn_deprecation: true, **)
+    username ||= user or raise ArgumentError, "missing username"
+    password ||= pass or raise ArgumentError, "missing password"
+    authzid  ||= authz
+    if warn_deprecation
+      warn "WARNING: DIGEST-MD5 SASL mechanism was deprecated by RFC6331."
+      # TODO: recommend SCRAM instead.
+    end
+    require "digest/md5"
+    require "strscan"
+    @username, @password, @authzid = username, password, authzid
+    @nc, @stage = {}, STAGE_ONE
+  end
+
+  def initial_response?; false end
+
+  # Responds to server challenge in two stages.
+  def process(challenge)
+    case @stage
+    when STAGE_ONE
+      @stage = STAGE_TWO
+      sparams = {}
+      c = StringScanner.new(challenge)
+      while c.scan(/(?:\s*,)?\s*(\w+)=("(?:[^\\"]|\\.)*"|[^,]+)\s*/)
+        k, v = c[1], c[2]
+        if v =~ /^"(.*)"$/
+          v = $1
+          if v =~ /,/
+            v = v.split(',')
+          end
+        end
+        sparams[k] = v
+      end
+
+      raise Net::IMAP::DataFormatError, "Bad Challenge: '#{challenge}'" unless c.eos? and sparams['qop']
+      raise Net::IMAP::Error, "Server does not support auth (qop = #{sparams['qop'].join(',')})" unless sparams['qop'].include?("auth")
+
+      response = {
+        :nonce => sparams['nonce'],
+        :username => @username,
+        :realm => sparams['realm'],
+        :cnonce => Digest::MD5.hexdigest("%.15f:%.15f:%d" % [Time.now.to_f, rand, Process.pid.to_s]),
+        :'digest-uri' => 'imap/' + sparams['realm'],
+        :qop => 'auth',
+        :maxbuf => 65535,
+        :nc => "%08d" % nc(sparams['nonce']),
+        :charset => sparams['charset'],
+      }
+
+      response[:authzid] = @authzid unless @authzid.nil?
+
+      # now, the real thing
+      a0 = Digest::MD5.digest( [ response.values_at(:username, :realm), @password ].join(':') )
+
+      a1 = [ a0, response.values_at(:nonce,:cnonce) ].join(':')
+      a1 << ':' + response[:authzid] unless response[:authzid].nil?
+
+      a2 = "AUTHENTICATE:" + response[:'digest-uri']
+      a2 << ":00000000000000000000000000000000" if response[:qop] and response[:qop] =~ /^auth-(?:conf|int)$/
+
+      response[:response] = Digest::MD5.hexdigest(
+        [
+          Digest::MD5.hexdigest(a1),
+          response.values_at(:nonce, :nc, :cnonce, :qop),
+          Digest::MD5.hexdigest(a2)
+        ].join(':')
+      )
+
+      return response.keys.map {|key| qdval(key.to_s, response[key]) }.join(',')
+    when STAGE_TWO
+      @stage = STAGE_DONE
+      # if at the second stage, return an empty string
+      if challenge =~ /rspauth=/
+        return ''
+      else
+        raise ResponseParseError, challenge
+      end
+    else
+      raise ResponseParseError, challenge
+    end
+  end
+
+  def done?; @stage == STAGE_DONE end
+
+  private
+
+  def nc(nonce)
+    if @nc.has_key? nonce
+      @nc[nonce] = @nc[nonce] + 1
+    else
+      @nc[nonce] = 1
+    end
+    return @nc[nonce]
+  end
+
+  # some responses need quoting
+  def qdval(k, v)
+    return if k.nil? or v.nil?
+    if %w"username authzid realm nonce cnonce digest-uri qop".include? k
+      v = v.gsub(/([\\"])/, "\\\1")
+      return '%s="%s"' % [k, v]
+    else
+      return '%s=%s' % [k, v]
+    end
+  end
+
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP < Protocol
+    module SASL
+
+      # Authenticator for the "+EXTERNAL+" SASL mechanism, as specified by
+      # RFC-4422[https://tools.ietf.org/html/rfc4422].  See
+      # Net::IMAP#authenticate.
+      #
+      # The EXTERNAL mechanism requests that the server use client credentials
+      # established external to SASL, for example by TLS certificate or IPsec.
+      class ExternalAuthenticator
+
+        # Authorization identity: an identity to act as or on behalf of.
+        #
+        # If not explicitly provided, the server defaults to using the identity
+        # that was authenticated by the external credentials.
+        attr_reader :authzid
+
+        # :call-seq:
+        #   new(authzid: nil, **) -> authenticator
+        #
+        # Creates an Authenticator for the "+EXTERNAL+" SASL mechanism, as
+        # specified in RFC-4422[https://tools.ietf.org/html/rfc4422].  To use
+        # this, see Net::IMAP#authenticate or your client's authentication
+        # method.
+        #
+        # #authzid is an optional identity to act as or on behalf of.
+        #
+        # Any other keyword parameters are quietly ignored.
+        def initialize(authzid: nil, **)
+          @authzid = authzid&.to_str&.encode "UTF-8"
+          if @authzid&.match?(/\u0000/u) # also validates UTF8 encoding
+            raise ArgumentError, "contains NULL"
+          end
+          @done = false
+        end
+
+        # :call-seq:
+        #   initial_response? -> true
+        #
+        # +EXTERNAL+ can send an initial client response.
+        def initial_response?; true end
+
+        # Returns #authzid, or an empty string if there is no authzid.
+        def process(_)
+          authzid || ""
+        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